App-to-App Flow

Blink Payments only: this page applies to the Payment API.

App-to-app return sends the customer straight from their banking app back to your mobile app once they have approved, without passing through a browser on the way back. It builds on the standard Mobile Integration: your app opens the gateway or the bank's page in an in-app browser (SFSafariViewController or Chrome Custom Tabs), and the bank's app does the rest.

Enabled by BlinkPay Support

App-to-app return must be enabled for your account, for each bank, by BlinkPay support. Contact support@blinkpay.co.nz to request it.

Two Kinds of Deep Link

"Deep link" is used for two different things on mobile, and only the second needs this page.

	Opening the bank's app	Returning to your app (app-to-app)
What happens	The bank's authorisation page opens in the customer's banking app instead of the browser	After approving, the banking app opens your app directly
What you set up	Nothing: it depends on the bank	Send `redirect_to_app: true` when you create the consent, once BlinkPay support has enabled it for your account and the bank
Banks	Depends on the bank; see Bank Coverage	ASB and Westpac; see Bank Coverage

redirect_to_app: true asks the bank to return the customer straight to your app. Without it, or if the bank doesn't support it or it isn't enabled for your account, the customer first lands on a BlinkPay page in their phone's browser after approving in their banking app. That page then opens your app through your return link, or, if it can't, asks the customer to return to your app themselves. Either way, the in-app browser you opened is still on screen behind the bank's app.

Supported Banks

ASB and Westpac offer app-to-app return; ANZ, BNZ, Kiwibank and NZHL do not. The per-bank table is in Bank Coverage. For a bank that doesn't offer it, or that has not been enabled for your account, redirect_to_app is silently ignored and the customer returns through your normal return link.

How It Works

App-to-app works with the redirect flow, and with the gateway flow when the customer takes the redirect option. It is not available with the decoupled flow. It works in sandbox and production once enabled for that environment.

Your backend creates the consent or quick payment with redirect_to_app: true and your app's return link as the redirect_uri, and stores the returned ID against the order.
Your app opens the returned redirect_uri in the in-app browser. On mobile the bank's page opens the customer's banking app.
The customer approves in their banking app.
The banking app opens your app's return link with the bank's code and state parameters (or an error), not with cid.
Your app, or your backend on its behalf, passes every query parameter it received, unchanged, to BlinkPay's return endpoint with redirect=false added. On success BlinkPay answers 204 No Content. On a failure it answers with a 302 whose Location carries cid, status and error, so handle both.
Your app closes the in-app browser and asks your backend for the outcome, and your backend GETs the consent or quick payment by the ID it stored. For a quick payment, retrieving it completes the payment, so make this GET straight away (see Handling the Outcome on Mobile).

GET /bank/1.0/return?state={state}&code={code}&redirect=false HTTP/1.1
Host: debit.blinkpay.co.nz

In sandbox, use sandbox.debit.blinkpay.co.nz, the host you created the consent on.

Because the option is silently ignored for a bank that is not enabled, the same return link can also receive a normal return carrying cid (and status on failure). Handle both: forward code and state when they are present, and otherwise treat it as a normal return. Either way, the outcome comes from your backend's GET, never from the link itself.

Getting Started

Contact support@blinkpay.co.nz to request app-to-app return, and say which banks and environments you need.
Provide your app's return link for sandbox and for production.
Register the same links under Settings > API Settings in the Whitelisted Redirect URLs for each environment (see Register Your Return Link).

BlinkPay registers your return link with each participating bank. Approval is at each bank's discretion and timelines vary, so build and test with the standard return (through the browser) in the meantime.

Plan Your URLs Carefully

Return links are difficult to change once registered with banks. Make sure your scheme, host and path are final before you request app-to-app return.

Implementation

Add redirect_to_app: true to the flow details when you create the consent:

POST /payments/v1/single-consents HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "flow": {
    "detail": {
      "type": "redirect",
      "bank": "ASB",
      "redirect_uri": "https://app.example.com/blinkpay/return",
      "redirect_to_app": true
    }
  },
  "amount": {
    "currency": "NZD",
    "total": "50.00"
  },
  "pcr": {
    "particulars": "Order",
    "code": "12345",
    "reference": "Ref"
  }
}

With the gateway flow, set redirect_to_app: true in the gateway flow details; it applies when the customer takes the redirect option.

Configure your app so that the return link reaches the activity or scene that is already running: on Android, the launch mode advice in the Platform Checklist applies, and on iOS, dismiss the in-app browser when the link arrives.

Error Handling

Deep Link Failures

If the device cannot open your app from the return link, for example because the app is not installed, a universal link or App Link opens its web page instead. Create a page at that URL explaining that the app couldn't be opened and that the payment may not have completed. The customer's consent is still there to be checked: your backend can GET it by the ID it stored.