Quick Start Guide

This guide demonstrates how to create a payment using Gateway Flow with Quick Payments.

Requirements

• BlinkPay Merchant Account (sign up at merchants.blinkpay.co.nz)
• API Credentials (Client ID and Client Secret) from Settings > API Settings; see Getting API Credentials
• A redirect URI registered under Whitelisted Redirect URLs on the same page; see Redirect URI Whitelisting

Step 1: Get Access Token

Request:

POST /oauth2/token HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2: Create Quick Payment

Request:

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

{
  "flow": {
    "detail": {
      "type": "gateway",
      "redirect_uri": "https://www.yourwebsite.com/payment/complete"
    }
  },
  "amount": {
    "currency": "NZD",
    "total": "25.00"
  },
  "pcr": {
    "particulars": "Invoice",
    "code": "12345",
    "reference": "Payment"
  }
}

Response:

{
  "quick_payment_id": "3a3b7f7d-f8e6-4c3e-b2a1-5f9c8d7e6a5b",
  "redirect_uri": "https://sandbox.debit.blinkpay.co.nz/gateway/pay?id=3a3b7f7d..."
}

Step 3: Redirect Customer

Redirect the customer to the redirect_uri from the response. The customer will:

1. See the BlinkPay Gateway
2. Select their bank (ANZ, ASB, BNZ, Kiwibank, or Westpac)
3. Authenticate with their bank
4. Authorise the payment
5. Return to your redirect_uri

Step 4: Handle Return

Customer returns to your redirect_uri with query parameters:

https://www.yourwebsite.com/payment/complete?cid={consent_id}

A return with cid and no status means the outcome was not reported as failed; it is not confirmation. Confirm the outcome with a server-side GET before you act on it. See Return Parameters for the full rules.

Step 5: Check Payment Status

Make this call as soon as the customer returns; 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 rather than treating the payment as failed.

Request:

GET /payments/v1/quick-payments/{quick_payment_id} HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}

Response:

{
  "quick_payment_id": "3a3b7f7d-f8e6-4c3e-b2a1-5f9c8d7e6a5b",
  "consent": {
    "consent_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a",
    "status": "Authorised",
    "creation_timestamp": "2025-12-16T10:00:00+13:00",
    "status_updated_timestamp": "2025-12-16T10:05:00+13:00",
    "detail": {
      "type": "single",
      "flow": {
        "detail": {
          "type": "gateway",
          "redirect_uri": "https://www.yourwebsite.com/payment/complete"
        }
      },
      "pcr": {
        "particulars": "Invoice",
        "code": "12345",
        "reference": "Payment"
      },
      "amount": {
        "total": "25.00",
        "currency": "NZD"
      }
    },
    "payments": [
      {
        "payment_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a",
        "type": "single",
        "status": "AcceptedSettlementInProcess",
        "creation_timestamp": "2025-12-16T10:05:00+13:00",
        "status_updated_timestamp": "2025-12-16T10:06:00+13:00",
        "detail": {
          "consent_id": "9f8e7d6c-5b4a-3c2b-1a09-8f7e6d5c4b3a"
        },
        "refunds": []
      }
    ]
  }
}

Payment Status Values

If the customer declines the payment, the consent status becomes Rejected and consent.payments contains a single payment record with status: Rejected. This means the most recent record in consent.payments tells you the outcome whether the payment was authorised or declined. The exception is a consent that never reached the bank at all — one that was revoked (Revoked), or that ran out of time before the customer authorised it — where consent.payments remains empty. Check consent.status for those cases rather than relying on the payments array.

Sandbox Testing

See Sandbox Test Values for how to produce declines, timeouts and revocations.

Next Steps

• Single Payments - Implement one-off payments with more control
• Recurring Payments - Set up subscriptions and repeat billing