Reference · Server API
POST /api/v1/payments
Reporting a charge outcome — the other half of card testing.
Reporting how a charge went. This is the other half of card-testing detection.
POST /api/v1/payments
Why it is not optional#
Declines are one of the three measurements in the card-testing model, and the only party that knows them is your processor.
Until your site reports its first outcome, declines are unmeasured rather than zero, and the paymentDeclines rule cannot fire for it. A site that never reports is not a site whose cards are never declined.
Request#
{ "attemptId": "<from the verdict reply>", "outcome": "declined" }outcome is "approved" or "declined". attemptId comes from payment.attemptId in the POST /api/v1/verdict reply.
Authentication#
The site secret, in x-api-key. No CORS headers: a browser reporting its own outcome would report "approved".
Status codes#
| Status | Meaning |
|---|---|
200 | Recorded |
400 | Malformed body |
401 | Wrong or missing key |
404 | Unknown attempt |
503 | Payment history is not configured |
404 also covers an attemptId belonging to another site, so one customer's secret cannot probe for another customer's attempt ids.
What the `card` field is#
Your processor's card fingerprint, or a hash you compute. Never the number.
Anything containing a 13-19 digit run that passes Luhn is refused with 400 before it is hashed, logged or stored. A false refusal costs the integrator a clear error on day one; a false acceptance costs a PCI scope.
The token is stored only as a site-salted SHA-256 prefix, so the same card at two customers is two unrelated keys.