Record a payment
Records a payment from your own billing (provider custom), or updates the one recorded with the same payment_id: 201 when it is new, 200 when it existed (sending the same request again changes nothing). It is linked to a visit by ref (a checkout event's ref), then user_id/customer_id (an identified user), then email (the email trait your server sent for a user through the server-side identify), then an earlier linked payment of the same customer_id; an update that names none of them keeps the link. A different ts or currency replaces the recorded payment. 300 requests a minute per API key.
Requires an API key holding revenue:write on the site. Session cookies and share links: 401.
x-api-key<token>An organization API key (ak_…), with the permissions and the sites it was created with. For servers and scripts: no cookie and no Origin check. Also accepted as Authorization: Bearer ak_… (apiKeyBearer). A request carries one credential: a key sent with a share token or a live session cookie is 400 (details.reason: ambiguous_credentials).
Scope: revenue:write
siteId*stringapplication/json- body
payment_id*stringYour billing system's id of the payment (order, transaction or invoice id), unique within the site
^[!-~]{1,255}$amount*integerWhat the customer paid, tax included: an integer in the currency's minor unit (1999 is 19.99 USD, 1200 is 1,200 JPY)
1 <= value <= 1000000000000currency*stringISO 4217 code, any case (stored lower-case)
^[A-Za-z]{3}$ts?|When it was paid, ISO 8601 with a zone, from 2000-01-01T00:00:00Z to 5 minutes past the server's clock; default: now, or the recorded time of a payment already recorded
refunded_amount?|Refunded so far, in the same unit, 0 to amount; default: 0, or what was recorded before
status?|Instead of refunded_amount: paid (0) or refunded (all); with it, it must agree
email?|The customer's email: links the payment to a user your server identified with that email trait
ref?|The ref your page sent with its checkout event (pilotfox.event('checkout', { ref }))
user_id?|The id you passed to pilotfox.identify() for the buyer
customer_id?|Your billing system's customer id: links this customer's later payments to the same visit, and is matched like user_id for sites that identify users by it
OK
application/json- response
data*curl -X POST 'https://pilotfox.app/api/v1/sites/string/payments' \ -H 'Content-Type: application/json' \ -d '{ "payment_id": "string", "amount": 1, "currency": "string"}'{ "data": { "payment_id": "string", "provider": "custom", "ts": "string", "amount": 0, "currency": "string", "refunded_amount": 0, "status": "paid", "attribution": "checkout_ref" }}