> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superbank.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Card Payments
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.
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](/platform/instructions/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
```bash cURL theme={null}
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": "PURCHASE_OF_GOODS",
"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](/platform/core-resources/settlement-request) for the full schema.
```json theme={null}
{
"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.
```bash cURL theme={null}
curl 'https://api-sandbox.superbank.co/v0/settlement-requests?external_id=order_xyz789' \
--header 'X-Api-Key: YOUR_API_KEY'
```
```json theme={null}
{
"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](#step-5-reconcile-the-settlement-at-t-x).
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.
```bash cURL theme={null}
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](/platform/guides/real-time-on-ramping#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](#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.
```bash cURL theme={null}
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.
The response status may be either `REQUEST_COMPLETED` (Superbank already
detected the inbound PAYIN and matched the amount) or
`AWAITING_PAYIN_RECONCILIATION` (your `transaction_hash` was recorded
but the PAYIN hasn't been observed yet — typical when calling this
endpoint immediately after broadcasting the on-chain transfer). In the
deferred case, the request auto-resolves to `REQUEST_COMPLETED` once
the PAYIN lands and Superbank emits another `settlement_request.updated`
webhook. See [Real Time On-Ramping → Step 6](/platform/guides/real-time-on-ramping#step-6-reconcile-via-request_completed)
for the full breakdown.
## 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
The standard on-ramping flow without the card-payment specifics.
Subscribe to settlement events and receive your `external_id` + `metadata` on every delivery.