Hosted checkout
The simplest integration: create a payment, send the buyer to its checkout_url, and wait for the webhook. The buyer chooses a method, pays and sees the result on a hosted, mobile-first page that needs no login.
On this page
The flow
- Create the payment with
POST /v1/payments. It iscreatedand has acheckout_url. - Redirect the buyer to
checkout_url. The page shows your account name, the description, the total and the methods available for this payment. - Pay. For a bank or wallet method the buyer is sent on to the provider’s page. For a coin through BTCPay the checkout shows the coin amount, the address, a QR code and a countdown, and waits.
- Return. When the payment settles the page shows the result, with a button back to your
return_url, to which?payment=<id>is added (an existing query string is kept). - Confirm on your server with the webhook and
GET /v1/payments/{id}, never on the return alone.
Create the payment
curl -sS https://payments.example.com/api/v1/payments \
-H "Authorization: Bearer cp_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-42-attempt-1" \
-d '{
"amount": "49.00",
"currency": "EUR",
"description": "Order 42",
"return_url": "https://shop.example.com/thanks",
"metadata": { "order_id": "42" }
}'The body is a strict JSON object: an unknown field is an error.
| Field | Required | Rule |
|---|---|---|
amount | yes | The price as a decimal string in major units, for example "49.00": at most 9 whole digits and 2 decimals. |
currency | yes | EUR or USD. |
description | yes | 1 to 255 characters. Shown to the buyer. |
return_url | yes | An http or https URL of at most 2048 characters, without credentials. Where the buyer goes after the checkout. |
expires_in_minutes | no | Whole minutes, 1 to 1440, default 1440. Methods with their own payment window, such as a bank transfer, move the expiry when the buyer picks them. |
metadata | no | Your own string key-value pairs: at most 20 keys, keys of 1 to 40 characters, values of at most 500. Returned unchanged. |
lines | no | Order lines for the pay-later methods. Only for an account that uses its own provider keys. Write-only. |
billing_address | no | The buyer’s billing address, for the pay-later methods. Only for an account that uses its own provider keys. Write-only. |
shipping_address | no | The delivery address; it needs billing_address. Only for an account that uses its own provider keys. Write-only. |
The full field rules, including order lines and addresses, are in the API reference.
The checkout link
The token in checkout_url is the only credential of the page, so treat the link like a password: send it only to the buyer of that payment. The page is not indexed by search engines and cannot be framed.
The page reads only the stored payment: it never shows your fee, your account details or the provider’s raw data. It shows your account name, the payment id (the buyer’s reference), the description, the total, the status, the expiry and the methods on offer.
For a price in USD the total is the EUR amount the buyer pays, with one line under it that says how it was converted, for example “Converted from $49.00 at 1 EUR = 1.1193 USD”.
What the buyer sees
| Status | Checkout page |
|---|---|
created | The methods to choose from. With no method available: “This payment cannot be completed right now”. |
pending | The coin panel, a link on to the provider’s page, or a waiting state. A method that takes days (such as a bank transfer) shows where the payment instructions are and until when the payment is watched. |
paid | “Paid. Thank you.” with a receipt and a button back to you. |
paid_late | “Payment received”: the money arrived after the time limit and the seller has to confirm it by hand. |
failed, canceled | “Payment failed” or “Payment canceled”, a note that nothing was taken, and a button back to you. |
expired | “This payment expired”, a note that nothing was charged, and a “Try again” link to your return_url. |
Payments with an invoice
When invoicing is switched on for your account, the checkout of an invoiced payment adds two steps: the buyer gives their billing details, then reviews the price, the VAT and the total before paying. A coin payment through BTCPay skips both: it has no VAT and no invoice. See VAT.
Status updates on the page
A waiting page checks the payment every 3 seconds and pauses while its tab is hidden. It never calls a provider itself: the provider’s notifications and the gateway’s own checks move the status. Your server does not need to poll; use the webhook.