BlinkPay offers two methods for single payments:
| Method | API Calls | Use Case |
|---|---|---|
| Quick Payments | 1 (combined consent + payment) | E-commerce checkout, simple payments |
| Single Consents | 2 (consent, then payment) | Invoice payments, pre-authorisation |
For bank payments, both methods result in a Direct Credit payment through New Zealand's BECS network. When using the Gateway flow, card payments are also available — card transactions are settled to you by your acquirer bank.
Creates the consent and the payment instruction in one API call; there is no separate POST /payments, which a quick payment refuses with 422 BP018.
You must retrieve the quick payment to complete it
Creating a quick payment obtains the customer's consent; it does not debit them. For a bank payment made through the redirect or gateway flow, retrieve the quick payment with GET /payments/v1/quick-payments/{quick_payment_id} as soon as the customer returns; the gateway normally does this for you, and calling it again is safe. That call completes the payment. If it returns a 4xx or 5xx, retry the GET rather than treating the payment as failed, and read the outcome from consent.payments[0].status.
In the decoupled flow the payment is submitted as soon as the customer authorises; you still retrieve the quick payment to read the outcome. For a card quick payment the money is taken at the gateway.
Request:
POST /payments/v1/quick-payments HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Content-Type: application/json
idempotency-key: 6d2f8a4c-1e3b-4a7d-9c5f-0b8e2d4a6c1f
request-id: 2b7e9c1d-4f6a-4d8b-a3e5-9c1f7b5d3e2a
{
"flow": {
"detail": {
"type": "gateway",
"redirect_uri": "https://www.yourwebsite.com/payment/complete"
}
},
"amount": {
"currency": "NZD",
"total": "50.00"
},
"pcr": {
"particulars": "Online Shop",
"code": "ORDER-123",
"reference": "Customer"
}
}
PCR Field Limits
Each PCR field (particulars, code, reference) has a maximum length of 12 characters. Requests with longer values are rejected with a 400 validation error.
Response:
{
"quick_payment_id": "3a3b7f7d-f8e6-4c3e-b2a1-5f9c8d7e6a5b",
"redirect_uri": "https://sandbox.debit.blinkpay.co.nz/gateway/pay?id=3a3b7f7d..."
}
Store quick_payment_id against your order before you redirect the customer to redirect_uri to complete authorisation; it is the cid on your return URL and the ID you retrieve the payment with (see Which IDs to Store).
Retrying a create request. Generate a new UUID for each quick payment and send it again unchanged if you retry after a timeout or 5xx. Send both idempotency-key and request-id, and resend both unchanged on retry.
After authorisation this call completes the payment (see above). Make it as soon as the customer returns, then poll it every second until the payment is AcceptedSettlementCompleted or Rejected, within your polling window.
Request:
GET /payments/v1/quick-payments/{quick_payment_id} HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Response:
{
"quick_payment_id": "3a3b7f7d-f8e6-4c3e-b2a1-5f9c8d7e6a5b",
"consent": {
"consent_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a",
"status": "Authorised",
"creation_timestamp": "2025-12-16T10:00:00+13:00",
"status_updated_timestamp": "2025-12-16T10:05:00+13:00",
"detail": {
"type": "single",
"flow": {
"detail": {
"type": "gateway",
"redirect_uri": "https://www.yourwebsite.com/payment/complete"
}
},
"pcr": {
"particulars": "Online Shop",
"code": "ORDER-123",
"reference": "Customer"
},
"amount": {
"total": "50.00",
"currency": "NZD"
}
},
"payments": [
{
"payment_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a",
"type": "single",
"status": "AcceptedSettlementInProcess",
"creation_timestamp": "2025-12-16T10:05:00+13:00",
"status_updated_timestamp": "2025-12-16T10:06:00+13:00",
"detail": {
"consent_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a"
},
"refunds": []
}
]
}
}
Determining the Outcome
Once the consent reaches Consumed or Rejected, the outcome is in consent.payments. A rejected consent carries exactly one payment record with status: Rejected, created at rejection time with its detail (amount, PCR) populated from the consent request:
"payments": [
{
"payment_id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"type": "single",
"status": "Rejected",
"creation_timestamp": "2025-12-16T10:05:00+13:00",
"status_updated_timestamp": "2025-12-16T10:05:00+13:00",
"detail": {
"consent_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a",
"amount": { "total": "50.00", "currency": "NZD" },
"pcr": { "particulars": "Online Shop", "code": "ORDER-123", "reference": "Customer" }
},
"refunds": []
}
]
A quick payment has at most one payment, so read consent.payments[0]. A consumed consent carries the real payment progressing through the payment lifecycle; Consumed does not by itself mean paid, so check payments[0].status. A Rejected quick payment, whether the customer declined or the authorisation or 60-minute window timed out, always carries its one Rejected payment. Only GatewayTimeout (a gateway consent abandoned before bank selection) and Revoked leave consent.payments empty — check consent.status for those cases.
If you use the redirect flow directly (not the hosted Gateway), the error and status
parameters on your return URL describe the consent outcome only, not the payment's. Read
consent.payments[0].status for the payment outcome rather than inferring it from the redirect.
See Return Parameters.
Two-step payment process with separate consent and payment creation.
Request:
POST /payments/v1/single-consents HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Content-Type: application/json
idempotency-key: 4a8c2e6f-3b1d-4f9a-8c7e-5d2b0a9f1e3c
request-id: 9e1c5a3f-7b2d-4e8c-b6a4-1f3d5b7c9a2e
{
"flow": {
"detail": {
"type": "gateway",
"redirect_uri": "https://www.yourwebsite.com/payment/callback"
}
},
"amount": {
"currency": "NZD",
"total": "75.00"
},
"pcr": {
"particulars": "Invoice",
"code": "INV-456",
"reference": "Payment"
}
}
Response:
{
"consent_id": "8f7e6d5c-4b3a-2c1b-0a09-8f7e6d5c4b3a",
"redirect_uri": "https://sandbox.debit.blinkpay.co.nz/gateway/pay?id=8f7e6d5c..."
}
Store consent_id against your order, then redirect the customer to redirect_uri to complete authorisation. Retries of this request follow the same rules as for quick payments: resend the same idempotency-key (redirect and decoupled) or request-id (gateway) with the same body.
Read the consent once the customer has returned to your redirect_uri; if it isn't Authorised or terminal yet, poll every second. Don't poll while they are still at their bank.
Request:
GET /payments/v1/single-consents/{consent_id} HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Response:
{
"consent_id": "8f7e6d5c-4b3a-2c1b-0a09-8f7e6d5c4b3a",
"status": "Authorised",
"creation_timestamp": "2025-12-16T10:00:00+13:00",
"status_updated_timestamp": "2025-12-16T10:05:00+13:00",
"detail": {
"type": "single",
"flow": {
"detail": {
"type": "gateway",
"redirect_uri": "https://www.yourwebsite.com/payment/callback"
}
},
"pcr": {
"particulars": "Invoice",
"code": "INV-456",
"reference": "Payment"
},
"amount": {
"total": "75.00",
"currency": "NZD"
}
},
"payments": []
}
Create the payment within 48 hours of the consent becoming Authorised (its status_updated_timestamp). After that the consent is Rejected: POST /payments/v1/payments returns 422 with BP002, and you need a new consent.
Send only consent_id. The amount and PCR always come from the consent, and a request that also carries amount or pcr is rejected with 400 BP235. Send an idempotency-key with a fresh UUID for each payment attempt.
Request:
POST /payments/v1/payments HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Content-Type: application/json
idempotency-key: c3e7a1f9-5d2b-4c8e-9a6f-2b4d8e0c6a1f
{
"consent_id": "8f7e6d5c-4b3a-2c1b-0a09-8f7e6d5c4b3a"
}
Response (201 Created):
{
"payment_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a"
}
Store the payment_id: you need it to check the payment and to refund it. You can also find it later from the consent: GET /payments/v1/single-consents/{consent_id} lists every payment in payments[].
What you can do next depends on when the bank refuses it:
| What happened | Payment | Consent | Next step |
|---|---|---|---|
| The bank refused the payment straight away | Rejected | Authorised | Handle it as a failed payment. If the customer resolves the cause, you may create another payment on the same consent, with a new idempotency key, within the 48 hours |
| The bank accepted the payment and later rejected it | Rejected | Consumed | The consent is used up (BP002 on a new attempt). Create a new consent |
| The payment succeeded | AcceptedSettlementCompleted | Consumed | Done; a new attempt returns BP002 |
Because of the first case, a single consent can carry more than one payment. consent.payments is sorted newest first, so payments[0] is always the latest attempt. As with quick payments, Consumed does not by itself mean paid: always check the payment's status.
If POST /payments times out or returns a 5xx, you don't know whether a payment was created, and it may still settle. Don't create a new consent. Retry the same request with the same idempotency key: you get the original payment back if one was created. If you don't have the key any more, GET /payments/v1/single-consents/{consent_id} and inspect payments[0] before doing anything else:
Pending or AcceptedSettlementInProcess: poll that payment; a new POST returns 409 BP703 naming it.AcceptedSettlementCompleted: the customer has paid.Rejected with the consent still Authorised: you may try again with a new key.POST.Only create a new consent once you know the old one has no payment that may still settle. See Which IDs to Store.
Request:
GET /payments/v1/payments/{payment_id} HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Response:
{
"payment_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a",
"type": "single",
"status": "AcceptedSettlementCompleted",
"creation_timestamp": "2025-12-16T10:10:00+13:00",
"status_updated_timestamp": "2025-12-16T10:15:00+13:00",
"detail": {
"consent_id": "8f7e6d5c-4b3a-2c1b-0a09-8f7e6d5c4b3a"
},
"refunds": []
}
Poll every second until the payment is AcceptedSettlementCompleted or Rejected, within your polling window. AcceptedSettlementCompleted is the only status that means the payment succeeded. BlinkPay does not send receipts to your customers, so send your own confirmation if you need one. To return money later, see Refunds.
To cancel a single consent before it is paid, for example when the customer cancels the order, revoke it:
DELETE /payments/v1/single-consents/{consent_id} HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Response: 204 No Content. The consent is Revoked and can't be paid. It needs the revoke:single_consent scope, which also revokes a quick payment through DELETE /payments/v1/quick-payments/{quick_payment_id}.
A 409 means a payment on the consent is still in flight: poll it first. Other refusals are listed on the Error Codes page.
| Constraint | Value |
|---|---|
| Minimum | $0.01 NZD |
| Maximum | Varies by bank — see Bank Coverage |
| Currency | NZD only |
| Format | A string with a decimal point and one or two decimal places (e.g. 100.00 or 100.5, not 100). Send two decimal places |
Bank-Specific Limits
Individual banks may have lower limits based on customer account settings. For large payments, inform customers they may need to increase their daily limits.
If BlinkPay has enabled surcharging (fee forwarding) for your account, the customer pays amount.total plus a surcharge, and limits apply to that total. See Surcharging (Fee Forwarding).
PCR (Particulars, Code, Reference) fields appear on bank statements for reconciliation. Use them for whatever is most useful to you; the uses below are only examples.
| Field | Required | Length | Example use |
|---|---|---|---|
particulars | Yes | 1-12 | General description |
code | No | 0-12 | Specific identifier (invoice number, order ID) |
reference | No | 0-12 | Additional reference (customer ID) |
Avoid putting customer personal information (names, addresses, contact details) in PCR fields — they appear on bank statements. Use opaque identifiers such as a customer or order ID instead. See Payment Reconciliation for full reconciliation guidance.
Allowed Characters
PCR fields accept letters, digits, spaces and the characters - & # ? : _ / , . '. A value with any other character (for example @, (, + or accented letters) is rejected with a 400 validation error. Westpac also rewrites some characters before sending them to the bank (& becomes and; #, ?, : and / are removed) and shortens each field to 12 characters.
Quick Payments combine consent and payment into a single API call, ideal for immediate e-commerce payments. Single Consents separate these steps, giving you control over when the payment is initiated — useful for invoice payments or pre-authorisation scenarios.
If you need to accept card payments, use either method with the Gateway flow. See the Card Payments guide for details.
For a detailed comparison of all consent types, see Consent Types.