Skip to main content
Quidkey sends a signed event to your webhook endpoint when a payment transaction changes state, and when a partner’s merchant goes live, is suspended or is reinstated. Each event is a document in the API’s own format: 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:
A merchant can have several named endpoints:
The response holds the endpoint, with its signing_secret:
Response
signing_secret appears only in this response. Store it straight away in a secret store. A retry with the same Idempotency-Key answers the endpoint without it, and so can the answer to a create you sent once, when Quidkey sent it on again after a dropped connection. If an answer has no signing_secret, POST /webhook-endpoints/{id}:rotateSecret issues a new one, and replaces the old one at once, with no overlap.
  • url is 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} changes url and status, and on a merchant’s endpoint is_signed and is_default. An inactive endpoint receives nothing.

Where a Payment Transaction’s Events Go

The first of these that applies:
  1. 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.
  2. 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.
  3. 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.
  4. The merchant’s default endpoint, set with is_default: true, if it’s active and takes the payment transaction’s environment.
  5. The merchant’s one active endpoint that takes the payment transaction’s environment, if there’s exactly one.
Otherwise the event goes nowhere. A merchant with more than one active endpoint sets a default, or names one on each payment transaction. A reversal’s events go where its payment transaction’s did. An endpoint created through the API takes both environments: live and test payment transactions. An endpoint registered outside the API can take only live or only test ones, and then rules 2, 4 and 5 pass over it for a payment transaction of the other kind. An inactive endpoint receives nothing, even where rule 1 or 2 names it.

The Event

A payment transaction’s event:
The body also holds the earlier format’s 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 a transaction.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 with is_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.

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 2xx quickly, and do the work afterwards.
  • De-duplicate on result.id. A resend Quidkey makes carries the same result.id as 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 on result.id.
When the customer’s bank accepts a payment transaction, you receive 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-format failed 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. Its data.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.