Prepare subscription collection

Prepares the collector-signed Solana subscriptions transfer transaction for an active subscription.

POST/v1/payments/subscriptions/{subscriptionId}/prepare-collectionRun in dashboard

The transaction must still be signed and submitted by the collector/fee-payer flow. A subscription that belongs to a recurring payment, or whose subscriber is one of the organization's SDP wallets, answers 409: SDP collects from an SDP wallet only through a recurring payment.

Requires an API key with the recurring.execute action.

Path parameters

subscriptionId · string · required · min length 1 · example psub_example

SDP subscription record ID.

Headers

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

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

Request body

application/json · required

Inputs for preparing the collector-signed Solana subscriptions transfer transaction. The amount is always derived from the stored plan.

receiverTokenAccount · string · required · example 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

Receiver token account for the pulled subscription payment. It must be allowed by the on-chain plan.

Responses

200 Subscription collection prepared
- data · object · required
  
  Prepared subscription collection 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.
  - preparedTransaction · object · required
    
    Unsigned Solana subscriptions transaction payload for client-side signing.
    - serialized · string · required · min length 1 · example AQID
      
      Base64-encoded unsigned transaction.
    - blockhash · string · required · example blockhash_example
      
      Blockhash for the transaction.
    - lastValidBlockHeight · string · required · example 123456
      
      Last valid block height.
    - requiredSigners · string[] · required · each min length 32 · each max length 44 · each example So11111111111111111111111111111111111111112
      
      Addresses that must sign the prepared transaction. This includes the sponsored fee payer when the transaction uses one.
  - collectionAttempt · object
    
    Recurring payment collection attempt record.
    - id · string · required · example psca_example
      
      Collection attempt ID.
    - organizationId · string · required · min length 1 · example org_example
      
      Organization identifier.
    - projectId · string · required · min length 1 · example prj_example
      
      Project identifier.
    - subscriptionId · string · required
      
      Subscription ID.
    - transferId · string | null · required · min length 1 · example xfr_example
      
      Payment transfer record ID when linked.
    - token · string · required
      
      Token mint or normalized token identifier.
    - amount · string · required · example 100.00
      
      Token amount in UI units (decimal string).
    - dueAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      ISO 8601 timestamp.
    - attemptedAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      ISO 8601 timestamp.
    - status · string · required · one of pending, processing, confirmed, failed, skipped · example pending
      
      Collection attempt status.
    - signature · string | null · required
      
      Solana transaction signature.
    - error · string | null · required · example The wallet used for this payment does not have enough funds. Add funds and try again.
      
      Why the collection failed, if it did. A source wallet that cannot cover the amount records the same text the collect request returned with 400 TRANSACTION_FAILED.
    - metadata · object · required
      
      Provider/job metadata for the attempt.
      
      One of:
      - source: "manual"
        
        recurringPaymentId · string · required
        
        initiatedByKeyId · string | null · required
        
        source · string · required · always manual
      - source: "automated"
        
        recurringPaymentId · string · required
        
        initiatedByKeyId · string | null · required
        
        source · string · required · always automated
      - source: "retry"
        
        recurringPaymentId · string · required
        
        initiatedByKeyId · string | null · required
        
        source · string · required · always retry
        
        initialSource · string · required · one of manual, automated
        
        transferId · string | null · required
        
        error · string · required
        
        retryAfterAt · string · required
      - source: "linked_transfer"
        
        recurringPaymentId · string · required
        
        initiatedByKeyId · string | null · required
        
        source · string · required · always linked_transfer
        
        initialSource · string · required · one of manual, automated
        
        transferId · string · 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.execute 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.
500 Internal Server Error

Same fields as 400.
503 Service Unavailable

Same fields as 400.

Example request

curl -X POST 'https://api-beta.solana.com/v1/payments/subscriptions/psub_example/prepare-collection' \
  -H "Authorization: Bearer $SDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverTokenAccount": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  }'

const res = await fetch("https://api-beta.solana.com/v1/payments/subscriptions/psub_example/prepare-collection", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SDP_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "receiverTokenAccount": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  })
});

import os, requests

r = requests.post("https://api-beta.solana.com/v1/payments/subscriptions/psub_example/prepare-collection",
  headers={"Authorization": f"Bearer {os.environ['SDP_API_KEY']}"},
  json={
    "receiverTokenAccount": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  })

Example responses

JSON

{
  "data": {
    "subscription": {
      "id": "psub_example",
      "organizationId": "org_example",
      "projectId": "prj_example",
      "planId": "plan_example",
      "counterpartyId": "counterparty_example",
      "subscriberAddress": "So11111111111111111111111111111111111111112",
      "subscriberTokenAccount": "So11111111111111111111111111111111111111112",
      "subscriptionPda": "So11111111111111111111111111111111111111112",
      "subscriptionAuthorityAddress": "So11111111111111111111111111111111111111112",
      "authorizationSignature": "example",
      "status": "active",
      "currentPeriodStartAt": "2025-01-01T00:00:00.000Z",
      "nextCollectionDueAt": "2025-01-01T00:00:00.000Z",
      "cancelAt": "2025-01-01T00:00:00.000Z",
      "canceledAt": "2025-01-01T00:00:00.000Z",
      "createdBy": "example",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    },
    "preparedTransaction": {
      "serialized": "AQID",
      "blockhash": "blockhash_example",
      "lastValidBlockHeight": "123456",
      "requiredSigners": [
        "So11111111111111111111111111111111111111112"
      ]
    },
    "collectionAttempt": {
      "id": "psca_example",
      "organizationId": "org_example",
      "projectId": "prj_example",
      "subscriptionId": "subscription_example",
      "transferId": "xfr_example",
      "token": "example",
      "amount": "100.00",
      "dueAt": "2025-01-01T00:00:00.000Z",
      "attemptedAt": "2025-01-01T00:00:00.000Z",
      "status": "pending",
      "signature": "example",
      "error": "The wallet used for this payment does not have enough funds. Add funds and try again.",
      "metadata": {
        "recurringPaymentId": "recurringpayment_example",
        "initiatedByKeyId": "initiatedbykey_example",
        "source": "manual"
      },
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

JSON

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Missing action: recurring.execute",
    "details": {
      "action": "recurring.execute"
    }
  },
  "meta": {
    "requestId": "req_example"
  }
}

Error responses use the standard error shape.

Prepare subscription collection

Path parametersCopy Anchor Link

HeadersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Example requestCopy Anchor Link