This page lists the error codes returned by the Payment API, with the HTTP status each one comes with. Each error has a code (BPnnn) and a message. Branch on code.
Codes beginning BG are not API errors. They appear on the gateway's error screen and are listed under Gateway Error Codes.
{
"timestamp": "2026-01-15T10:30:00.000+13:00",
"path": "/payments/v1/payments",
"status": 422,
"error": "UNPROCESSABLE_CONTENT",
"message": "Consent has been revoked",
"code": "BP015"
}
Some responses carry no BlinkPay code:
WWW-Authenticate header: Bearer error="invalid_token" when the access token is expired or invalid, and a bare Bearer when no token was sent. Get a new token and retry. The token request itself is the exception: POST /oauth2/token without a client_id or client_secret returns 401 with code BP505 (Missing required parameter: client_id). Retrying won't help: send both.Retry-After header, then back off; see API Rate Limits.Every response carries a request-id header (it echoes yours if you send one). Include it when you contact support.
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP101 | 404 | Consent does not exist | Verify the consent ID is correct |
| BP002 | 422 | Consent already consumed or rejected, including a single consent not paid within 48 hours of authorisation | GET the consent and check payments[0] first. If a payment exists and is not Rejected, it may still settle: poll it rather than creating a new consent. Otherwise create a new consent |
| BP003 | 422 | Enduring consent is past its expiry_timestamp (it is now Consumed) | Create a new consent |
| BP004 | 422 | Consent exceeded request timeout | Customer took too long; create new consent |
| BP011 | 422 | Consent cannot be revoked because it was never authorised (Rejected or GatewayTimeout) | No action needed |
| BP015 | 422 | Consent has been revoked — possibly cancelled by the customer in their banking app | Create a new consent |
| BP017 | 422 | Consent not yet authorised (a payment was created too early) | Customer hasn't approved yet; continue polling |
| BP018 | 422 | Quick payment cannot be processed, for example POST /payments on a quick payment | Don't create payments for a quick payment: GET the quick payment instead |
| BP021 | 422 | Gateway consent timed out (>15 min) | Create a new consent |
| BP026 | 422 | The earlier consent you sent as a decoupled consent_id identifier can no longer identify the customer. How long a consent can be used this way depends on the bank, from a few months to about 2 years after it was authorised, so send the customer's most recent authorised consent | Use another identifier or the redirect flow |
| BP061 | 422 | A payment on an enduring consent was made before the consent is active, that is before its from_timestamp. The message gives the time it becomes active. Nothing was sent to the bank | Retry the payment at or after the time in the message. A payment refused with BP061 does not use up its idempotency-key, so the same key can be sent again once the consent is active, and the payment is then made once |
| BP701 | 409 | Consent was already revoked — either earlier via the API, or by the customer in their banking app | No action needed; create a new consent to take further payments |
| BP707 | 409 | Consent has a payment still settling, so it cannot be revoked yet | Poll the payment until it is terminal, then revoke if still needed |
These 403s mean a feature is not enabled for your account, or a flow is not available at that bank; resending the request unchanged gets the same error.
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP401 | 403 | Your account is not subscribed to PayNow | Contact BlinkPay to enable it |
| BP402 | 403 | Your account is not subscribed to AutoPay | Contact BlinkPay to enable it |
| BP403 | 403 | Enduring consents are not enabled for the bank | Use another bank (see Bank Coverage), or contact BlinkPay |
| BP404 | 403 | The redirect flow is not enabled for the bank | Use another flow or bank (see Bank Coverage), or contact BlinkPay |
| BP405 | 403 | The decoupled flow is not enabled for the bank | Use another flow or bank (see Bank Coverage), or contact BlinkPay |
| BP406 | 403 | Your account is not subscribed to the BlinkPay gateway | Contact BlinkPay to enable it |
| BP407 | 403 | Your account must use the BlinkPay gateway | Create the consent with the gateway flow |
| BP417 | 403 | The decoupled flow is disabled on the BlinkPay gateway for your account | Use a redirect flow hint or no flow hint, or contact BlinkPay |
These mean the request needs fixing; resending it unchanged gets the same error.
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP035 | 422 | Referenced consent is for a different bank | Use a consent ID from the same bank |
| BP214 | 400 | Redirect URI not whitelisted | Register the URI under Settings > API Settings |
| BP215 | 400 | redirect_uri or callback_url is not a valid URI | Send an absolute URI with a scheme and host |
| BP216 | 400 | Bank not configured for merchant | Contact BlinkPay to enable the bank |
| BP235 | 400 | amount or pcr sent when creating a payment on a single consent | Send only the consent_id; the amount and PCR come from the consent |
| BP240 | 400 | Decoupled identifier type not supported by the bank | Use an identifier type listed for the bank in features.decoupled_flow.available_identifiers on the metadata endpoint |
| BP249 | 400 | The decoupled mobile_number identifier is not a valid NZ mobile number | Send an NZ mobile number, for example +64-259531933 |
| BP252 | 400 | An amount is empty, not a number, or not greater than zero | Send a positive amount, for example "25.50" |
| BP264 | 400 | An enduring consent's expiry_timestamp is in the past | Send a future expiry_timestamp, or leave it out |
| BP265 | 400 | Identifier value is not a valid consent ID | Pass a consent ID as the decoupled identifier_value |
| BP276 | 400 | surcharge or total_charge was sent in a consent or quick payment request | Remove them: BlinkPay calculates these fields |
| BP283 | 400 | An enduring consent's from_timestamp and expiry_timestamp fall on the same date | Set the expiry at least one day after the start |
| BP289–BP293 | 400 | callback_url is malformed or is not a public https URL | Send a publicly reachable HTTPS URL (the sandbox also accepts http) |
| BP299 | 400 | Invalid request parameters, for example an ID or an idempotency-key, request-id or x-correlation-id header that is not a UUID | Fix the request; send UUIDs for IDs and those headers |
An idempotency key is bound permanently to the payment it creates. These 409s tell you which of the two situations you are in: the key is still busy with an earlier request (retry later), or it has been spent (use a fresh key).
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP702 | 409 | Duplicate idempotency key with different payload | Use a unique idempotency key per distinct request |
| BP703 | 409 | The named payment is still in flight | Poll the payment ID in the message until it reaches a terminal status; don't resubmit |
| BP708 | 409 | A payment request with this key is still in progress | Retry with the same key after a few seconds |
| BP709 | 409 | The consent was changed by another request at the same time | Retry the request |
| BP710 | 409 | The key was already used by a payment that is now terminal | Read the status in the message: Rejected means you may re-submit under a fresh key, AcceptedSettlementCompleted means the money already moved and you must not |
| BP711 | 409 | A concurrent refund request holds the same key | Retry the same request with the same key shortly |
| BP712 | 409 | Another request on this consent is submitting a payment | GET the consent's payments before retrying |
| BP713 | 409 | Duplicate of a payment made in the same minute without an idempotency-key | Always send an idempotency-key |
| BP714 | 409 | A consent or quick payment create with this key is still in progress. No second consent was created and nothing reached the bank | Retry with the same key after a few seconds; once the first request finishes, the retry returns its response |
| BP715 | 409 | The charge went out while the refund was being processed, so it could no longer be cancelled | Retry the refund with a new idempotency key — the money will be sent back as a refund instead |
See Refunds.
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP012 | 422 | The payment is not AcceptedSettlementCompleted | Poll the payment until it settles, then refund it |
| BP013 | 422 | The refund type is not supported for this payment, for example account_number on a card payment | Use full_refund or partial_refund for a card payment |
| BP014 | 422 | The consent does not support refunds: the payer's account number could not be obtained, so an account_number refund cannot be made | Contact BlinkPay support |
| BP039 | 422 | The refund would take the total refunded above the payment amount, for example a full_refund after a partial one | Refund only what remains, with a partial_refund |
| BP045 | 422 | The card payment settled more than 60 days ago | Contact BlinkPay support |
| BP046 | 422 | The card payment has already been refunded or reversed | No action needed |
| BP047 | 422 | Refunds are not enabled for the merchant | Contact BlinkPay support to have refunds enabled |
| BP048 | 422 | full_refund or partial_refund on a bank payment | Use an account_number refund and pay the customer back yourself |
| BP049 | 422 | Card refunds are not enabled for the merchant | Contact BlinkPay support — card refunds are granted separately from bank refunds |
| BP053 | 422 | The payment's charge has not completed yet, so there is no money to send back | Poll the payment until it reaches AcceptedSettlementCompleted, then refund it. Do not re-create the payment — the consent is already used |
| BP110 | 404 | Refund does not exist | Verify the refund ID is correct |
| BP111 | 404 | This refund type is not supported for this transaction (the payer's account number could not be found) | Contact BlinkPay support |
| BP903–BP905 | 502 | The card processor's answer to the refund is unknown | GET the refund to check its status before retrying |
| BP906–BP908 | 502 | The card processor's answer to a cancellation is unknown | GET the payment and check its refunds[] before retrying |
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP020 | 422 | Card payment declined | Not returned by the API. When 3D Secure failed, the customer can try another card or pay by bank in the gateway; when the issuer declined the charge, the consent has ended as Consumed. See Declined Cards |
| BP036 | 422 | The bank refused the payment for this consent period | Enduring consent: the bank counts this payment in a period whose allowance is used up; try again in the next period (see Period Calculation). Single consent: the consent stays Authorised, so once the cause is resolved you may try again with a new idempotency-key |
| BP044 | 422 | An enduring-consent payment would take the period's total above maximum_amount_period | Wait for the next period, or take a smaller amount |
| BP102 | 404 | Payment does not exist | Verify the payment ID is correct |
| BP109 | 404 | Quick payment does not exist | Verify the quick payment ID is correct |
| BP229 | 400 | The amount is over the bank's payment limit | Lower the amount; see Payment Limits and payment_limit on the metadata endpoint |
| BP230 | 400 | The amount is over your merchant account's payment limit | Lower the amount, or contact BlinkPay support to change your merchant limit |
| BP262 | 400 | An enduring-consent payment is larger than maximum_amount_period | Lower the amount |
| BP263 | 400 | An enduring-consent payment is larger than maximum_amount_payment | Lower the amount |
| BP277 | 400 | With surcharging (fee forwarding), the amount including the surcharge is over your merchant payment limit (for an enduring consent, the maximum amount) | Lower the amount or the maximum, or contact BlinkPay support to change your merchant limit |
| BP287 | 400 | An enduring consent without maximum_amount_payment has a maximum_amount_period over the bank's payment limit, because a single payment could draw the whole period amount | Send a maximum_amount_payment at or below the bank's limit |
| BP288 | 400 | As BP287, but the maximum_amount_period is over your merchant account's payment limit | Send a maximum_amount_payment at or below your limit, or contact BlinkPay support |
See the Fixed Recurring Payments guide for how start_date is resolved.
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP009 | 422 | Start date is in the past | Use today or a future date (NZ timezone) |
| BP023 | 422 | Start date is before the consent's from_timestamp | Use a date on or after the consent's activation date |
| BP024 | 422 | Start date is after the consent's expiry_timestamp | Use a date inside the consent window, or create a new consent |
| BP025 | 422 | The consent has already expired | Create a new consent |
| BP030 | 422 | daily schedule cannot start today — submitted after 21:45 NZ | Set start_date to tomorrow |
| BP038 | 422 | daily schedule whose consent only becomes active after 21:45 NZ on start_date | Set start_date to the following day |
| BP108 | 404 | Fixed recurring payment does not exist | Verify the schedule ID is correct |
| BP705 | 409 | Duplicate fixed recurring payment | Only one active schedule is allowed per consent |
| BP706 | 409 | Fixed recurring payment already cancelled | No action needed |
These errors are specific to card payment processing. For a detailed troubleshooting guide, see Card Payments.
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP050 | 422 | The consent is a card Quick Payment, which completed at the gateway | Nothing to do — a Quick Payment has no separate payment step |
| BP051 | 422 | The card consent is not authorised, so there is no payment to create | Wait for the customer to authorise at the gateway, then create the payment |
| BP052 | 422 | The card consent carries no card authorisation | Contact BlinkPay support |
| BP054 | 422 | The card consent has already been authorised | Create the payment, or let the reservation be released; do not authorise the same consent twice |
| BP060 | 422 | The card could not be authenticated with 3D Secure (for example, the issuer's 3D Secure was unavailable or the card is not enrolled) and the amount, surcharge included, is over BlinkPay's limit for such payments. The card was not charged | Not returned by the API: the customer can try another card or pay by bank in the gateway. See Declined Cards |
| BP256–BP258 | 400 | Card payment set-up details are missing | Complete card payment onboarding with BlinkPay; contact support if it persists |
| BP259 | 400 | Card transient token missing from the request | Send the transient token from the card capture step |
| BP260 | 400 | No card payment types configured | Complete card payment onboarding with BlinkPay |
| BP261 | 400 | No card networks configured | Complete card payment onboarding with BlinkPay |
| BP270 | 400 | Card payment set-up is incomplete | Contact BlinkPay to complete card onboarding |
| Code | HTTP | Description | Resolution |
|---|---|---|---|
| BP601 | 503 | Bank service unavailable | Retry with backoff, using the same idempotency-key for a POST; check for maintenance |
| BP602 | 503 | BlinkPay is temporarily unavailable | Retry after the Retry-After time, using the same idempotency-key for a POST |
| BP603 | 503 | The bank refused the consent; no payment was sent | GET the consent to check its status before trying again |
For a request that times out or returns another 5xx with no clear answer, see If a Request Times Out.
For errors not listed here or for assistance troubleshooting:
message field for specific detailsrequest-id from the response