Skip to main content
This guide describes how to settle a card-funded purchase to your end user’s stablecoin wallet using Superbank. The settlement type for this flow is STABLECOIN_TO_STABLECOIN: the on-chain operation Superbank performs is moving stablecoin from your prefunded wallet to the end user’s wallet. The card payment is your upstream business - Superbank doesn’t see the card transaction itself.

Flow of Funds

Refresher on how prefunded wallets and instant settlement work.

​
Pre-requisites

  1. A Superbank Developer account with API access.
  2. A configured prefunded wallet (Superbank operates this for you - talk to your Superbank contact to set the facility limit and supported rails).
  3. An external card processor (Stripe, Adyen, Checkout.com, etc.) handling card authorization on your side.
  4. Your API key.
How to get API access

​
Flow

​
Step 1: Card authorization (your processor)

Your end user pays with a card. Your processor authorizes the payment and returns success. Persist the authorization in your system with whatever internal id you use (we’ll call it external_id below - it can be your order id, transaction id, or any other unique identifier you control). Superbank doesn’t see this step.

​
Step 2: Create a Settlement Request

The moment the card is authorized, create a STABLECOIN_TO_STABLECOIN settlement request. Pass your internal id as external_id, and any additional correlation you want to keep with the settlement in metadata.

​
Request

cURL
curl --request POST \
  --url https://api-sandbox.superbank.co/v0/settlement-requests \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "type": "STABLECOIN_TO_STABLECOIN",
    "payment_reason": "PAYMENT_FOR_GOODS_AND_SERVICES",
    "amount": 50,
    "external_id": "order_xyz789",
    "metadata": {
      "user_id": "usr_42",
      "restaurant_id": "rest_88",
      "card_processor": "stripe",
      "card_charge_id": "ch_3O5..."
    },
    "destination": {
      "currency": "USDC",
      "rail": "SOLANA",
      "is_third_party": true,
      "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "beneficiary": {
        "type": "BUSINESS",
        "business_name": "Bella Vista Pizzeria LLC",
        "address": { "country_code": "US" }
      }
    }
  }'

​
Response

The response includes the settlement id (Superbank’s identifier) and echoes back your external_id and metadata. Some fields (e.g. payment_reason, outbound_payment, inbound_payment, timestamps, failure fields) are omitted below for brevity — see the Settlement Request reference for the full schema. 
{
  "id": "39760060-846e-4d5a-8583-7ee62553f79b",
  "type": "STABLECOIN_TO_STABLECOIN",
  "status": "REQUEST_STARTED",
  "amount": "50.00000000",
  "external_id": "order_xyz789",
  "metadata": {
    "user_id": "usr_42",
    "restaurant_id": "rest_88",
    "card_processor": "stripe",
    "card_charge_id": "ch_3O5..."
  },
  "destination": {
    "currency": "USDC",
    "rail": "SOLANA",
    "is_third_party": true,
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "beneficiary": {
      "type": "BUSINESS",
      "business_name": "Bella Vista Pizzeria LLC",
      "address": { "country_code": "US" }
    }
  },
  "payment_instructions": {
    "currency": "USDC",
    "rail": "SOLANA",
    "prefunded_wallet_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj",
    "valid_until": "2026-01-26T15:50:10.074Z"
  },
  "created_at": "2026-01-26T15:35:10.047Z"
}

​
Looking up the settlement later

You don’t need to persist anything from the create response - not Superbank’s id, and not payment_instructions. Both come back on the lookup. The recommended pattern is to look up the settlement by your external_id whenever the next step runs - typically in a different process or job from the create step.
cURL
curl 'https://api-sandbox.superbank.co/v0/settlement-requests?external_id=order_xyz789' \
  --header 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": "39760060-846e-4d5a-8583-7ee62553f79b",
      "type": "STABLECOIN_TO_STABLECOIN",
      "status": "REQUEST_STARTED",
      "amount": "50.00000000",
      "external_id": "order_xyz789",
      "metadata": {
        "user_id": "usr_42",
        "restaurant_id": "rest_88",
        "card_processor": "stripe",
        "card_charge_id": "ch_3O5..."
      },
      "destination": { "...": "..." },
      "payment_instructions": {
        "currency": "USDC",
        "rail": "SOLANA",
        "prefunded_wallet_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj",
        "valid_until": "2026-01-26T15:50:10.074Z"
      },
      "created_at": "2026-01-26T15:35:10.047Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}
