Skip to main content

​
Overview

Payments in Superbank represent transfers of stablecoins between accounts. The primary payment type is Liquidity Settlement, which moves funds from your prefunded account to a destination wallet.

​
Payment Types

​
Liquidity Settlement

Transfer stablecoins from your prefunded account to any external wallet. Use Cases:
  • Payouts to users
  • Vendor payments
  • Cross-border settlements
  • Exchange withdrawals
{
  "type": "LIQUIDITY",
  "amount": 100.00,
  "currency_code": "USDC",
  "chain": "SOLANA",
  "destination_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
}

​
Payment Lifecycle

​
Status Descriptions

StatusDescriptionFinal?
CREATEDPayment created, waiting for notificationNo
PROCESSINGBlockchain transfer initiatedNo
COMPLETEDTransfer confirmed on-chainYes
FAILEDTransfer failedYes
EXPIREDPayment not notified within time limitYes

​
Creating a Payment

​
Request

curl -X POST https://api-sandbox.superbank.com/v1/payments \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "LIQUIDITY",
    "amount": 100.00,
    "currency_code": "USDC",
    "chain": "SOLANA",
    "destination_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "account_holder": {
      "type": "INDIVIDUAL",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]"
    }
  }'

​
Response

{
  "id": "pay_abc123",
  "type": "LIQUIDITY",
  "status": "CREATED",
  "amount": 100.00,
  "currency_code": "USDC",
  "chain": "SOLANA",
  "destination_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "reference_id": "ref_xyz789",
  "expires_at": "2024-01-15T12:00:00Z",
  "created_at": "2024-01-15T10:00:00Z"
}

​
Payment Fields

FieldTypeDescription
idstringUnique payment identifier
typestringPayment type (LIQUIDITY)
statusstringCurrent status
amountnumberTransfer amount
currency_codestringCurrency (USDC)
chainstringBlockchain network
destination_walletstringRecipient wallet address
reference_idstringReference for notification
transaction_hashstringOn-chain transaction hash (when completed)
expires_atstringExpiration timestamp
created_atstringCreation timestamp
completed_atstringCompletion timestamp

​
Notifying Payments

Once fiat transfer has been initialized from your end user, notify Superbank to trigger the stablecoin transfer: 
curl -X POST https://api-sandbox.superbank.com/v1/payments/notifications \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INCOMING_PAYMENT",
    "reference_id": "ref_xyz789",
    "rail": "WIRE"
  }'

​
Notification Fields

FieldTypeRequiredDescription
typestringYesMust be INCOMING_PAYMENT
reference_idstringYesReference ID from payment creation response
railstringYesPayment rail must be WIRE
This triggers the on-chain transfer to the destination wallet.

​
Payment Expiration

Payments have a time limit for notification:
EnvironmentExpiration
Sandbox5 minutes
Production5 minutes
If not notified within this window, the payment expires and must be recreated.

​
Reserve Funds

Before creating a payment, ensure your prefunded account has sufficient balance. Superbank reserves funds when a payment is created:
  1. On Payment Creation: The payment amount is reserved from your prefunded account balance
  2. On Completion: Reserved funds are transferred to the destination wallet
  3. On Expiration/Failure: Reserved funds are released back to your available balance
{
  "prefunded_account": {
    "total_balance": 10000.00,
    "available_balance": 9000.00,
    "reserved_balance": 1000.00
  }
}
Payments will fail if your available balance is insufficient for the payment amount plus network fees.

​
Metadata

Attach custom data to payments for your reference: 
{
  "type": "LIQUIDITY",
  "amount": 100.00,
  "currency_code": "USDC",
  "chain": "SOLANA",
  "destination_wallet": "7xKXtg...",
  "metadata": {
    "order_id": "order-12345",
    "customer_id": "cust-67890",
    "notes": "Monthly payout"
  }
}
Metadata is stored with the payment and returned in all responses.

​
Idempotency

Use idempotency keys to safely retry payment creation: 
{
  "type": "LIQUIDITY",
  "amount": 100.00,
  "currency_code": "USDC",
  "chain": "SOLANA",
  "destination_wallet": "7xKXtg...",
  "idempotency_key": "order-12345-payment"
}
If you send the same request with the same idempotency key, you’ll receive the original payment.

​
Fees

Fee TypeAmountDescription
Platform Fee0No Superbank platform fee
Network FeeVariableBlockchain gas fee for on-chain transfer
Network fees vary by chain and network congestion. They are deducted from your prefunded account balance separately from the payment amount.

​
Transaction Details

Once a payment is completed, you can view on-chain details: 
{
  "id": "pay_abc123",
  "status": "COMPLETED",
  "transaction_hash": "5wHu1qwD7q4...",
  "completed_at": "2024-01-15T10:05:30Z"
}
View the transaction on the blockchain explorer:
  • Solana (Devnet): https://solscan.io/tx/{transaction_hash}?cluster=devnet
  • Ethereum (Sepolia): https://sepolia.etherscan.io/tx/{transaction_hash}
  • Polygon (Amoy): https://amoy.polygonscan.com/tx/{transaction_hash}
  • Base (Sepolia): https://sepolia.basescan.org/tx/{transaction_hash}
  • Tron (Shasta): https://shasta.tronscan.org/#/transaction/{transaction_hash}

​
Next Steps

Create Payment

API reference for creating payments

Webhooks

Get notified of payment events