Create a settlement request by sending a POST request to /v0/settlement-requests endpoint on Superbank’s API.We recommend supplying an external_id (your own identifier for this
settlement) and optional metadata (free-form key/value pairs) on
create. Both are echoed back on every read and webhook, and external_id
is filterable on the list endpoint — meaning you don’t need to persist
anything from the create response (not Superbank’s id, not
payment_instructions). Look the settlement up by external_id
whenever you need it; the full record (including payment_instructions)
comes back on every lookup.
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": "REMITTANCES", "amount": 20, "external_id": "txn_abc123", "metadata": { "user_id": "usr_42", "source": "mobile_app" }, // Optional. Override only when your processor's settlement window // differs from the T+3 default. ISO 8601, must be in the future, max 30 days out. "reconciliation_expected_at": "2026-05-04T17:00:00Z", "destination": { "currency": "USDC", "rail": "SOLANA", "is_third_party": true, "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", "beneficiary": { "type": "BUSINESS", "address": { "country_code": "US" }, "business_name": "Acme Corp" } } }'
Picking the right payment_reason. The enum is broad and is used for categorisation and
reporting, not customer-visible metadata. For typical fintech flows the values you’ll actually use
are: REMITTANCES (cross-border consumer transfers), PAYMENT_FOR_GOODS_AND_SERVICES (merchant
payments), EMPLOYEE_SALARIES_OR_WAGES (payroll). Pick the closest specific value rather than
reaching for OTHER.
destination.is_third_party — pick what’s true, not what’s convenient. Set true when the
beneficiary is not your own registered company (e.g., a payout to a vendor, contractor, or
end-user). Set false only when the destination is your own company / registered account.
Some fields (e.g. outbound_payment, inbound_payment, timestamps, failure fields) are omitted in the examples on this page for brevity — see the Settlement Request reference for the full schema.
You don’t need to persist anything from this response - not Superbank’s
id, and not payment_instructions. Both come back on the lookup.
Look the settlement up later via the external_id filter whenever the
next step runs:
external_id is not enforced as unique on Superbank’s side. If you reuse the same value
(intentionally or by mistake), the response can include multiple settlements. If you need to
disambiguate, filter the results client-side using metadata.
Step 3: Start on-ramping with your infrastructure provider
Use thepayment_instructions returned in the previous step as the on-ramping destination to request the deposit instructions from your infrastructure provider.For example, here’s how to do it with Bridge as your infrastructure provider.
Step 4: Update settlement request status to FUNDS_SENT
Once the End-User has initated the payment using your infrastructure provider, update the settlement request status to FUNDS_SENT by sending the PUT request to /v0/settlement-requests/:id.This triggers the instant settlement from your pre-funded wallet, to your User’s destination wallet.
Once you confirm the funds are sent via Step 4, Superbank moves USDC from your pre-funded wallet to the End-User’s wallet in real time.The End-User receives their USDC instantly (blockchain speed).
Between Step 5 (Superbank moves the funds) and Step 6 (you call REQUEST_COMPLETED with the transaction hash), your system needs to know that the settlement is done. There are two ways to find out, and we strongly recommend the first.
Subscribe a webhook endpoint and listen for settlement_request.updated events where data.status === 'SETTLEMENT_COMPLETED'. As soon as Superbank moves the funds, you’ll get a signed POST to your endpoint and can immediately fire Step 6.
If you can’t accept webhooks, poll GET /v0/settlement-requests/:id until status === 'SETTLEMENT_COMPLETED'. Recommended interval: 5 seconds or longer. Polling more aggressively wastes your rate-limit budget without speeding up settlement (the underlying blockchain confirmation is the gating factor, not our API).
Webhooks are the better choice in almost every case: lower latency, no wasted requests, and you don’t have to keep state about what you’re polling for.
After T+X — when you’ve collected the fiat from the end user and reconciled
it on-chain into your Superbank prefunded wallet — close the settlement by
calling REQUEST_COMPLETED with the transaction hash of the on-chain
reconciliation.The on-chain reconciliation typically happens one of two ways:(a) Direct deposit via payment_instructions. Use the wallet address
or bank details shown in payment_instructions from Step 2’s response.
Funds deposited there settle automatically into the prefunded wallet, so
you don’t need to perform a separate forwarding step.(b) Third-party forwarding. If you receive the funds on a third-party
infrastructure first (e.g. Bridge, Coinbase, your own off-ramp), forward
the resulting stablecoin on-chain to the Superbank prefunded wallet to
reconcile.In both cases, the transaction_hash in the request below is the hash of
the on-chain transfer that lands stablecoin in the prefunded wallet — not
the destination payment Superbank made to the end user (that’s the
OUTBOUND, which auto-confirms in seconds and doesn’t need to be reported
back).
This step is crucial. Without the on-chain transaction hash from the reconciliation step,
Superbank cannot match the settlement to the inbound funds.
