result is the event, and its subject links to the resource it’s about. An event tells you what happened. Read its subject to see where it stands.
The same body also carries the fields of the earlier event format, which integrations built on it read. A new integration reads result and can ignore them.
Set Up an Endpoint
A partner has one endpoint, and receives every event for the payment transactions it creates and its merchants’ status changes:signing_secret:
Response
urlis an absolute HTTPS URL on a public address. Treat it as a secret if it carries a token.- An endpoint created through the API receives events for test payment transactions as well as live ones.
PATCH /webhook-endpoints/{id}changesurlandstatus, and on a merchant’s endpointis_signedandis_default. Aninactiveendpoint receives nothing.
Where a Payment Transaction’s Events Go
The first of these that applies:- A payment transaction created with a partner’s credential, while its merchant is still with that partner, reports to the partner’s endpoint. If the partner has no endpoint, its events go nowhere: they never go to the merchant’s destinations instead.
- A payment transaction that named endpoints in
webhook_endpoints, up to 10, reports to each of them that takes its environment, each delivery signed with that endpoint’s secret. If none of them takes its environment, its events go nowhere. - A merchant with a webhook URL of its own, shown as Default webhook under Developers in the Console, gets its events there, live and test alike, with one more earlier field. The merchant can remove it in the Console, and this API has no operation that sets one.
- The merchant’s default endpoint, set with
is_default: true, if it’sactiveand takes the payment transaction’s environment. - The merchant’s one
activeendpoint that takes the payment transaction’s environment, if there’s exactly one.
inactive endpoint receives nothing, even where rule 1 or 2 names it.
The Event
A payment transaction’s event:id, object, created, type and data, left out here.
An event has no
_uri: no operation reads an event. The API reference documents each event’s body under Events.
The Events
A transaction’s event type is
transaction.<type>.<status> and a merchant’s is merchant.<status>, with type and status as GET /transactions/{id} and GET /merchants/{id} answer them. A merchant’s events go to the partner’s endpoint only, while the merchant is still with that partner. Branch on result.type. More types can appear: answer one you don’t recognise with a 2xx and ignore it. A body with no result reports a state no event type covers, which Quidkey sends in the earlier format alone: answer it with a 2xx too.
A reversal’s subject is the reversal, whose parent_transaction is the payment transaction. See Handle a reversal.
On transaction.payment.unresolved, don’t take payment again for that order until it resolves: transaction.payment.processing or transaction.payment.completed can still follow, or transaction.payment.failed once Quidkey confirms.
These send no event, so poll for them:
When a Payment Transaction Has Succeeded
Each payment transaction sends one of two events when the customer’s bank accepts it, depending on how its money is routed.
No status,
completed included, confirms that money has reached an account. Reconcile money in hand with payouts.
Failure Reasons
The payment transaction atransaction.payment.failed event names carries failure, which says why it failed: code, message, written for your customer, and retryable, whether the same payment transaction could succeed if tried again, or null when neither the bank nor Quidkey gave an indication. Quidkey doesn’t retry a failed payment transaction: whether to ask the customer to pay again is yours to decide.
Treat
code as an open set: handle a code you don’t recognise as you would UNKNOWN. When the bank reports a reason after the event, the payment transaction’s code becomes more specific, such as UNKNOWN becoming DECLINED, and no event is sent for that, so read the reason on the payment transaction.
Verify Every Event
Every delivery is signed, unless a merchant registered the endpoint withis_signed: false. A partner’s endpoint is always signed. Verify the signature before you parse the body.
Each delivery is a POST with these headers:
SIGNATURE is a hex HMAC-SHA256 of the timestamp, a full stop and the raw request body, keyed by the endpoint’s full signing_secret, whsec_ prefix included. It covers the whole body, result and the earlier fields alike.
- Verify against the raw body bytes, exactly as received. Capture them before any JSON parser runs.
- Refuse a timestamp more than 5 minutes old.
- Compare signatures in constant time.
- On a signed endpoint, refuse a delivery that has no
X-Signature.
- Node.js
- Python
- Stripe SDK (Node.js)
Delivery
- Each event is delivered once. It isn’t retried automatically, and some activity sends no event, so poll the API for what you must see.
- Order isn’t guaranteed. Read the subject if order matters.
- Answer fast. Return a
2xxquickly, and do the work afterwards. - De-duplicate on
result.id. A resend Quidkey makes carries the sameresult.idas the delivery it repeats, and every event of a payment transaction has its own. - Handle each state once. Quidkey can send a new event, with a new
result.id, for a state you’ve already handled, as when Quidkey staff send a payment transaction’s state again. So make what you do for a subject’s state idempotent, such as fulfilling an order only once, as well as de-duplicating onresult.id.
transaction.payment.completed if it’s direct, or transaction.payment.processing if it goes through a virtual account. Both mean the same thing for your order: fulfil it. Handle the two together.
Read the subject first, and decide from what the read answers, not from the event alone: the read is the subject as it stands. Then record the event’s result.id before you do the work, in a table where it’s unique, in the same database transaction as the work: a second delivery of the event then records nothing and does nothing, and work that fails leaves the event unrecorded. Read the subject before that transaction opens, so it holds no database connection while it waits on the API.
quidkey.get stands for your own HTTP client, sending your access token, with https://api.quidkey.com/v1 as its base URL. It reads the subject at a path built from its id, never at a URL taken from the body. db stands for your database.
The Earlier Format
Every event also carries the fields of the event format integrations built before this one read:id, object, created, type and data, beside result, entities and not_included. The names don’t overlap, so a parser written for either format reads its own fields. They’re described here for those integrations, and the API reference marks them deprecated. Their amounts, statuses and field names are their own, not the API’s.
A payment transaction’s event, in the earlier format, to a merchant’s endpoint:
Earlier Event Types
“To a merchant” means to a merchant’s endpoint and to its Default webhook. Payment transaction event types are named
quidkey.payment_request.*.
A payment transaction’s event carries these in data.object:
fees:
rewards:
payer, when it isn’t null:
quidkey.merchant.status_changed carries these in data.object:
Earlier Failure Reasons
Every earlier-formatfailed event carries data.object.failure, with code, message and retryable as the payment transaction’s failure holds them. Its codes are the payment transaction’s in lower case: INSUFFICIENT_FUNDS on the payment transaction is insufficient_funds in data.object.failure, and UNKNOWN is unknown. Other earlier-format events don’t carry it.
The Default Webhook
A merchant’s Default webhook, rule 3 in Where a payment transaction’s events go, gets the same events as a merchant’s endpoint, and reads the earlier format as a merchant does. Itsdata.object.metadata carries one more field:
It never carries
payer or unresolved. It’s always signed, with the Default webhook’s own whsec_ secret, in the same way as an endpoint’s delivery.