payment_instructions.prefunded_wallet_address is the address you’ll send your reconciliation transfer to in Step 5. It’s stable for the lifetime of the settlement, so you can look it up the moment you’re ready to reconcile - no need to read it from the create response. valid_until only governs the FUNDS_SENT call (15 minutes from create); it does not apply to the T+X reconciliation transfer, so an expired valid_until at reconciliation time is expected and harmless.
external_id is not enforced as unique on Superbank’s side. If you reuse the same value (intentionally or by mistake - for example, retrying a failed create with the same identifier), the list response will include every matching settlement. If you need to disambiguate, filter the results client-side using metadata (e.g. metadata.card_charge_id, which is unique per card authorization).

​
Step 3: Notify FUNDS_SENT

Send a PUT to confirm you’ve authorized the card payment. This triggers Superbank to move stablecoin from your prefunded wallet to the end user’s wallet.
cURL
curl --request PUT \
  --url https://api-sandbox.superbank.co/v0/settlement-requests/39760060-846e-4d5a-8583-7ee62553f79b \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{ "status": "FUNDS_SENT" }'
End user receives stablecoin in seconds.

​
Step 4: Detecting completion

Same options as the standard on-ramp flow - see Detecting Completion. Webhooks recommended; poll as a fallback. The webhook payload includes your external_id and metadata, so you can route the event back to the right internal record without an extra lookup.

​
Step 5: Reconcile the settlement at T+X

When your card processor finalizes the settlement (typically T+2 or T+3, with weekend drift), you reconcile the drawdown from the Superbank facility in two phases:

​
5a. Send stablecoin to the prefunded wallet

Look up the settlement by your external_id (see Looking up the settlement later above) and transfer stablecoin on-chain to the address in payment_instructions.prefunded_wallet_address from that response. This on-chain transfer is the reconciliation - it’s what closes the credit cycle for this settlement.

​
5b. Call REQUEST_COMPLETED with the transaction hash

Once the transfer in 5a confirms on-chain, notify Superbank by sending a PUT with the transaction hash from that transfer.
cURL
curl --request PUT \
  --url https://api-sandbox.superbank.co/v0/settlement-requests/39760060-846e-4d5a-8583-7ee62553f79b \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "status": "REQUEST_COMPLETED",
    "transaction_hash": "3CBCEbF2yikAza5d8pcxpibrR4hkj78wAZPYGPtXokNsxxUqPG29aSkrNW6nXnvWzjDePgzYgcLa4G9rJ78k8cXo"
  }'
Without the transaction hash from 5a, Superbank can’t reconcile the payment with the settlement request you created. The on-chain transfer must happen before the REQUEST_COMPLETED call.

​
Idiomatic correlation pattern

The card-payments flow makes the case for external_id + metadata particularly clear:
  • external_id = your card processor’s charge id, your internal order id, or whatever single identifier you’d want to look the settlement up by later.
  • metadata = anything you want to carry through to the webhook payload without an extra database lookup - user_id, restaurant_id, card_processor, card_charge_id, device_id, etc.
Both are echoed in every read and webhook, and external_id is filterable on the list endpoint. The recommended developer pattern is don’t persist Superbank’s id - look up the settlement by your external_id whenever you need it.

​
Next Steps

Real-Time On-Ramping

The standard on-ramping flow without the card-payment specifics.

Webhooks

Subscribe to settlement events and receive your external_id + metadata on every delivery.