Payment Lifecycle

Payments in BlinkPay progress through a defined lifecycle from initiation through settlement. Understanding these states helps you provide accurate payment tracking and handle edge cases appropriately.

Payment States Overview

┌─────────┐     ┌─────────────────────────────┐     ┌─────────────────────────────┐
│ Pending │ ──► │ AcceptedSettlementInProcess │ ──► │ AcceptedSettlementCompleted │
└─────────┘     └─────────────────────────────┘     └─────────────────────────────┘
     │                         │
     │ (if declined)           │ (if the bank rejects it after accepting)
     ▼                         │
┌──────────┐                   │
│ Rejected │ ◄─────────────────┘
└──────────┘

State Descriptions

Pending

Initial state immediately after payment creation

The payment has been created via the BlinkPay API and submitted to the customer's bank for processing.

Typical duration: Seconds to minutes

Next states:

• AcceptedSettlementInProcess - Bank accepted and is processing
• Rejected - Bank rejected the payment

What's happening:

• Bank is validating the payment request
• Checking account status and available balance
• Applying fraud detection and compliance checks
• Determining if payment can be processed

Merchant actions:

• Display "Payment processing" status to customer
• Don't assume success until state changes
• Have timeout handling (typically resolves within minutes)

AcceptedSettlementInProcess

Bank has accepted and is processing the payment

The customer's bank has accepted the payment and initiated the settlement process through the BECS (Bulk Electronic Clearing System).

Typical duration: 1-2 hours (can be longer for late-day payments)

Next states:

• AcceptedSettlementCompleted - Payment sent via BECS
• Rejected - Bank rejected the payment at settlement time (rare but possible)

What's happening:

• Funds are being debited from customer's account
• Payment is queued for BECS settlement
• Bank is preparing the direct credit instruction
• Payment will be included in next BECS batch

Merchant actions:

• Display "Payment in progress" or "Processing" to customer
• The payment is not yet successful: the bank can still reject it
• Final confirmation will come with AcceptedSettlementCompleted

AcceptedSettlementCompleted

Payment sent to merchant's bank via BECS (Final state)

The customer's bank has successfully sent the payment through BECS Direct Credit. This means the funds have been sent from the customer's bank to your merchant bank account.

What this means:

• Funds have been sent by the customer's bank
• Payment instruction is in the BECS system
• Your bank should receive funds shortly

What this doesn't mean:

• Funds are not guaranteed to be in your account yet
• Your bank may still be processing the incoming payment
• In rare cases, payments can still be reversed (e.g., account closed)

Typical timing:

• Most payments reach merchant bank within 2 hours
• Check your bank statement for actual receipt
• Settlement runs 365 days a year, including weekends and public holidays, within the daily SBI operating window

Merchant actions:

• This is the only status that means the payment succeeded: the payer's bank has confirmed sending the funds
• Send your own confirmation to the customer: BlinkPay does not send receipts to your customers
• Reconcile with bank statements using PCR fields

For a card payment, AcceptedSettlementCompleted (with accepted_reason: card_network_accepted) means the card network accepted the charge; the BECS detail on this page applies to bank payments.

Rejected

Bank rejected the payment (Final state)

The payment was rejected by the customer's bank and will not be processed.

For quick payments, a payment record with status: Rejected is also created when the consent is declined or times out at the bank. In those cases the consent is Rejected too; check consent.status to tell them apart from a payment the bank rejected after the customer authorised it.

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.

Common reasons a bank rejects a payment:

The API does not say which of these applied: neither the payment nor the consent has a rejection-reason field.

Merchant actions:

• Notify customer of payment failure, suggesting they check with their bank
• Offer alternative payment methods
• Don't automatically retry (address underlying issue first)
• Log rejection for analysis

State Transition Timeline

Time    State                           Action
------  ------------------------------  --------------------------------
0s      [Payment Created]
0-30s   Pending                         Bank validates payment
30s     AcceptedSettlementInProcess     Bank accepts, queues for BECS
2hr     AcceptedSettlementCompleted     Payment sent via BECS
2-4hr   [Funds in merchant account]     Merchant bank receives funds

Settlement Process

BECS Direct Credit

All BlinkPay payments use New Zealand's BECS (Bulk Electronic Clearing System) for Direct Credit transfers.

How BECS works:

1. Customer's bank debits their account
2. Payment instruction sent to BECS network
3. BECS routes payment to merchant's bank
4. Merchant's bank credits merchant account

Settlement timing:

• BlinkPay payments clear through BECS and settle via Settlement Before Interchange (SBI365), which processes 365 days a year — including weekends and public holidays
• Settlement runs multiple times a day within the daily SBI operating window (approx. 9am–midnight NZ time); payments made outside this window complete when it next opens
• Timing is also subject to individual bank processing schedules

