Collect recurring payment

Manually starts a due active SDP-custody recurring payment collection, creating a linked payment transfer and collection attempt.

POST/v1/payments/recurring-payments/{id}/collectRun in dashboard

When admitting a new collection, SDP requires an active counterparty and account in the schedule's project. Archival that commits before admission prevents a new collection from signing. If either recipient record is archived or unavailable, the schedule pauses with pausedReason destination_unavailable and the request returns 409 without signing. That 409, and every later collect or resume while the recipient stays unavailable, tells the caller to cancel the schedule and create a new one. A collection admitted earlier may still finish or recover.

If submission cannot be confirmed immediately, a 200 response returns the same transfer as processing with its known signature; reconciliation settles it, and the next due time advances only after exact on-chain confirmation.

When the source wallet cannot cover the amount, the request returns 400 TRANSACTION_FAILED, and the failed collection attempt and its transfer record the same reason in error, so the collection history shows why.

Requires an API key with the recurring.execute action.

Path parameters

id · string · required · min length 1 · example prp_example

SDP recurring payment record ID.

Headers

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

Required for dashboard sessions. API keys use their assigned project.
Idempotency-Key · string · required

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.

Responses

200 Recurring payment collection result
- data · object · required
  
  Recurring payment collection response payload.
  - recurringPayment · object · required
    
    SDP-custody outbound recurring payment record.
    - id · string · required · example prp_example
      
      SDP recurring payment ID.
    - organizationId · string · required · min length 1 · example org_example
      
      Organization identifier.
    - projectId · string · required · min length 1 · example prj_example
      
      Project identifier.
    - sourceCustodyWalletId · string | null · required · example cwlt_example
      
      Exact source SDP Wallet ID, or null for unresolved legacy records.
    - sourceProviderWalletId · string · required · min length 1 · example privy_wallet_123
      
      Source Provider wallet ID retained as evidence.
    - sourceAddress · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Source wallet address.
    - counterpartyId · string · required · example cpty_example
      
      Counterparty ID.
    - counterpartyAccountId · string · required · example cpacct_example
      
      Counterparty account ID.
    - destinationAddress · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Counterparty wallet owner address.
    - destinationTokenAccount · string | null · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Derived counterparty token account used for collection.
    - token · string · required
      
      SPL token mint address.
    - amount · string · required · example 100.00
      
      Token amount in UI units (decimal string).
    - periodHours · integer · required · greater than 0 · example 720
    - firstCollectionAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      Requested first collection timestamp.
    - nextCollectionDueAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      Next due collection timestamp.
    - planId · string | null · required
      
      Linked SDP subscription plan ID.
    - subscriptionId · string | null · required
      
      Linked SDP subscription ID.
    - planPda · string | null · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      On-chain plan PDA.
    - planCreatedAt · string | null · required
      
      On-chain plan createdAt value as an unsigned integer string.
    - planCreationSignature · string | null · required
      
      Solana signature for plan creation.
    - 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
      
      Solana signature for subscription authorization.
    - status · string · required · one of pending_activation, activating, active, updating, canceling, resuming, paused, canceled, expired · example active
      
      Recurring payment status.
    - pausedReason · string | null · required · one of custody_policy_refused, failed_attempts, destination_unavailable · example null
      
      Why SDP paused the recurring payment, set exactly while status is paused: custody_policy_refused when the custody provider's policy refused to sign a collection, failed_attempts when one due period failed 5 times, or destination_unavailable when its counterparty or account is archived or unavailable in the project. Resume requires an active recipient and clears the reason.
    - metadataUri · string | null · required
      
      Optional plan metadata URI.
    - createdBy · string | null · required
      
      Creator user ID or API key ID.
    - 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.
  - collectionAttempt · object · required
    
    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.
  - transfer · object · required
    
    Transfer transaction record.
    - fireblocks · object
      
      Native Fireblocks transfer tracking. A processing payment may await approval in Fireblocks; network fees are paid by its source vault. A missing transaction ID means submission is still being reconciled. Do not create a replacement payment while its outcome is unknown.
      - transactionId · string | null · required
      - status · string · required
      - subStatus · string | null · required
    - id · string · required · min length 1 · example xfr_example
      
      Transfer identifier (SDP record ID, not the on-chain signature).
    - organizationId · string · required · min length 1 · example org_example
      
      Organization identifier.
    - custodyWalletId · string | null · required · example cwlt_example
      
      Exact SDP Wallet ID associated with the persisted transfer, or null for unresolved legacy and observed rows.
    - providerWalletId · string · required · min length 1 · example privy_wallet_123
      
      Provider wallet ID retained as evidence; not an execution selector.
    - projectId · string · min length 1 · example prj_example
      
      Project identifier for the transfer.
    - type · string · required · example transfer
      
      Transfer type.
    - kind · string · required
      
      Dashboard transaction kind derived from the transfer type and originating Payments resource.
    - direction · string · required · one of inbound, outbound · example outbound
      
      Transfer direction.
    - status · string · required · example confirmed
      
      Transfer status.
    - signature · string | null · required · example sig_example
      
      Solana transaction signature (tx id/hash).
    - serializedTx · string | null · required · min length 1 · example base64_tx_example
      
      Base64-encoded transaction payload, if available. Always null for transfer batch chunks, whose signed bytes stay server-side.
    - slot · integer | null · required · example 123456
      
      Slot number, if confirmed.
    - blockTime · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      Block time, if confirmed.
    - confirmedAt · string · format date-time · example 2025-01-01T00:00:00.000Z
      
      When SDP confirmed the transfer on chain.
    - fee · integer | null · required · example 0
      
      Network fee the source wallet paid, in lamports: 0 when SDP sponsored the transaction, null when not known.
    - error · string | null · required · example Signature failed
      
      Error message if the transaction failed.
    - initiatedBy · object
      
      Initiator that triggered the transfer.
      - type · string · required · one of api_key, user, system · example api_key
        
        Initiator type.
      - id · string
        
        Initiator identifier if applicable.
      - display · string
        
        Human-friendly label for the initiator.
    - source · string · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Source wallet address.
    - destination · string · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Destination wallet address.
    - memo · string · max length 256
      
      Optional memo for the transfer.
    - token · string
      
      Token symbol or mint address.
    - amount · string · example 100.00
      
      Token amount in UI units (decimal string).
    - counterpartyId · string · example cpty_example
      
      Counterparty tied to the transfer record, when available.
    - counterpartyDisplayName · string · example Acme Studio
      
      Current display name of the counterparty tied to the transfer.
    - risk · object
      
      Optional risk evaluation for the transfer.
      - provider · string · required · example trm
        
        Risk scoring provider.
      - score · string · required · example 0.12
        
        Provider-specific risk score.
      - level · string · required · one of low, medium, high, unknown · example low
        
        Risk level classification.
      - evaluatedAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
        
        Timestamp when risk was evaluated.
    - createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      Creation timestamp.
    - updatedAt · string · required · format date-time · example 2025-01-02T00:00:00.000Z
      
      Last update 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.
