Create subscription

POST/v1/payments/subscriptionsRun in dashboard

The customer must still sign the Solana subscription authorization transaction. The subscriber must be the customer's own wallet: a subscriber that is one of the organization's SDP wallets answers 409, because to pay on a schedule from an SDP wallet you create a recurring payment, which keeps the wallet's token approval bounded.

Requires an API key with the recurring.manage action.

HeadersCopy Anchor Link

• x-project-id · string · min length 1 · example prj_example

  Required for dashboard sessions. API keys use their assigned project.

• Idempotency-Key · string

  Use a unique 1–255 printable ASCII key per operation. Reuse it with the same request on retries. An in-flight attempt returns 409; a changed request returns 422. Retry and recovery rules.

Request bodyCopy Anchor Link

application/json · required

Creates a pending SDP subscription record tied to a counterparty. Lifecycle, schedule, on-chain addresses, and authorization proof are server-owned and populated only by verified flows.

• planId · string · required · min length 1 · example psp_example

  SDP subscription plan ID.

• counterpartyId · string · required · min length 1 · example cpty_example

  Counterparty being billed for the recurring payment.

• subscriberAddress · string · required · example 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

  Customer wallet address that authorizes the subscription.

ResponsesCopy Anchor Link

• 201 Subscription created

  • data · object · required

    Subscription response payload.

    • subscription · object · required

      Recurring payment subscription record.

      • id · string · required · example psub_example

        SDP subscription ID.

      • organizationId · string · required · min length 1 · example org_example

        Organization identifier.

      • projectId · string · required · min length 1 · example prj_example

        Project identifier.

      • planId · string · required

        SDP subscription plan ID.

      • counterpartyId · string · required

        Counterparty ID.

      • subscriberAddress · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        Base58-encoded Solana address.

      • subscriberTokenAccount · string | null · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        Subscriber token account address.

      • subscriptionPda · string | null · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        On-chain subscription PDA.

      • subscriptionAuthorityAddress · string | null · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        On-chain subscription authority address.

      • authorizationSignature · string | null · required

        Customer authorization transaction signature.

      • status · string · required · one of pending_authorization, active, paused, canceling, canceled, expired · example active

        Subscription status.

      • currentPeriodStartAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

      • nextCollectionDueAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

      • cancelAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

      • canceledAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

      • createdBy · string | null · required

      • createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

      • updatedAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

  • meta · object · required

    Response metadata.

    • requestId · string · required · min length 1 · example req_example

      Request identifier for tracing.

    • timestamp · string · required · format date-time · example 2025-01-01T00:00:00.000Z

      ISO 8601 timestamp.

• 400 Bad Request

  • error · object · required

    Standard error payload.

    • code · string · required

      Machine-readable error code.

    • message · string · required

      Human-readable error message.

    • details · object

      Optional error details for debugging.

      • * · any

  • meta · object

    • requestId · string · min length 1 · example req_example

      Request identifier for tracing.

• 401 Unauthorized

  Same fields as 400.

• 403 Forbidden. Requires the recurring.manage action: an API key must hold it (a module's manage or execute also covers its read), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and error.details.action names the action. Any other 403 names its own reason.

  Same fields as 400.

• 404 Not Found

  Same fields as 400.

• 409 Conflict

  Same fields as 400.

• 422 Unprocessable Entity

  Same fields as 400.

• 500 Internal Server Error

  Same fields as 400.