Subscriptions

Subscription lifecycle from creation through agreement signing, review, payment, and escrow completion.

A subscription represents an investor's commitment to purchase securities in an offering. The lifecycle covers agreement signing, compliance review, post-approval payment, and completion when funds reach escrow.

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

Prerequisites

The authenticated user must have an approved org-scoped KYC verification before creating a subscription, signing an agreement, or having a subscription approved. Primary Issuance checks live eligibility with Identity for the offering's organization, so tokens may contain kyc_completed for convenience but are not the source of truth for subscription gating. If KYC is not approved, the API returns a 403 error with code KYC_REQUIRED. See KYC & Accreditation for how to complete KYC.

Subscription Lifecycle

CREATE                 SIGN & CONFIGURE         SUBMIT FOR REVIEW      ADMIN DECISION      ESCROW
  │                        │                        │                       │                  │
  ▼                        ▼                        ▼                       ▼                  ▼
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,
    "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: Link a Payment Method and Submit for Review

For card or ACH, create a Stripe setup session to save a payment method without charging it:

curl -X POST https://api.rialto.com/issuance/subscriptions/<subscription_id>/create-setup-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` or `us_bank_account`
`successUrl`	Yes	URL	Redirect URL after the investor completes payment-method setup
`cancelUrl`	Yes	URL	Redirect URL if the investor cancels payment-method setup

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, then finalize the setup and submit the subscription:

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

curl -X POST https://api.rialto.com/issuance/subscriptions/<subscription_id>/submit-for-review \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{}'

Wire/check subscriptions select their payment method and submit without a Stripe setup session. Pass the chosen method in the submit-for-review body:

curl -X POST https://api.rialto.com/issuance/subscriptions/<subscription_id>/submit-for-review \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{ "paymentMethod": "wire" }'

Use "wire" or "check". No funds are collected before approval. The submitted subscription response includes a reference_code; show it to the investor and include it in wire/check instructions so staff can reconcile the payment when funds arrive.

Step 4: Wait for Review

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

subscription.approved -- subscription approved; payment can now be collected
subscription.rejected -- subscription rejected with a reason

Step 5: Funds Reach Escrow

After approval, Rialto collects card/ACH payments or staff reconciles wire/check payments. The subscription moves to completed only when the funds reach escrow. At that point, offering amount and investor counters are updated and both a subscription.funded and a subscription.completed webhook event are published.

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`	Linking payment method; no charge yet	Yes
`pending_review`	Submitted for review; no funds collected yet	No
`approved`	Approved, awaiting escrow settlement	No
`rejected`	Rejected by compliance	No
`cancelled`	Cancelled by investor	--
`voided`	Subscription agreement voided by admin	No
`completed`	Funds reached escrow; deal is complete	No

Payment Statuses

Status	Description
`pending`	No payment attempt yet
`processing`	Payment in flight
`received`	Payment captured; awaiting escrow settlement
`in_escrow`	Funds reached escrow; subscription is completed
`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 status reached `in_escrow`
`subscription.approved`	Approved after review
`subscription.rejected`	Rejected by compliance
`subscription.completed`	Subscription closed; counters updated
`subscription.cancelled`	Subscription cancelled
`subscription.info_requested`	Additional info requested from investor
`subscription.voided`	Subscription agreement voided

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. Link a payment method without charging it
const setup = await createSetupSession(subscription.id, {
  paymentMethod: "card",
  successUrl: "https://yourapp.com/success",
  cancelUrl: "https://yourapp.com/cancel",
});
window.location.href = setup.session_url;

// 5. After Stripe redirects back to successUrl, finalize the setup and submit for review
await finalizeSetup(subscription.id);
await submitForReview(subscription.id);

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

Subscriptions

On this page