GET /partners/{id}/merchants, and a merchant with GET /api-keys/current.
1. Check the Currencies
2. Create the Payment Transaction
amountis in minor units:2550is EUR 25.50.customer_details.countrydecides 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.authorizationsays how the customer authorizes the payment transaction: withcheckout, they authorize it themselves at their bank, and come back tosuccess_urlorfailure_url.- Use one
Idempotency-Keyfor 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.
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 asauthorization.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 tocheckout.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
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.