{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Custodial vs. Non-Custodial Off-Ramp","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"custodial-vs-non-custodial-off-ramp","__idx":0},"children":["Custodial vs. Non-Custodial Off-Ramp"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the off-ramp (sell) flow, there are two ways to handle the crypto transfer from the customer to Banxa. The right choice depends on whether your platform holds custody of your customers' crypto."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n A([Sell order initiated]) --> B[POST /v2/sell]\n B --> C[Customer completes checkout
KYC + bank account details]\n C --> D{Custodial?}\n\n D -->|No| E[Banxa shows deposit
address + QR code]\n E --> F[Customer sends crypto
from their own wallet]\n F --> Z\n\n D -->|Yes| G{Notification method}\n\n G -->|Deeplink| H[Banxa redirects to partner
with deposit address in deeplink]\n H --> I[Partner transfers crypto
to Banxa deposit address]\n I --> Z\n\n G -->|Webhook| J[Order status → waitingPayment
Webhook fires to partner endpoint]\n J --> K[Partner calls GET /v2/orders/:id
retrieves deposit address]\n K --> L[Partner transfers crypto
to Banxa deposit address]\n L --> Z\n\n Z[Banxa detects on-chain transfer] --> M([Fiat payout released to customer])\n","diagramHtml":"

No

Yes

Deeplink

Webhook

Sell order initiated

POST /v2/sell

Customer completes checkout
KYC + bank account details

Custodial?

Banxa shows deposit
address + QR code

Customer sends crypto
from their own wallet

Banxa detects on-chain transfer

Notification method

Banxa redirects to partner
with deposit address in deeplink

Partner transfers crypto
to Banxa deposit address

Order status → waitingPayment
Webhook fires to partner endpoint

Partner calls GET /v2/orders/:id
retrieves deposit address

Partner transfers crypto
to Banxa deposit address

Fiat payout released to customer

","diagramHtmlDark":"

No

Yes

Deeplink

Webhook

Sell order initiated

POST /v2/sell

Customer completes checkout
KYC + bank account details

Custodial?

Banxa shows deposit
address + QR code

Customer sends crypto
from their own wallet

Banxa detects on-chain transfer

Notification method

Banxa redirects to partner
with deposit address in deeplink

Partner transfers crypto
to Banxa deposit address

Order status → waitingPayment
Webhook fires to partner endpoint

Partner calls GET /v2/orders/:id
retrieves deposit address

Partner transfers crypto
to Banxa deposit address

Fiat payout released to customer

"},"children":["flowchart TD\n A([Sell order initiated]) --> B[POST /v2/sell]\n B --> C[Customer completes checkout
KYC + bank account details]\n C --> D{Custodial?}\n\n D -->|No| E[Banxa shows deposit
address + QR code]\n E --> F[Customer sends crypto
from their own wallet]\n F --> Z\n\n D -->|Yes| G{Notification method}\n\n G -->|Deeplink| H[Banxa redirects to partner
with deposit address in deeplink]\n H --> I[Partner transfers crypto
to Banxa deposit address]\n I --> Z\n\n G -->|Webhook| J[Order status → waitingPayment
Webhook fires to partner endpoint]\n J --> K[Partner calls GET /v2/orders/:id
retrieves deposit address]\n K --> L[Partner transfers crypto
to Banxa deposit address]\n L --> Z\n\n Z[Banxa detects on-chain transfer] --> M([Fiat payout released to customer])\n"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"non-custodial-flow","__idx":1},"children":["Non-custodial flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The customer initiates the crypto transfer themselves. Banxa displays a receiving wallet address and QR code during checkout, and the customer sends the crypto directly from their own wallet."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How it works:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer creates a sell order and completes checkout (KYC, bank account details)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa displays a deposit address and QR code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer transfers the crypto from their wallet to the Banxa deposit address."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa detects the incoming transfer on-chain and processes the fiat payout."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No additional API calls are required from your platform"]}," after order creation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Best for:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Self-custody wallets where the customer controls their private keys."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Consumer wallet applications."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"custodial-flow","__idx":2},"children":["Custodial flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your platform holds custody of the customer's crypto and executes the blockchain transfer on their behalf. After the customer completes checkout, Banxa needs to notify your platform of the deposit address. There are two ways this works:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-1-deeplink","__idx":3},"children":["Option 1: Deeplink"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer creates a sell order and completes checkout (KYC, bank account details)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa redirects back to your platform via a deeplink that includes the deposit address and all required transfer parameters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your platform reads the deeplink parameters and executes the blockchain transfer to Banxa's deposit address."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa detects the incoming transfer on-chain and processes the fiat payout."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example deeplink:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://example.com/banxa/?blockchain=ETH&coinAmount=39.29&fiatAmount=55\n &fulfillmentStatus=Pending&providerWalletAddress=0x03EA4c7ED1d8199510017D88f2783Ef43ab5a4fd\n &coinType=USDT&orderId=7dbb7f5c2ad8bbbd022e4426fe98fb3a&identityStatus=Complete\n &orderRef=7dbb7f5c2ad8bbbd022e4426fe98fb3a&paymentStatus=Action%2BRequired\n &coin=USDT&orderStatus=pending&fiat=AUD\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your platform uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["providerWalletAddress"]}," as the destination address for the blockchain transfer, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coinAmount"]}," as the amount to send."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-2-webhook","__idx":4},"children":["Option 2: Webhook"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer creates a sell order and completes checkout (KYC, bank account details)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa updates the order status to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["waitingPayment"]}," and triggers a webhook to your endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your platform calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/orders/{id}"]}," to retrieve the deposit address and transfer details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your platform executes the blockchain transfer to Banxa's deposit address."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Banxa detects the incoming transfer on-chain and processes the fiat payout."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact Banxa to discuss which option is best for your integration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Best for:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exchanges or custodial wallet products where your platform manages customer funds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cases where you want to automate the crypto transfer without customer action."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choosing-a-flow","__idx":5},"children":["Choosing a flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact Banxa to configure your preferred flow. The flow is set at the partner account level and applies to all sell orders for your integration."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Consideration"},"children":["Consideration"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Non-custodial"},"children":["Non-custodial"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Custodial"},"children":["Custodial"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You hold customer crypto"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer action required for transfer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhook integration required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]}]}]}]}]},"headings":[{"value":"Custodial vs. Non-Custodial Off-Ramp","id":"custodial-vs-non-custodial-off-ramp","depth":1},{"value":"Non-custodial flow","id":"non-custodial-flow","depth":2},{"value":"Custodial flow","id":"custodial-flow","depth":2},{"value":"Option 1: Deeplink","id":"option-1-deeplink","depth":3},{"value":"Option 2: Webhook","id":"option-2-webhook","depth":3},{"value":"Choosing a flow","id":"choosing-a-flow","depth":2}],"frontmatter":{"title":"Custodial vs. Non-Custodial Off-Ramp | Banxa Docs","description":"Choose how crypto transfers work in Banxa's sell flow. Custodial requires POST /v2/orders/{id}/confirm after your platform executes the blockchain transfer.","seo":{"title":"Custodial vs. Non-Custodial Off-Ramp"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/on-ramp-off-ramp/custodial-vs-non-custodial","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}