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",
"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 |
APPLEPAY | Available | 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.
Card payments are authenticated with 3D Secure, the card issuer's check that the cardholder is the one paying. The issuer may authenticate the cardholder without asking them anything, or ask them to confirm the payment, for example with a code or in their banking app. Apple Pay and Google Pay payments are authenticated by the wallet on the customer's device instead, so the rest of this section does not apply to them.
A payment cannot always be authenticated with 3D Secure, most often because the issuer's 3D Secure service is unavailable or the card is not enrolled in it. What happens then depends on the amount charged, including any surcharge:
| Amount charged | Result |
|---|---|
| Up to a limit BlinkPay sets | The payment can still be authorised. It is not authenticated with 3D Secure, so the card schemes' liability shift does not apply and a fraud chargeback on it is yours to bear (see Chargebacks) |
| Above that limit | The payment is declined with BP060 before the card is charged, so nothing is taken or held. The customer stays in the gateway to try another card or pay by bank (see Declined Cards) |
Not every declined card ends the consent. When 3D Secure fails without the customer being asked to confirm the payment (BP020), or the payment is declined above the 3D Secure limit (BP060), the card is never charged, nothing is held, and the consent stays GatewayAwaitingSubmission. The gateway keeps the customer on the payment screen, tells them their card payment didn't go through, and lets them try another card or pay by bank.
After the third declined card on a consent, the gateway shows the decline on a full screen and returns the customer to your redirect_uri with status=rejected and the display-only error. Your application never receives BP020 or BP060. The consent is still not Rejected: a GET shows it GatewayAwaitingSubmission until it becomes GatewayTimeout at the gateway cutoff (see Timeouts and Deadlines), unless the customer completes it first. For the customer to try again after that return, create a new consent.
Two kinds of decline do end the consent. When the card issuer declines the card as it is charged (also BP020), that attempt used the consent: it ends Consumed with nothing charged, and the gateway shows the decline and returns the customer to your redirect_uri with status=rejected straight away. When the issuer asks the customer to confirm the payment and the customer fails that 3D Secure challenge, the consent becomes Rejected and the customer goes straight back to your redirect_uri with status=rejected, with no gateway screen. Either way, create a new consent for the customer to try again.
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.
Under the card schemes' rules, when a payment has been authenticated with 3D Secure, liability for a fraud chargeback (the cardholder says they did not make the payment) generally shifts to the card issuer rather than to you. That shift does not apply to a payment authorised without 3D Secure authentication, so a fraud chargeback on such a payment is yours to bear. 3D Secure has no bearing on chargebacks for other reasons, such as goods not received.
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, BP050–BP054 and BP060, 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.