422 Unprocessable Entity

Same fields as 400.
500 Internal Server Error

Same fields as 400.
502 Bad Gateway

Same fields as 400.
503 Service Unavailable

Same fields as 400.

Example request

IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST 'https://api-beta.solana.com/v1/payments/recurring-payments/prp_example/collect' \
  -H "Authorization: Bearer $SDP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

// Reuse this key when you retry this request.
const idempotencyKey = crypto.randomUUID();
const res = await fetch("https://api-beta.solana.com/v1/payments/recurring-payments/prp_example/collect", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SDP_API_KEY}`,
    "Idempotency-Key": idempotencyKey
  }
});

import os, requests, uuid

# Reuse this key when you retry this request.
idempotency_key = str(uuid.uuid4())
r = requests.post("https://api-beta.solana.com/v1/payments/recurring-payments/prp_example/collect",
  headers={"Authorization": f"Bearer {os.environ['SDP_API_KEY']}", "Idempotency-Key": idempotency_key})

Example responses

JSON

{
  "data": {
    "recurringPayment": {
      "id": "prp_example",
      "organizationId": "org_example",
      "projectId": "prj_example",
      "sourceCustodyWalletId": "cwlt_example",
      "sourceProviderWalletId": "privy_wallet_123",
      "sourceAddress": "So11111111111111111111111111111111111111112",
      "counterpartyId": "cpty_example",
      "counterpartyAccountId": "cpacct_example",
      "destinationAddress": "So11111111111111111111111111111111111111112",
      "destinationTokenAccount": "So11111111111111111111111111111111111111112",
      "token": "example",
      "amount": "100.00",
      "periodHours": 720,
      "firstCollectionAt": "2025-01-01T00:00:00.000Z",
      "nextCollectionDueAt": "2025-01-01T00:00:00.000Z",
      "planId": "plan_example",
      "subscriptionId": "subscription_example",
      "planPda": "So11111111111111111111111111111111111111112",
      "planCreatedAt": "example",
      "planCreationSignature": "example",
      "subscriptionPda": "So11111111111111111111111111111111111111112",
      "subscriptionAuthorityAddress": "So11111111111111111111111111111111111111112",
      "authorizationSignature": "example",
      "status": "active",
      "pausedReason": null,
      "metadataUri": "example",
      "createdBy": "example",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    },
    "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"
    },
    "transfer": {
      "fireblocks": {
        "transactionId": "transaction_example",
        "status": "example",
        "subStatus": "example"
      },
      "id": "xfr_example",
      "organizationId": "org_example",
      "custodyWalletId": "cwlt_example",
      "providerWalletId": "privy_wallet_123",
      "projectId": "prj_example",
      "type": "transfer",
      "kind": "example",
      "direction": "outbound",
      "status": "confirmed",
      "signature": "sig_example",
      "serializedTx": "base64_tx_example",
      "slot": 123456,
      "blockTime": "2025-01-01T00:00:00.000Z",
      "confirmedAt": "2025-01-01T00:00:00.000Z",
      "fee": 0,
      "error": "Signature failed",
      "initiatedBy": {
        "type": "api_key"
      },
      "source": "So11111111111111111111111111111111111111112",
      "destination": "So11111111111111111111111111111111111111112",
      "amount": "100.00",
      "counterpartyId": "cpty_example",
      "counterpartyDisplayName": "Acme Studio",
      "risk": {
        "provider": "trm",
        "score": "0.12",
        "level": "low",
        "evaluatedAt": "2025-01-01T00:00:00.000Z"
      },
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-02T00: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.

Collect recurring payment

Path parametersCopy Anchor Link

HeadersCopy Anchor Link

ResponsesCopy Anchor Link

Example requestCopy Anchor Link

Example responsesCopy Anchor Link

Path parameters

Headers

Responses

Example request

Example responses