The facts most Blink Data integrations need, on one page. Each section links to the page with the detail.
| Environment | Base URL | Token endpoint |
|---|---|---|
| Sandbox | https://sandbox.data.blinkpay.co.nz | POST https://sandbox.data.blinkpay.co.nz/oauth2/token |
| Production | https://data.blinkpay.co.nz | POST https://data.blinkpay.co.nz/oauth2/token |
API paths sit under /v1, for example POST /v1/consents; the token endpoint sits at the host root. Get a token with the OAuth 2.0 client credentials grant; it lasts one hour, so reuse it until it expires. You don't request scopes: the token carries the ones assigned to your API client. Keep the client secret on your server, never in a browser or mobile app. Blink Data has no SDK; call it over HTTPS, and try requests with the Postman Collection. See Authentication.
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 BDT211.
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.
POST /v1/consents takes a flow, whose flow.detail.type is gateway, redirect or decoupled, and the permissions you need (ReadAccounts, ReadBalances, ReadTransactions, ReadStatements, ReadParty). expiration_date_time is optional; leave it out for a consent that doesn't expire. start_date_time and end_date_time set the window of data the consent covers. A gateway flow_hint sits beside flow.detail and must name a bank (400 BDT260 without one). Blink Data consents don't take a metadata object. See Quick Start and Consent Duration.
| Item | Value |
|---|---|
| Test bank | PNZ, the only bank in the sandbox |
| Redirect or gateway login | Username user01, password password |
| Decoupled, auto-approve | Mobile number +64-259531933 |
| Decline | Cancel on the PNZ login page, before logging in |
Any other decoupled number is accepted but never authorises. A bank your organisation isn't set up for returns 400 BDT213. See Testing.
When the customer comes back to your redirect_uri, the query string carries cid, the consent 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 with GET /v1/consents/{consent_id}. See Return Parameters.
Authorised means you can read data. Rejected, Revoked, Consumed (the consent period has ended) and GatewayTimeout are final; create a new consent. Don't poll while the customer is at their bank. Once they return, read the consent and, if it isn't final yet, poll it every second. In the decoupled flow, wait for the callback_url or poll every 5 seconds. See Consent Lifecycle.
Every data endpoint takes the consent as ?consent_id=. Lists are paged with page and size (at most 500); see Pagination. Date filters need a time zone offset: use Z, or encode + as %2B. To read new data later, call the endpoints again with the same consent_id; the customer doesn't need to do anything until the consent expires or is revoked. See Data Retrieval and Refreshing Data.
Send an idempotency-key header with a UUID on each POST /v1/consents, and send the same key when you retry: you get the original consent back rather than a second one. Keys are remembered for 24 hours. The same key with a different body is rejected with 409 BDT701. See Idempotency.
If you expect high volume, tell support in advance. See API Policies.
Blink Data error codes start with BDT; see Error Codes. For common problems, see Troubleshooting.