Settlement Guarantees

Best practice:

• Treat AcceptedSettlementCompleted as the only success status
• Reconcile with actual bank statements
• Have process for handling rare post-settlement reversals

Determining settlement: which fields to trust

Use payment.status = AcceptedSettlementCompleted as the only signal that the payment has succeeded and the payer's bank has sent the funds. Do not use consent.status to determine this — a Consumed consent means the consented action is complete (the bank has made its final decision on the payment), not that the payment succeeded.

Settlement Speed

When the money arrives in your account depends on settlement: the funds reach you once the payment settles. Settlement timing varies based on when the payment is initiated and the participating banks' processing schedules. Payments clear through BECS and settle via SBI365, which runs 365 days a year within a daily operating window (approx. 9am–midnight NZ time). Most payments settle within about 2 hours; a payment initiated outside the operating window completes once it next opens.

Factors affecting settlement:

• Time payment is initiated
• Individual bank processing schedules
• Time of day relative to the daily SBI operating window
• BECS batch processing times

Checking Payment Status

Polling

Retrieve payment status via API:

GET /payments/v1/payments/{payment_id} HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}

Poll only once you have a reason to look, then poll quickly:

The bank's authorisation window is roughly 4-10 minutes; read it from redirect_flow.request_timeout or features.decoupled_flow.request_timeout on the metadata endpoint.

Most payments reach a final status within seconds. One that is still Pending or AcceptedSettlementInProcess when your polling window ends is not a failure: stop polling and leave it to the wash-up.

Quick payments: for a bank payment, 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 it, and read the outcome from consent.payments[0].status.

A payment made late in the day may not settle until the next morning (see Settlement Speed). Leave such a payment to your wash-up rather than polling for it, and reconcile against your bank statement as the final source of truth.

consent.payments lists the newest payment first, so payments[0] is always the most recent.

Notifications and Webhooks

Read the consent or payment to learn its state (see Polling). BlinkPay sends two kinds of notification:

Revocation: a consent revoked at the customer's bank is not pushed to you: it shows as Revoked on your next GET /payments/v1/enduring-consents/{consent_id}, and POST /payments on a revoked consent returns 422 BP015. If the consent has an active Fixed Recurring Payment, the schedule is cancelled and you receive a fixed-recurring-payment-cancelled webhook.

Which IDs to Store

Store these IDs server-side, against your order, before you send the customer to their bank. The customer may never return to your site, and the return URL carries only cid.

The IDs do not change. Keep them as long as you may need to reconcile the payment or refund it.

If a Request Times Out

Send an idempotency-key header (a UUID you generate, new for each distinct payment) on every POST. If a request times out or returns a 5xx, you don't know whether it succeeded, so retry it with the same key: if the first attempt created something, you get it back rather than a duplicate. (Gateway-flow consents are de-duplicated on the request-id header instead, so resend the same request-id.)

If you are still unsure, GET the consent and inspect payments[0] before doing anything else. Never create a new consent until you know the old one has no payment that may still settle, or the customer could be charged twice. After a Rejected payment, use a new key.

Payment Reconciliation

Using PCR Fields

Match payments to bank statements using Particulars, Code, and Reference (PCR) fields. Each field supports up to 12 characters.

Run a periodic wash-up

Real-time polling resolves the vast majority of payments quickly, but some are still reported by the bank as non-terminal (Pending or AcceptedSettlementInProcess) when your polling window ends — for example payments initiated late in the day (outside the SBI operating window) or during a bank maintenance window. If your integration stops polling at that point, those payments can be left in a stale state in your own records even though the bank later resolved them.

To catch these, run a recurring wash-up (a sweep) on a schedule that suits your business — every 12 hours is a sensible default, but anything from a few hours to daily works depending on volume and how quickly you need certainty:

1. Query your own records for any payment you still hold as Pending or AcceptedSettlementInProcess and older than your normal polling window (e.g. older than 6 hours, or from a previous day).
2. Re-fetch each one via GET /payments/v1/payments/{payment_id} to pull it to its current status.
3. Update your records to the bank's terminal status (AcceptedSettlementCompleted or Rejected) and reconcile it against your bank statement.

Refunds

Refund a payment once it is AcceptedSettlementCompleted, using POST /payments/v1/refunds. Bank payments take an account_number refund (you pay the customer back yourself); card payments take a full_refund or partial_refund. See Refunds.

Troubleshooting

Long-Running Pending Status

Settlement Timing

Settlement runs 365 days a year, including weekends and public holidays (SBI365), so weekend and holiday payments are no longer held to the next business day. Payments initiated outside the daily SBI operating window (approx. 9am–midnight NZ time) complete once it next opens. Settlement timing remains subject to individual bank processing schedules.