Create a hosted checkout order

Create checkout from your application server with `POST https://api.payerone.com/checkout/v1/orders_v2`. Authenticate with your Merchant Token. Calculate the amount from your own trusted order data before making the request.

Required fields

| Field | What to send |

| --- | --- |

| `amount` | Purchase amount as a JSON number. |

| `currency_code` | `USD`, `EUR`, `GBP`, or `USDT`. |

| `description` | A useful description of the purchase. |

| `customer_name` | Customer name. |

| `customer_email` | Valid customer email address. |

| `custom_id` | Your own order reference. Keep this distinct from the returned PayerOne order ID. |

| `ipn_url` | Public HTTPS endpoint for payment notifications. |

| `success_url` | Customer return URL after checkout success. |

| `fail_url` | Customer return URL after checkout failure. |

{
  "amount": 25.00,
  "currency_code": "USD",
  "description": "Example purchase",
  "customer_name": "Example Customer",
  "customer_email": "customer@example.com",
  "custom_id": "SHOP-1001",
  "ipn_url": "https://example.com/webhooks/payerone",
  "success_url": "https://example.com/payment/success",
  "fail_url": "https://example.com/payment/failed"
}

Send it from your server

Save the JSON request as `order.json`, keep your Merchant Token in your server environment, and send the request from a trusted backend. This example sends a real API request when you run it.

curl 'https://api.payerone.com/checkout/v1/orders_v2' \
  --request POST \
  --header "Authorization: Bearer $PAYERONE_MERCHANT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @order.json

Save the result

On success, store `data.order_id` against your local order and send the customer to `data.order_url`. Use the URL returned by PayerOne rather than building a checkout URL yourself. The response also includes the checkout token and fee information.

Optional fields

`address_types` can restrict the merchant address types enabled for this order, such as `evm` or `solana`; use types configured for your account. `transaction_fee` and `transaction_fee_fixed` are optional customer-fee inputs. Leave optional fee values unset unless your integration intentionally applies them.

An IPN URL that does not use HTTPS is rejected. If the amount is rejected, use the amount requirement returned by the API; do not silently increase the customer charge. If your merchant credit balance prevents creation, resolve that in the dashboard before retrying.

Use one local checkout attempt record for the purchase. `custom_id` is your reference, not a documented order-creation idempotency guarantee. If a create request times out after being sent, reconcile the existing attempt before blindly creating another checkout.

Confirm the recorded payment state on your server before fulfillment. A customer reaching `success_url` is a browser return and does not prove payment.