API Policies

Acceptable Use of Services

Use BlinkPay services only in accordance with their intended use, and additionally in accordance with the BlinkPay Acceptable Use Policy.

Security and Load Testing

Prior permission must be obtained before conducting penetration tests or load tests against any BlinkPay environment. Contact support@blinkpay.co.nz to arrange testing windows.

API Rate Limits

The Blink Payments and Blink Data APIs limit how many requests each IP address can send in a short time. The limits allow for normal e-commerce traffic, including the polling intervals recommended on these pages.

When you go over a limit, the API responds 429 Too Many Requests with a Retry-After header giving the number of seconds to wait. Wait at least that long before retrying, and if you are limited again, back off exponentially with some random jitter. Rely on the status and the header, not on the body.

Most rate limiting comes from avoidable traffic:

• Reuse access tokens. Request a new token only when the current one is about to expire; see Token Caching.
• Poll sensibly. Don't poll while the customer is at their bank: use their return to your redirect URI, or a decoupled callback_url, to know when to look, then poll every second until the consent leaves AwaitingAuthorisation. In the direct decoupled flow with no callback, poll every 5 seconds. Blink Payments: poll a payment every second until it is AcceptedSettlementCompleted or Rejected, for a minute or two at most.
• Stop at a terminal state, and pick up anything still in flight with a periodic sweep rather than continuous polling.

If you expect high volumes, for example a sale or a large billing run, email support@blinkpay.co.nz in advance with your expected peak transactions per hour. Security testing and load testing both need prior permission, as above.

API Change Policy

To preserve backward compatibility, breaking changes such as endpoint naming updates or the removal of JSON elements will not occur until a major version (URL) change.

In general, additive changes may be made to request query parameters and JSON responses.

This policy applies only after your Go-Live Date.

Non-Breaking Changes

These may occur at any time without advance notice:

• Addition of new endpoints
• Addition of new optional request parameters
• Addition of new fields in JSON responses
• Addition of new error codes
• Addition of new enum values
• Performance improvements
• Bug fixes

Your Responsibility:

• Design clients to ignore unknown response fields
• Don't rely on field order in JSON responses
• Handle new enum values gracefully

Request Headers

Optional Headers

The following optional headers can be included in API requests:

These headers help banks with fraud detection and compliance. Include them when available.

Terms of Service

These API policies supplement BlinkPay's:

• Terms of Service
• Privacy Policy
• Acceptable Use Policy

In case of conflict, the Terms of Service take precedence.

Questions?

For questions about these policies:

• Email: support@blinkpay.co.nz
• Documentation: merchants.blinkpay.co.nz