Redirecting back to your application

After a user completes or cancels a payment on the BTC Direct checkout page, they can be redirected back to your application. You control this with the returnUrl field.

How it works

1. You include a returnUrl when creating the checkout session.
2. The user completes (or cancels) payment on the BTC Direct checkout page.
3. BTC Direct redirects the user back to your returnUrl.

Setting the return URL

Pass the returnUrl field in your checkout request:

{
  "baseCurrency": "BTC",
  "quoteCurrency": "EUR",
  "paymentMethod": "creditCard",
  "quoteCurrencyAmount": 50,
  "walletAddress": "bc1...",
  "returnUrl": "https://yourapp.com/order/complete"
}

The returnUrl is optional. If omitted, the user stays on the BTC Direct checkout page after completion.

Deep linking into mobile apps

The returnUrl supports deep links, allowing you to redirect users back into your native mobile app after payment. Use your app’s custom URL scheme or universal link:

{
  "returnUrl": "yourapp://orders/complete"
}

Or with a universal link:

{
  "returnUrl": "https://yourapp.com/app/orders/complete"
}

Make sure your app is configured to handle the URL scheme or universal link on the target platform (iOS/Android).

What happens on redirect

The user is redirected to your returnUrl as-is. No query parameters are appended by BTC Direct. To track which order the redirect belongs to, use the partnerOrderIdentifier field and encode it in your URL:

{
  "returnUrl": "https://yourapp.com/order/complete?ref=my-order-123",
  "partnerOrderIdentifier": "my-order-123"
}