Integrate Express Wallet on your website

Create Express Wallet instructions from your server after configuring **Payments > Express Wallet > Address**. Use your **Merchant Token** as the Bearer credential. Keep it on your server. The **Private Key** is a separate secret used for webhook signature verification.

Request customer instructions

Send **POST https://api.payerone.com/checkout/v1/express_wallet** with JSON and these fields:

- **merchant_client_id:** your stable customer ID, using letters, digits, or hyphens. Use the same ID for the same customer.

- **merchant_client_email:** the customer email.

- **merchant_client_name:** optional customer name.

- **ipn_url:** your HTTPS server endpoint for payment notifications.

- **success_url** and **fail_url:** your customer return URLs.

- **amount:** optional amount used for the displayed payment instructions.

Do not substitute your merchant Account ID for the customer ID or accept a customer-selected ID without validating ownership in your application.

{
  "merchant_client_id": "customer-123",
  "merchant_client_email": "customer@example.com",
  "merchant_client_name": "Example Customer",
  "ipn_url": "https://merchant.example.com/payments/payerone/ipn",
  "success_url": "https://merchant.example.com/wallet/complete",
  "fail_url": "https://merchant.example.com/wallet",
  "amount": "10.00"
}

Check amount units

The optional `amount` is passed as a numeric token-transfer amount in the generated payment links; it is not converted into a separate quote for each token. An amount of `10` does not mean a $10 equivalent for every token. Confirm the selected token and its units before displaying a prefilled transfer link. Use standard checkout with an explicit order currency when you need a fixed-price purchase quote.

Use the response

Check that **status** is **success** before using **data**. **data.networks** maps enabled network keys and token symbols to their assigned receive addresses. **data.payment_links** supplies token-transfer links for supported combinations. **data.order_id** identifies the generated Express checkout request; **data.order_url** opens its hosted instructions. Display the exact returned network, token, and address. Save references on your server and do not expose the Merchant Token to the browser. Request fresh instructions when the customer returns rather than assuming an old checkout URL stays valid forever.

Confirm a deposit

Verify the **X-PayerOne-Signature** against the original raw notification body using your Private Key before processing a notification. Use the webhook guide for the complete verification flow. For an Express transaction lookup, send an authenticated **GET https://api.payerone.com/checkout/v1/orders?network_transaction_id=TRANSACTION_REFERENCE** using the merchant Bearer token. The response includes the transaction status, network, coin, amount, currency, customer reference, fee fields, and date when a merchant-owned transaction is found. Use the returned amount and currency together; do not assume every amount is denominated in the token or that a reported amount is the gross amount before configured fees.

Avoid duplicate credits and failed setup

Credit your customer only after server-side verification of the expected merchant, customer, successful payment status, amount, and currency. Make credit handling idempotent using a stable transaction reference. A success return URL alone is not payment confirmation. If you see **Forwarding address not registered**, add an Express Wallet destination. If your IPN URL is rejected, use HTTPS. If no transaction is found, confirm the TXID and account and allow for processing; do not create a duplicate customer credit or instruct a second transfer.