Skip to main content
A merchant’s credential and a partner’s both create payment transactions. A partner finds the merchant’s ID with GET /partners/{id}/merchants, and a merchant with GET /api-keys/current.

1. Check the Currencies

It lists the currencies routed to the merchant’s active accounts, for live and for test payment transactions. A payment transaction in another currency is refused.

2. Create the Payment Transaction

  • amount is in minor units: 2550 is EUR 25.50.
  • customer_details.country decides how the payment transaction is routed.
  • statement_descriptor, up to 18 characters, goes to the customer’s bank, which makes it alphanumeric. On a payment transaction through a virtual account, the customer’s statement shows Quidkey’s reconciliation reference instead.
  • authorization says how the customer authorizes the payment transaction: with checkout, they authorize it themselves at their bank, and come back to success_url or failure_url.
  • Use one Idempotency-Key for each attempt to pay, and store it with the attempt before you send the request. When the customer tries again after a payment transaction has failed or been cancelled, use a new key: the old one keeps answering the payment transaction that failed. See Idempotency and Recover a lost response.
The answer is 201, with the payment transaction at status: pending:
Response
checkout is a one-time value: it appears only here and in the answer to POST /transactions/{id}:issueCheckout. A replay leaves it out, and so can the answer to a create you sent once, when Quidkey sent it on again after a dropped connection. If the answer has no checkout, call POST /transactions/{id}:issueCheckout for it. The reference lists every code.

Open Checkout at the Customer’s Bank

If the customer chooses their bank on your own page, send it as authorization.bank at create. List the banks they can choose from with GET /merchants/{id}/banks, for the same country, currency and is_test as the payment transaction. See Banks.
checkout.url then opens with that bank chosen, and the customer confirms it with one tap. They can still pick another bank on the same page.

3. Send the Customer to Pay

Redirect the customer to checkout.url. They choose their bank, approve the payment transaction there, and come back to your authorization.success_url or failure_url. Customer. The redirect only says where the customer went. Confirm the payment transaction with the event or a read, never with the redirect alone.

4. Receive the Event

transaction.payment.completed arrives when the customer’s bank accepts a direct payment transaction, and transaction.payment.processing when it accepts one through a virtual account. A payment transaction created with a partner’s credential reports to the partner’s endpoint, and one created with the merchant’s to the merchant’s. See Webhooks. result.subject links to the payment transaction, whose order.order_id is the one you sent.

5. Read the Payment Transaction

The payment transaction reads processing while the money is on its way, and completed once the provider reports it finished. fees holds what Quidkey charged, and payout links to the payout that carries it, once it’s batched. ?include=customer_details adds the customer’s details to entities. If the customer leaves before paying, the payment transaction stays pending. POST /transactions/{id}:issueCheckout answers its live checkout again, or a new one once it has expired, so you can send the customer back.