Guides

Accepting payments

How a transaction moves from created to paid, and the choices you make along the way.

The flow

1. You create a transaction

   Create a transaction with a price and a webhook URL, and keep the private_key it returns.

2. The buyer opens the checkout

   At the transaction's checkout, /checkout/{transaction_id}, they choose a payment method and get an address, or PayPal details, to pay. Hosted checkout covers the page.

3. The payment arrives

   We send payment_change as it is seen and as it confirms, then completed once it is paid in full and confirmed.

4. You fulfil the order

   Check the transaction is completed, then deliver. The money is in your balance.

Lifecycle

Every transaction starts pending and ends in exactly one of three states.

All three are final. Funds sent to a cancelled transaction's address do not settle, so only cancel what you know is unpaid.

Fixed or open price

Send amount with the currency it is denominated in, such as 20 usd. The buyer pays the equivalent in the method they choose, at the rate fixed when they choose it. Leave both out for an open-ended transaction, where amount_topay stays null.

A transaction must be worth at least 0.1 USD and at most 1,000,000 USD.

Choosing payment methods

By default the buyer can use every method enabled on your account. Pass allowed_payment_methods to narrow it for one transaction. With exactly one method on offer, the checkout shows a single button for it. Payment methods lists every code.

Underpaid and overpaid

Buyers sometimes send slightly less than asked, for example when a wallet takes its fee from the amount. Your completion threshold, set in the dashboard or with completion_threshold on Update seller settings, is the percentage short that still counts as paid: with 0.5, a payment 0.5% under topay completes the transaction.

If the buyer sends more, the transaction completes and its payment carries overpaid, the amount above topay.

Confirmations

A crypto payment counts once it has the confirmations its currency requires, shown as payment.confirmations_needed. Until then payment.confirmations rises with each block, and -1 means nothing has been seen yet. Payment methods lists the requirement for each currency.

Deposits

Create a transaction with deposit=1 to top up your own balance, for example to pay fees. amount and currency are ignored; whatever arrives is credited as a deposit rather than as revenue.

Building your own checkout

The hosted checkout is the simplest path. To build your own, call Choose how the buyer pays once the buyer picks a method: it needs no API key, so it can run on behalf of a buyer, and it returns the address and amount to show them.

curl https://anonpay.org/api/transaction/setpaymentmethod \
  -d transaction_id=9c1f0b7a4e2d8f6a3b5c7d9e1f0a2b4c \
  -d payment_method=btc

import requests

response = requests.post(
    "https://anonpay.org/api/transaction/setpaymentmethod",
    data={
        "transaction_id": "9c1f0b7a4e2d8f6a3b5c7d9e1f0a2b4c",
        "payment_method": "btc",
    },
    timeout=30,
)
print(response.json())

const url = "https://anonpay.org/api/transaction/setpaymentmethod";

const response = await fetch(url, {
  method: "POST",
  body: new URLSearchParams({
    transaction_id: "9c1f0b7a4e2d8f6a3b5c7d9e1f0a2b4c",
    payment_method: "btc",
  }),
});
console.log(await response.json());

$url = 'https://anonpay.org/api/transaction/setpaymentmethod';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POSTFIELDS => http_build_query([
        "transaction_id" => '9c1f0b7a4e2d8f6a3b5c7d9e1f0a2b4c',
        "payment_method" => 'btc',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);