API reference

Base URL https://paymybid.lol/api/v1. Every request carries the board's token as Authorization: Bearer <token>. Requests and responses are JSON. Amounts are integers in the currency's minor unit (cents).

GET/ping

Confirms the token and tells you whether payments are currently enabled for your board.

{ "board": "b_x8k2m1qz4a", "currency": "usd", "payments": true }

POST/orders

Creates an order and its checkout link. Send the payer to checkout_url: it is on this domain, and the payment form on it is served by the processor. It stays open for sixty minutes.

curl -X POST https://paymybid.lol/api/v1/orders \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "amount_cents": 2500, "currency": "usd", "reference": "bid-8812", "payer_email": "[email protected]" }'

Field	Type	Notes
`amount_cents`	integer, required	100 to 10,000,000
`currency`	string	`usd` or `eur`; defaults to the board's currency
`reference`	string, required	Your own id for this order, up to 64 chars of `A-Z a-z 0-9 _ - : .`. Opaque to us, never shown to the payer or the processor.
`payer_email`	string	If given, the processor sends the receipt there and pre-fills checkout.

201 Created
{
  "id": "01J6Z3Q0V8K1N9X2W4E5R6T7Y8",
  "status": "pending",
  "amount_cents": 2500,
  "currency": "usd",
  "reference": "bid-8812",
  "checkout_url": "https://paymybid.lol/pay/01J6Z3Q0V8K1N9X2W4E5R6T7Y8",
  "expires_at": "2026-09-03T15:41:00+00:00",
  "paid_at": null
}

GET/orders/{id}

Reads an order. While it is pending we look it up at the processor, at most once every 5 seconds per order, so poll as often as your page needs. Once it is paid the answer is final.

{ "id": "01J6Z3Q0V8K1N9X2W4E5R6T7Y8", "status": "paid", "paid_at": "2026-09-03T15:14:09+00:00", ... }

Statuses

`pending`	Created, checkout open, not yet paid.
`paid`	Money captured. Apply the credit. Final.
`expired`	The sixty-minute window closed unpaid and the payment was cancelled at the processor. Create a new order if the payer returns.
`failed`	The processor refused to open the payment. Nothing was charged.

Errors

`401`	Missing or unknown token.
`404`	No such order for this board.
`422`	Validation, with a `errors` object naming the fields.
`502`	`checkout_failed`: the processor did not open the payment. Retry later.
`503`	`payments_unavailable`: payments are not enabled for this board yet.

Recommended flow

Create the order when the payer confirms the amount, not before. Store our id against your bid.
Send the payer to checkout_url, ideally in a new tab, and keep your page open.
Poll /orders/{id} every three seconds from your server while that page is open.
On paid, apply the credit once. Treat a repeated paid as the same event.
Run a job every minute for bids you stopped watching; expire your side after a day.

Getting a token

Tokens are issued by hand and shown once. Write to us with what your board sells and in which currency.