Skip to main content

​
Set callback URL

​
Payments

Add callback_url to the request body when you call POST /offramp/initiate to create a payment for stablecoin to local currency conversion. See Stablecoin to NGN for a guide.

​
Wallets

Add callback_url when you call POST /wallet/create, or update it later on the wallet, so you can get webhook notifications about deposits and withdrawals on your wallet. See Create stablecoin wallet.

​
How notifications works

Switch sends each notification as:
Your server should acknowledge the request by returning any 2xx status quickly for successfully received notifications. Switch will retry delivery up to 3 times if the server does not acknowledge the request.

​
Payment webhooks

You receive this notifications whenever callback_url is set on your payment initiation request payload.

​
Payment status

StatusDescription
AWAITING_DEPOSITWaiting for the user to send the stablecoin.
PROCESSINGStablecoin received is being processed.
COMPLETEDStablecoin payout to local currency is completed.
FAILEDStablecoin payout to local currency failed.
REVERSEDStablecoin payout to local currency was reversed.
SCHEDULEDPayment is delayed due to liquidity constraints.
BLOCKEDPayment is blocked for compliance or risk reasons.

​
Example payload

For a USDC on Base to Nigeria Naira (NGN) in AWAITING_DEPOSIT status. 
{
  "status": "AWAITING_DEPOSIT",
  "type": "OFFRAMP",
  "reference": "19ae2615-325a-46dc-b5c1-16e0d03e4779",
  "fee": {
    "total": 0,
    "platform": 0,
    "developer": 0,
    "currency": "NGN"
  },
  "source": {
    "amount": 100,
    "currency": "USDC"
  },
  "destination": {
    "amount": 148296,
    "currency": "NGN"
  },
  "deposit": {
    "amount": 100,
    "address": "0xe0836E4D35047843dA08D510dFb91E7ecd0c43FC",
    "asset": "base:usdc",
    "note": [
      "Kindly send the exact amount to the wallet address to complete the transaction.",
      "This dynamic wallet address has a 30-minute expiry window and can only be used once."
    ]
  }
}

​
Payload field reference

FieldTypeDescription
statusstringCurrent status; see Payment status.
typestringOFFRAMP or ONRAMP.
referencestringUnique transaction reference (UUID).
source.amountnumberAmount of source to be sent.
source.currencystringSource currency code e.g. USDC.
source.networkstringSource network e.g. Base.
destination.amountnumberAmount of destination to be received.
destination.currencystringDestination currency code e.g. NGN.
destination.networkstringDestination network e.g. Fiat.
deposit.amountnumberAmount to send to the deposit address.
deposit.addressstringWallet address to send the amount to.
deposit.assetstringAsset to deposit e.g. base:usdc.
deposit.notestring[]Specific instructions for the deposit
meta.session_idstringPayout bank transfer session ID.
meta.explorer_urlstringURL to view the deposit on-chain.
meta.hashstringHash of the deposit transaction.
meta.session_id is only present when the bank payment has been initiated and is successfully processed.
meta.explorer_url and meta.hash are only present when the deposit has been made on-chain to the provided deposit address.

​
Wallet deposits and withdrawals

When callback_url is set on a wallet, Switch sends a JSON POST for on-chain deposits (receive) and withdrawals (send) involving that wallet.

​
Example wallet payload

Incoming USDC on Base to the wallet address. 
{
  "address": "0xe0836E4D35047843dA08D510dFb91E7ecd0c43FC",
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "decimals": 6,
  "type": "receive",
  "sender": "0x04e05B9bCed583e4F25F7942684dCfe8Ab2632E1",
  "receiver": "0xe0836E4D35047843dA08D510dFb91E7ecd0c43FC",
  "hash": "0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb",
  "amount": 100000000,
  "asset": "base:usdc"
}

​
Wallet payload field reference

FieldTypeDescription
addressstringWallet address involved in the event.
tokenstringContract address of the token on the network.
decimalsnumberToken decimals (for interpreting amount).
typestringreceive for deposits to the wallet, send for withdrawals from the wallet.
senderstringAddress that sent the funds.
receiverstringAddress that received the funds.
hashstringOn-chain transaction hash.
amountnumberAmount in the token’s smallest unit; divide by 10^decimals for a human-readable balance.
assetstringSwitch asset id (e.g. base:usdc).

​
Need Help?

Email

Send us a message

Call

Book a call with us