Skip to main content

Flow of Funds

Refresher on how instant on-ramping works with Superbank’s API.

​
Pre-requisites

Before you begin, ensure you have:
  1. A Superbank Developer account with API access
  2. A prefunded account with sufficient USDC balance
  3. Your API key.
Click here to learn how

​
On-Ramping

​
Step 1: Receive an instant on-ramping request

You user sends a real-time on-ramping request via your UI, or API. Persist their destination wallet address (destination.wallet_address).

​
Step 2: Create a Settlement Request

Create a settlement request by sending aPOST request to /v1/settlement-requests endpoint on Superbank’s API.

​
Request

cURL
curl --request POST \
  --url https://api-test.superbank.co/v1/settlement-requests \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: sb_test_key' \
  --data '{
    "amount": 20,
    "destination": {
      "currency": "USDC",
      "rail": "SOLANA",
      "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "beneficiary": {
        "type": "BUSINESS",
        "address": {
          "country_code": "US"
        },
        "business_name": "Acme Corp"
      }
    }
  }'

​
Response

{
  "id": "39760060-846e-4d5a-8583-7ee62553f79b",
  "status": "REQUEST_STARTED",
  "amount": "20",
  "transaction_id": null,
  "destination": {
    "currency": "USDC",
    "rail": "SOLANA",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "beneficiary": {
      "type": "BUSINESS",
      "business_name": "Acme Corp",
      "address": {
        "country_code": "US"
      }
    }
  },
  "payment_instructions": {
    "currency": "USDC",
    "rail": "SOLANA",
    "prefunded_wallet_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj",
    "valid_until": "2026-01-26T15:50:10.074Z"
  },
  "outbound_payment": null,
  "inbound_payment": null,
  "created_at": "2026-01-26T15:45:10.047Z",
  "updated_at": "2026-01-26T15:45:10.047Z", 
  "processing_at": null,
  "completed_at": null
}
Persist payment_instructions and settlement request id.

​
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.

​
Request

cURL
curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <Unique Idempotency Key>' \
--data-raw '{
  "amount": "1.0",
  "source": {
    "payment_rail": "ach_push",
    "currency": "usd",
  },
  "destination": {
    "payment_rail": "solana",
    "currency": "usdc",
    "to_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj",
  },
}'

​
Response

{
  "id": "transfer_123",
  "state": "awaiting_funds",
  "amount": "1.0",
  "source": {
    "payment_rail": "ach_push",
    "currency": "usd"
  },
  "destination": {
    "payment_rail": "solana",
    "currency": "usdc",
    "to_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj"
  },
  "source_deposit_instructions": {
    "bank_account_number": "123456789",
    "bank_routing_number": "101019644",
    "amount": "1.0", 
    "currency": "usd",
    "deposit_message": "BVI7depositmessage",
  },
  "receipt": {
    "initial_amount": "1.0",
    "exchange_fee": "0.0",
    "final_amount": "1.0",
    "destination_tx_hash": "0xc0ffee",
  },
  "created_at": "2023-05-05T19:39:14.316Z",
  "updated_at": "2023-05-05T19:39:15.231Z"
}

​
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 /v1/settlement-requests/:id. This triggers the instant settlement from your pre-funded wallet, to your User’s destination wallet.

​
Request

cURL
curl --request PUT \
  --url https://api-test.superbank.co/v1/settlement-requests/39760060-846e-4d5a-8583-7ee62553f79b \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: sb_test_6RtTjRgJZc48i6qZ1-6X3DBF0G9M9JPH' \
  --data '{
    "status": "FUNDS_SENT"
  }'

​
Response

{
  "id": "39760060-846e-4d5a-8583-7ee62553f79b",
  "status": "FUNDS_SENT",
  "amount": "20.00000000",
  "transaction_id": null,
  "destination": {
    "currency":"USDC",
    "rail": "SOLANA",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "beneficiary": {
      "type": "BUSINESS",
      "business_name":"Acme Corp",
      "address": {
        "country_code":"US"
      }
    }
  },
  "payment_instructions": {
    "currency":"USDC",
    "rail":"SOLANA",
    "prefunded_wallet_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj",
    "valid_until": "2026-01-26T15:50:10.074Z"
  },
  "outbound_payment": {
    "id": "2a9d2a2c-d97b-4973-baf1-78e31d37a024",
    "type": "PAYOUT",
    "status": "PROCESSING",
    "amount": "20.00000000",
    "currency": "USDC",
    "created_at": "2026-01-26T15:45:51.589Z"
  },
  "inbound_payment": null,
  "created_at": "2026-01-26T15:45:10.047Z",
  "updated_at": "2026-01-26T15:45:51.589Z",
  "processing_at": "2026-01-26T15:45:51.594Z",
  "completed_at": null
}

​
Step 5: Instant settlement completed

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).

​
Step 6: Update settlement request status to SETTLEMENT_COMPLETED

After T+X when the on-ramped transaction is completed, update the settlement request status to SETTLEMENT_COMPLETED and send the transaction hash back to Superbank by sending a PUT request to /v1/settlement-requests/:id . Without the transaction hash, we will not be able to reconcile the payment with the settlement request you created.

​
Request

cURL
curl --request PUT \
  --url https://api-test.superbank.co/v1/settlement-requests/39760060-846e-4d5a-8583-7ee62553f79b \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: sb_test_6RtTjRgJZc48i6qZ1-6X3DBF0G9M9JPH' \
  --data '{
    "status": "SETTLEMENT_COMPLETED",
    "transaction_hash": "3CBCEbF2yikAza5d8pcxpibrR4hkj78wAZPYGPtXokNsxxUqPG29aSkrNW6nXnvWzjDePgzYgcLa4G9rJ78k8cXo"
  }'

​
Response

{
  "id": "39760060-846e-4d5a-8583-7ee62553f79b",
  "status": "SETTLEMENT_COMPLETED",
  "amount": "20.00000000",
  "transaction_id": null,
  "destination": {
    "currency": "USDC",
    "rail":"SOLANA",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "beneficiary": {
      "type": "BUSINESS",
      "business_name": "Acme Corp",
      "address": {
        "country_code": "US"
      }
    }
  },
  "payment_instructions": {
    "currency": "USDC",
    "rail":"SOLANA",
    "prefunded_wallet_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj",
    "valid_until": "2026-01-26T15:50:10.074Z"
  },
  "outbound_payment": {
    "id": "2a9d2a2c-d97b-4973-baf1-78e31d37a024",
    "type": "PAYOUT",
    "status": "COMPLETED",
    "amount":"20.00000000",
    "currency": "USDC",
    "created_at": "2026-01-26T15:45:51.589Z"
  },
  "inbound_payment": {
    "id": "04621f85-bd40-46a9-a9a9-9fe14be09354",
    "type": "PAYIN",
    "status": "COMPLETED",
    "amount": "20.00000000",
    "currency": "USDC",
    "created_at": "2026-01-26T14:12:08.354Z"
  },
  "created_at": "2026-01-26T15:45:10.047Z",
  "updated_at": "2026-01-26T15:48:08.670Z",
  "processing_at": "2026-01-26T15:45:51.594Z",
  "completed_at": "2026-01-26T15:48:08.657Z"
}