Subscriptions

Subscription lifecycle from creation through agreement signing, payment, review, and share issuance.

A subscription represents an investor's commitment to purchase securities in an offering. The subscription lifecycle takes the investor from initial commitment through agreement signing, payment, compliance review, and share issuance.

All endpoints are under the /issuance prefix and require a Rialto access_token (Bearer).

Prerequisites

The authenticated user must have KYC completed (kyc_completed = true in their token claims) before creating a subscription, signing an agreement, or having a subscription approved. If KYC is not completed, the API returns a 403 error with code KYC_REQUIRED. See KYC & Accreditation for how to complete KYC.

Subscription Lifecycle

CREATE                 SIGN AGREEMENT           PAY                    ADMIN REVIEW        SHARES
  │                        │                     │                        │                  │
  ▼                        ▼                     ▼                        ▼                  ▼
draft ──► pending_signature ──► pending_payment ──► pending_review ──► approved ──► completed
                                                                          │
                                                                          ▼
                                                                       rejected

Cancellable states: draft, pending_signature, pending_payment

Step 1: Create a Subscription

curl -X POST https://api.rialto.com/issuance/offerings/<offering_id>/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{
    "securityClassId": "d4e5f6a7-...",
    "unitsSubscribed": 1000,
    "paymentMethod": "card",
    "suitabilityConfirmed": true,
    "riskAcknowledgmentSigned": true
  }'

Request Body:

Field	Required	Type	Description
`securityClassId`	Yes	UUID	The security class to subscribe to
`unitsSubscribed`	Yes	number (>0)	Number of units to purchase
`trancheId`	No	UUID	Specific tranche (if applicable)
`paymentMethod`	No	string	Preferred payment method
`accreditationStatus`	No	string	Self-reported accreditation status
`suitabilityConfirmed`	No	boolean	Investor suitability confirmed
`riskAcknowledgmentSigned`	No	boolean	Risk acknowledgment signed

Payment Methods: card, us_bank_account, crypto, wire, other

Response (201):

{
  "success": true,
  "data": {
    "id": "e5f6a7b8-...",
    "offering_id": "a1b2c3d4-...",
    "security_class_id": "d4e5f6a7-...",
    "units_subscribed": 1000,
    "price_per_unit": "10.00",
    "total_amount": "10000.00",
    "currency": "USD",
    "payment_status": "pending",
    "subscription_agreement_signed": false,
    "status": "draft",
    "signed_at": null,
    "shares_id": null,
    "shares_issued_at": null,
    "created_at": "2026-03-15T10:30:00.000Z",
    "updated_at": "2026-03-15T10:30:00.000Z"
  }
}

Step 2: Sign the Subscription Agreement

After creating a subscription, the investor must sign the subscription agreement:

curl -X POST https://api.rialto.com/issuance/subscriptions/<subscription_id>/sign-agreement \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{
    "signature": "John Doe",
    "signedAt": "2026-03-15T10:35:00.000Z",
    "ipAddress": "203.0.113.42"
  }'

Request Body:

Field	Required	Type	Description
`signature`	Yes	string	Digital signature (investor's name)
`signedAt`	Yes	ISO 8601	Timestamp of signing
`ipAddress`	No	IPv4	IP address of signer

After signing, the subscription moves to pending_payment.

Step 3: Create a Checkout Session

Initiate payment via Stripe Checkout:

curl -X POST https://api.rialto.com/issuance/subscriptions/<subscription_id>/create-checkout-session \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{
    "paymentMethod": "card",
    "successUrl": "https://yourapp.com/subscription/success",
    "cancelUrl": "https://yourapp.com/subscription/cancel"
  }'

Request Body:

Field	Required	Type	Description
`paymentMethod`	Yes	string	`card`, `us_bank_account`, `crypto`, `wire`, `other`
`successUrl`	Yes	URL	Redirect URL on successful payment
`cancelUrl`	Yes	URL	Redirect URL on cancelled payment

Response:

{
  "success": true,
  "data": {
    "session_id": "cs_live_abc123...",
    "session_url": "https://checkout.stripe.com/c/pay/cs_live_abc123..."
  }
}

Redirect the investor to session_url to complete payment. After payment:

Success: Stripe sends a webhook, the subscription moves to pending_review
Failure: Payment status is set to failed, subscription stays in pending_payment (investor can retry)

Step 4: Wait for Review

After payment, the subscription enters pending_review for compliance review by Rialto staff. You'll be notified of the outcome via webhook:

subscription.approved -- subscription approved, shares will be issued
subscription.rejected -- subscription rejected with a reason

Step 5: Shares Issued

Once approved, Rialto staff issues shares and the subscription moves to completed. You'll receive:

subscription.completed webhook event
shares.issued webhook event

The subscription response will include shares_id and shares_issued_at.

Listing Subscriptions

curl https://api.rialto.com/issuance/subscriptions \
  -H "Authorization: Bearer <rialto_access_token>"

Returns all subscriptions for the authenticated user.

Getting a Subscription

curl https://api.rialto.com/issuance/subscriptions/<subscription_id> \
  -H "Authorization: Bearer <rialto_access_token>"

Cancelling a Subscription

Subscriptions can be cancelled while in draft, pending_signature, or pending_payment:

curl -X DELETE https://api.rialto.com/issuance/subscriptions/<subscription_id> \
  -H "Authorization: Bearer <rialto_access_token>"

Returns 204 No Content on success.

Subscription Statuses

Status	Description	Can Cancel?
`draft`	Initial state, just created	Yes
`pending_signature`	Awaiting agreement signature	Yes
`pending_payment`	Awaiting payment	Yes
`pending_review`	Payment received, under compliance review	No
`approved`	Approved, awaiting share issuance	No
`rejected`	Rejected by compliance	No
`cancelled`	Cancelled by investor	--
`voided`	Subscription agreement voided by admin	No
`completed`	Shares issued, fully complete	No

Payment Statuses

Status	Description
`pending`	No payment attempt yet
`processing`	Payment in flight
`received`	Payment captured successfully (required for share issuance)
`failed`	Payment declined (investor can retry)
`refunded`	Payment refunded
`disputed`	Payment dispute filed

Subscription Events

Subscribe to these via webhooks for real-time updates:

Event	When it fires
`subscription.created`	Subscription created
`subscription.signed`	Agreement signed
`subscription.funded`	Payment received
`subscription.approved`	Approved after review
`subscription.rejected`	Rejected by compliance
`subscription.completed`	Shares issued
`subscription.cancelled`	Subscription cancelled
`subscription.info_requested`	Additional info requested from investor
`subscription.voided`	Subscription agreement voided
`shares.issued`	Shares created from subscription

Typical Integration Pattern

// 1. User selects an offering and security class
const offering = await getOffering(offeringId);
const securities = await getOfferingSecurities(offeringId);

// 2. Create subscription
const subscription = await createSubscription(offeringId, {
  securityClassId: securities[0].id,
  unitsSubscribed: 1000,
  suitabilityConfirmed: true,
  riskAcknowledgmentSigned: true,
});

// 3. Sign agreement
await signAgreement(subscription.id, {
  signature: "John Doe",
  signedAt: new Date().toISOString(),
});

// 4. Create checkout session and redirect
const checkout = await createCheckoutSession(subscription.id, {
  paymentMethod: "card",
  successUrl: "https://yourapp.com/success",
  cancelUrl: "https://yourapp.com/cancel",
});
window.location.href = checkout.session_url;

// 5. Handle webhook for completion
// POST /your-webhook-endpoint
// event_type: "subscription.completed"

Subscriptions

On this page