When you use the Gateway Flow, BlinkPay provides the screens a customer sees between your checkout and their bank. When you use the Redirect Flow or Decoupled Flow directly, you build those screens yourself, and getting them right becomes your responsibility. This page sets out what that involves, for Blink Payments and Blink Data alike.
| Gateway feature | What it does |
|---|---|
| Bank selection | Lists the banks enabled for the consent, by name and logo |
| Flow selection | Offers the ways the customer's bank supports on their device: the bank's internet banking website, opening the bank's app, or sending the request to the bank's app (the redirect and decoupled flows), including the waiting screen and countdown while a decoupled request is approved in the app |
| Confirmation screen | Blink Payments: shows who is being paid, the amount and the payment reference (particulars, code and reference) before the customer goes to their bank, with any surcharge and the total where surcharging is enabled for your account |
| Bank limit warnings | Blink Payments: warns the customer when the amount is over their bank's payment limit and asks them to choose another bank, and shows ANZ's notice that Voice ID is needed for payments over $10,000 |
| Opening the banking app | On a mobile device, opens the customer's banking app directly for the banks that support it; other banks continue in the browser |
| Timeouts and pending states | Counts down the bank's authorisation window and tells the customer when an outcome is still being confirmed |
When the customer has finished, the gateway returns them to your redirect_uri in the browser. If your front end is a mobile app, make that a link that opens your app (see Register Your Return Link).
With a direct flow, you are responsible for following the Payments NZ API Centre Customer Experience Guidelines v3.0, the industry standard for how payment and account access consents are presented to New Zealand customers. Read them before you design your screens. The sections below are BlinkPay's own guidance, and they do not replace the guidelines. Much of it is what the gateway does for you (see What the Gateway Provides); with the gateway, only Showing the Outcome and Letting Customers Revoke remain yours.
The gateway's confirmation screen covers this. With a direct flow, show the customer exactly what they are about to approve, on a screen they confirm before you create the consent or send them to their bank. Their bank shows the request again, and the two should match.
Blink Payments: for a PayNow payment, show the payee as your customers know you, the amount, and the reference that will appear on their bank statement. If you add a surcharge, show it and the total separately before the customer proceeds. For AutoPay, show who will take the payments, the maximum per period and the period itself (for example weekly or monthly), any maximum for a single payment, when the agreement starts and when it ends, and how the customer can cancel it.
Blink Data: show which information you will access (for example account details, balances, transactions or statements), why you need it, how long your access lasts, and for transactions the date range you will read. Ask only for the permissions you use.
Tell the customer what happens next. With the redirect flow they go to their bank's website or app and come back to you afterwards. With the decoupled flow the request goes to their banking app: some banks send a push notification, and with others the customer opens the app and checks its notifications or messages. In every flow the customer chooses the account at their bank, so never ask for an account number on your own screens.
Offer every supported bank your account has enabled, using the bank names and logos customers recognise, and don't steer customers towards one bank. Bank Coverage lists the banks, the flows each supports and, for the decoupled flow, the identifier each accepts (see Decoupled Flow Identifiers).
Blink Payments: check the amount against the bank's limit before the customer chooses, so they can pick another bank rather than fail at theirs. The limits are in Payment Limits, and GET /payments/v1/meta returns each bank's current payment_limit at runtime. Tell ANZ customers that ANZ needs Voice ID for payments over $10,000.
Only show success once your backend has confirmed it with the API. The return redirect and the decoupled callback tell you when to look, not what happened (see Credential and Integration Security). While you check, show a "checking your payment" or "waiting for your bank" state, not a failure.
Blink Payments: keep three states apart. A payment is pending while it is Pending or AcceptedSettlementInProcess, paid once it is AcceptedSettlementCompleted, and failed if it is Rejected. An Authorised consent means the customer approved it, not that money has moved. Most payments move within seconds; check every second until the payment reaches AcceptedSettlementCompleted or Rejected, pick up any still in flight with a periodic wash-up, and contact support with the consent ID and payment ID if one is still Pending after 6 hours. BlinkPay does not send receipts to your customers, so confirm the payment to them yourself.
Blink Data: the consent is Authorised when the customer has granted access. If it is Rejected, or the bank's authorisation window passed, tell the customer nothing was shared and offer to try again.
Don't poll while the customer is at their bank. Once they have returned, or the decoupled callback has fired, check the consent every second until it leaves AwaitingAuthorisation; in the direct decoupled flow with no callback, check every 5 seconds. If the customer returned with a non-success status, you can show the accompanying error text, which is written for customers, but base your own logic on status and the API.
Customers can always revoke a consent at their bank, through internet banking or the bank's app. Give them a way to do it with you as well, through the same channel they used to set it up, such as the account or settings area of your website or app, and show them which consents are active. Revoke the consent through the API when they ask (Blink Payments: DELETE on the single or enduring consent; Blink Data: DELETE /v1/consents/{consent_id}).
A revocation made at the bank is not pushed to you: read the consent before relying on it, and it shows as Revoked. Check before relying on a consent, and tell the customer if an AutoPay agreement or data access has ended.
Before you go live, check your screens against the Going Live checklist.