Linking orders to your system

The partnerOrderIdentifier field lets you attach your own reference to a checkout session. BTC Direct stores this value on the order and includes it in order status updates.

Setting the identifier

Pass any string that identifies the order in your system:

{
  "baseCurrency": "BTC",
  "quoteCurrency": "EUR",
  "paymentMethod": "creditCard",
  "quoteCurrencyAmount": 50,
  "walletAddress": "bc1...",
  "partnerOrderIdentifier": "my-order-123"
}

The value is stored as-is. BTC Direct does not validate or interpret it.

Retrieving it later

The partnerOrderIdentifier is returned in the order detail response from the Reporting API and included in order status callbacks. Use it to look up the corresponding record in your own database without needing to store the BTC Direct order ID.

Tip: combining with returnUrl

To track which order a redirect belongs to after checkout, encode the identifier in your returnUrl:

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