BlinkPay supports credit and debit card payments alongside account-to-account (A2A) bank transfers through a single API integration. Card payments are available through the Gateway Flow for one-off payments (both Quick Payments and Single Consents).
When card payments are enabled for your merchant account, the BlinkPay Gateway automatically presents card as a payment option alongside bank accounts. The card payment form securely tokenises card details so that card data never passes through BlinkPay or your systems.
High-level flow:
redirect_uricard_network field identifying the card type usedIn addition to a standard Blink Payments merchant account with the Gateway flow configured, card payments require your own acquirer — i.e. a merchant facility with your bank for card payment settlement. See Onboarding for details on getting set up.
Use the metadata endpoint to confirm card payments are enabled for your account and to discover which card types and networks are available.
GET /payments/v1/meta HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
The response is a JSON array with one entry per bank. When card payments are enabled for your account, the array also contains an entry named Card (bank entries are shortened here):
[
{
"name": "ASB",
"features": {}
},
{
"name": "Card",
"features": {
"card_payment": {
"enabled": true,
"allowed_card_payment_types": [
"APPLEPAY",
"CLICKTOPAY",
"GOOGLEPAY",
"PANENTRY"
],
"allowed_card_networks": ["VISA", "MASTERCARD"]
}
}
}
]
If the Card entry is present, your account can accept card payments (its card_payment.enabled is always true); if card payments are not enabled, there is no Card entry. The allowed_card_payment_types and allowed_card_networks arrays define which options are available to your customers.
For more details on the metadata endpoint, see Metadata.
Card payments use the same endpoints as A2A payments — either Quick Payments or Single Consents with the Gateway flow. No additional request fields are needed; the gateway automatically presents card as a payment option based on your merchant configuration.
POST /payments/v1/quick-payments HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Content-Type: application/json
idempotency-key: d8b2f6a0-4c9e-4d3b-a1f7-5e3c9b7d1a4f
request-id: 0c6a4e2f-9d1b-4f7c-8e5a-3b1d7f9c5e2a
{
"flow": {
"detail": {
"type": "gateway",
"redirect_uri": "https://www.yourwebsite.com/payment/callback"
}
},
"amount": {
"currency": "NZD",
"total": "49.99"
},
"pcr": {
"particulars": "Order1234",
"code": "ONLINE",
"reference": "INV-5678"
}
}
Response:
{
"quick_payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"redirect_uri": "https://gateway.blinkpay.co.nz/redirect/a1b2c3d4-..."
}
Redirect the customer to the redirect_uri. The gateway presents all available payment methods — bank accounts and card — based on your configuration.
The two-step Single Consent flow also supports card payments. Create a single consent with flow.detail.type: "gateway", redirect the customer, and create the payment after authorisation — see Single Payments for the full two-step flow.
On a card, authorising at the gateway reserves the money on the customer's card without handing it over; creating the payment is what actually takes it. No payment exists until you do, so poll the consent rather than a payment while you wait.
Create the payment promptly. A reservation you never turn into a payment is released after 5 days: the money returns to your customer and the consent becomes Revoked, so a new consent is needed to charge them.
By default, the gateway presents all available payment methods and the customer chooses. If you want to pre-select the card payment option, you can optionally include a flow_hint:
{
"flow": {
"detail": {
"type": "gateway",
"redirect_uri": "https://www.yourwebsite.com/payment/callback",
"flow_hint": {
"type": "redirect",
"bank": "Card"
}
}
},
"amount": {
"currency": "NZD",
"total": "49.99"
},
"pcr": {
"particulars": "Order1234",
"code": "ONLINE",
"reference": "INV-5678"
}
}
After the customer completes or cancels payment, they are redirected to your redirect_uri. The return URL always carries cid, the consent ID (for a quick payment, also the quick_payment_id). On anything other than success it also carries status and, usually, a display-only error; branch on status, never on error. The full list is in Return Parameters. The return URL is not proof of payment: always confirm the outcome with a GET from your server.
The following card payment types may be enabled for your merchant account. Available types are returned in the metadata response under allowed_card_payment_types.
| Type | Status | Description |
|---|---|---|
PANENTRY | Available | Traditional card entry — customer manually enters card number, expiry, and CVV in the card payment form |
GOOGLEPAY | Available | Google Pay digital wallet. Tokenised payment via Chrome or Android devices |
CLICKTOPAY | Available | Mastercard Click to Pay. Browser-based digital wallet with stored card credentials |
APPLEPAY | Coming Soon | Apple Pay digital wallet |
| Network | Description |
|---|---|
VISA | Visa credit and debit cards |
MASTERCARD | Mastercard credit and debit cards |
AMEX | American Express cards. Requires a separate acquiring account with Amex |
Visa and Mastercard are enabled by default. Amex can be enabled if you have an acquiring relationship with American Express.
The networks enabled for your account are returned in allowed_card_networks in the metadata response.
After the customer returns from the gateway, poll for the final payment status. The process is the same as for A2A payments — see Single Payments for the full polling guide.
GET /payments/v1/quick-payments/{quick_payment_id} HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Card payment response example:
{
"quick_payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"consent": {
"status": "Consumed",
"card_network": "VISA",
"payments": [
{
"status": "AcceptedSettlementCompleted",
"accepted_reason": "card_network_accepted",
"detail": {
"consent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": {
"currency": "NZD",
"total": "49.99"
}
}
}
]
}
}
(Other fields are omitted for brevity.) The payment's amount is in payments[].detail.amount; on a surcharged payment it also carries surcharge and total_charge (see Surcharging).
A card quick payment has usually finished by the time the customer returns, so the first GET normally shows the outcome. If it doesn't, poll every second until the consent is terminal and the payment is AcceptedSettlementCompleted or Rejected, within your polling window. AcceptedSettlementCompleted is the only status that means the payment succeeded. If the customer declines, the consent is rejected and consent.payments contains a single payment record with status: Rejected, the same as for A2A quick payments.
On a card payment, AcceptedSettlementCompleted with accepted_reason: card_network_accepted means the card processor has accepted the charge. It does not mean the funds are in your bank account: your acquirer settles card funds to you on its own schedule.
A card quick payment still pending 24 hours after authorisation is cancelled and marked Rejected; the customer's hold is released, though their bank can take a few days to show it.
| Payment | Deadline | Result |
|---|---|---|
| Single consent (reservation, two steps) | 5 days without a payment | Reservation released, consent Revoked |
| Quick payment (charge never captured) | 24 hours after authorisation | Authorisation cancelled, payment Rejected |
Every timer on both products is listed in Timeouts and Deadlines.
Unlike bank payments, card payments can be charged back by the customer's card issuer. The BlinkPay API has no chargeback endpoint or status, so a chargeback does not change the payment shown by the API.
Two response fields distinguish card payments from bank A2A payments:
| Field | Location | Card Payment Value |
|---|---|---|
card_network | consent object | One of the network values above, such as VISA or MASTERCARD. Null for bank payments |
accepted_reason | consent.payments[] entries | card_network_accepted for card payments. source_bank_payment_sent for bank payments |
// Example: checking payment type
if (response.consent.payments[0].accepted_reason === 'card_network_accepted') {
const network = response.consent.card_network; // e.g. "VISA" or "MASTERCARD"
console.log(`Card payment received via ${network}`);
} else {
console.log('Bank payment received');
}
Refund a card payment with POST /payments/v1/refunds, using a full_refund or partial_refund (an account_number refund is for bank payments only). Card refunds must be made within 60 days of the payment completing. Request bodies, statuses, polling, idempotency and the full list of refund errors are in the Refunds guide. You do not choose how a card refund is done — BlinkPay checks with the card processor and picks:
| Request | Payment state | What the customer sees |
|---|---|---|
full_refund | The charge has not gone out yet | No charge at all — it is cancelled |
full_refund | The charge has gone out | The original charge, then a refund |
partial_refund | Either | The original charge, then a refund |
If the charge has not gone out yet, cancelling it is cleaner for everyone: the money never leaves your account and nothing appears on your customer's statement. Their bank may still show a pending amount until it releases the reservation on its own. Once the charge has gone out — or when you are returning only part of a payment — the money has already moved, so it comes back as a separate refund that usually reaches your customer within a few business days.
You cannot choose the first, or rely on getting it. Whether the charge has gone out is read from the card processor at the moment you ask, and if that cannot be established BlinkPay sends a refund, which is always valid. So there are only two things you ever need to tell a customer: either they will never see the charge, or they will see it followed by a refund a few business days later.
A payment you have created but whose charge has not completed yet has nothing to send back, and a refund against it returns BP053. Keep polling it: once it reaches AcceptedSettlementCompleted the money has been taken and you can refund it normally. Do not create the payment again — the consent has already been used, and a second attempt returns BP002. If it stays pending, contact support@blinkpay.co.nz.
Once a payment has been partly refunded, a full_refund against it is refused with BP039, because it would claim more than the balance left. Send the remainder as another partial_refund instead. A payment with any refund against it is never cancelled outright either, because cancelling is all-or-nothing and cannot return just the remainder.
Refunds must be enabled for your merchant account, and card refunds are granted separately from bank refunds — contact support@blinkpay.co.nz if you receive BP047 or BP049.
Card payments are typically configured during your initial BlinkPay onboarding. You need your own acquirer (i.e. a merchant facility with your bank) to use card payments — BlinkPay requires your acquirer merchant ID, Merchant Category Code (MCC), and acquirer bank name to complete the setup.
If card payments were not set up during your initial onboarding, contact support@blinkpay.co.nz and the team will guide you through the process. Once configured, verify enablement by calling GET /payments/v1/meta and confirming that the Card entry appears.
Card-specific error codes, such as BP020 and BP050–BP054, are listed in the Error Codes Reference. For general troubleshooting, see the Troubleshooting Guide.
Sandbox Test Card Numbers:
| Network | Card Number | Expiry | CVV |
|---|---|---|---|
| Visa | 4000 0000 0000 2503 | Any | Any |
| Mastercard | 5200 0000 0000 2151 | Any | Any |
For full card payment test scenarios, see the Testing Guide.