Testing Guide

Testing your integration in the sandbox environment is essential before going live with BlinkPay.

Sandbox Environment

Sandbox URL: https://sandbox.debit.blinkpay.co.nz

The sandbox environment provides:

• Full API functionality with mock bank (PNZ)
• Simulated payment flows that settle within seconds
• All consent flows supported (Gateway, Redirect, Decoupled)

Limitations:

• Mock data only (not real customer data)
• Only PNZ mock bank available
• Some bank-specific behaviours simplified

Getting Sandbox Credentials

Sandbox credentials are provisioned when you sign up at merchants.blinkpay.co.nz. If Settings > API Settings shows no sandbox key, select Request Sandbox API Key there. See Getting API Credentials.

Try the Gateway Experience

To see the Gateway flow in action before building your integration, visit our demo site:

ACME Demo Site: https://acme-sandbox.blinkpay.co.nz

This demonstrates the full Gateway payment experience from a customer's perspective.

Sandbox Test Values

The sandbox has one test bank, PNZ: Payments NZ's API Centre test bank, shown as the PNZ tile in the Gateway. Use these values for every flow:

Producing Sandbox Errors

The sandbox can produce these outcomes, so test your handling of each:

Outcomes You Cannot Trigger

Bank-side rejections after authorisation, bank downtime, Fixed Recurring Payment failures, revocation at the bank and consent expiry can't be triggered in the sandbox. Build that handling from the documented statuses and error codes, and finish with a single low-value live payment in production.

Test Scenarios

The primary integration path is the Gateway flow, which hosts the bank selection and handles the redirect or decoupled sub-flow automatically.

Gateway Flow (Recommended)

Objective: Verify end-to-end payment using Gateway

Steps:

1. Create single consent with flow.type: 'gateway'
2. Redirect user to consent.redirect_uri
3. In Gateway: Select PNZ bank → Choose Internet banking website (redirect) or Send to PNZ app (decoupled)
4. For redirect: Login as user01 with password password → Approve
5. For decoupled: Use mobile number +64-259531933 → Auto-approves
6. Handle the return to your redirect_uri: read the cid (consent ID) and status query parameters. No status means the outcome was not reported as failed, not that it succeeded: confirm it with a server-side GET. See Return Parameters
7. Confirm with GET /payments/v1/single-consents/{cid} that the consent status is Authorised
8. Create payment using the consent_id
9. Verify payment status is AcceptedSettlementCompleted

Expected Results:

• Consent status: Authorised
• Payment status: AcceptedSettlementCompleted
• Redirect back to your application

Quick Payment

Objective: Test simplified single-step payment

Steps:

1. Create quick payment via POST /payments/v1/quick-payments and store the quick_payment_id
2. Redirect to Gateway and complete authorisation at PNZ bank
3. As soon as the customer returns, call GET /payments/v1/quick-payments/{quick_payment_id}; the gateway normally does this for you, and calling it again is safe. For a bank payment this call completes the payment. If it returns a 4xx or 5xx, retry the GET.
4. Keep polling the same endpoint until the consent is Consumed and its single payment is AcceptedSettlementCompleted

Enduring Consent (AutoPay)

Objective: Test recurring payment setup

Steps:

1. Create enduring consent via POST /enduring-consents with maximum_amount_period, maximum_amount_payment, and period
2. Complete authorisation via Gateway
3. Create first payment with an amount within limits
4. Verify consent remains Authorised (not Consumed)
5. Create subsequent payments - consent should allow reuse within limits

Card Payment (Gateway)

Objective: Verify card payment flow via Gateway

Steps:

1. Call GET /payments/v1/meta and confirm the response contains a Card entry
2. Create a one-off payment (quick payment or single consent) with flow.detail.type: "gateway"
3. Follow the redirect to the sandbox gateway
4. Select the card payment option
5. Enter one of the test cards below
6. Handle callback at your redirect_uri
7. Poll for payment status — verify AcceptedSettlementCompleted
8. Confirm card_network field is present in the response (e.g. VISA)

Sandbox Test Card Numbers:

Expected Results:

• Consent status: Consumed
• Payment status: AcceptedSettlementCompleted
• accepted_reason: card_network_accepted
• card_network: VISA or MASTERCARD

Error Handling

Test these scenarios to ensure your integration handles errors gracefully:

Timeout: Create a consent and redirect to the Gateway. If you don't select a bank, the consent becomes GatewayTimeout once the 15-minute Gateway session cutoff elapses. If you select PNZ but never complete authorisation, it becomes Rejected once that bank's authorisation window elapses. See Authorisation timeouts.

Rejection: On the PNZ login page, choose Cancel before logging in. The consent status becomes Rejected and you'll receive this in your redirect callback. For quick payments, the consent's payments[] array will contain a single payment record with status Rejected.

Revocation: Authorise a consent (the auto-approve number is quickest), then call DELETE /payments/v1/single-consents/{consent_id} before creating a payment. The consent becomes Revoked, and a subsequent POST /payments/v1/payments fails with 422 BP015.

Next Steps

• Going Live - Production checklist when testing is complete