Blink Payments Essentials

The facts most Blink Payments integrations need, on one page. Each section links to the page with the detail.

Base URLs and Token Endpoint

API paths sit under /payments/v1, for example POST /payments/v1/quick-payments. Get a token with the OAuth 2.0 client credentials grant; it lasts one hour, so reuse it until it expires. Keep the client secret on your server, never in a browser or mobile app. See Authentication.

Credentials and Going Live

Sandbox credentials are provisioned when you sign up at merchants.blinkpay.co.nz. On Settings > API Settings, open the Sandbox row, copy the API Client ID and select Rotate Secret to get a secret, which is shown once. If there is no sandbox key, select Request Sandbox API Key on that page. Register each redirect_uri under Whitelisted Redirect URLs on the same row; an unregistered one is rejected with 400 BP214.

For production, select Upgrade to Production. An Administrator submits the application, and approval usually takes 1-3 business days. See Getting API Credentials and Going Live.

Choosing a Flow

Use the gateway flow unless you need something else: BlinkPay hosts bank selection and authorisation. For a one-off payment, a quick payment (POST /payments/v1/quick-payments) creates the consent and the payment in one call; see Single Payments. For AutoPay, see Recurring Payments. Server-side SDKs are listed in SDK Overview.

Sandbox Test Values

Any other decoupled number is accepted but never authorises. See Testing.

Return Parameters

When the customer comes back to your redirect_uri, the query string carries cid, the consent ID (for a quick payment, the same value as quick_payment_id). Only when the outcome is not success does it also carry status (cancelled, rejected, timeout or error; the gateway can also send pending) and a customer-safe error message. There is no success value: a return without status means the outcome was not reported as failed. Always confirm the outcome with a server-side GET. See Return Parameters.

The Success Rule

AcceptedSettlementCompleted is the only payment status that means the payment succeeded: the payer's bank has confirmed sending the funds. Pending and AcceptedSettlementInProcess are still in progress, and Rejected has failed. A Consumed consent means the consented action is complete, not that the payment succeeded, so read the payment's status; consent.payments[0] is the newest payment.

For a quick payment, retrieve it with GET /payments/v1/quick-payments/{quick_payment_id} as soon as the customer returns; the gateway normally does this for you, and that call completes the payment. See Payment Lifecycle.

Polling

Don't poll while the customer is at their bank. Once they return, or the decoupled callback_url fires, read the consent or quick payment straight away, then poll every second until the payment is AcceptedSettlementCompleted or Rejected, for a minute or two at most. Leave anything still in progress to a periodic wash-up. In the direct decoupled flow with no callback, poll the consent every 5 seconds for the bank's authorisation window. See Polling.

Idempotency

Send an idempotency-key header with a new UUID on every POST that creates a consent, payment or refund, and send the same key when you retry that request: you get the original back rather than a duplicate. Gateway-flow consents are de-duplicated on the request-id header instead. See If a Request Times Out.

Limits

Each bank has its own payment limits, which differ between PayNow and AutoPay; see Transaction Limits. payment_limit on GET /payments/v1/meta gives BlinkPay's current per-payment maximum for each bank, and a payment over it is rejected with 400 BP229. The minimum payment is $0.01, and your account has its own limit, which support can change.

If you expect high volume, tell support in advance. See API Policies.

Errors and Help

Blink Payments error codes start with BP; see Error Codes. For common problems, see Troubleshooting.