Gateway Integration

This guide shows how to implement the Gateway Flow for payment integrations (PayNow and AutoPay). For a conceptual overview of how Gateway Flow works, see Gateway Flow.

Quick Start

This guide covers the payment-specific steps. The full request bodies for each consent type are on Gateway Flow, and the client libraries that wrap these calls are listed on SDKs. You'll learn how to:

• Create payment consents with Gateway Flow
• Handle customer redirects and callbacks
• Process one-off and recurring payments
• Implement complete e-commerce and subscription flows

Integration Steps

Step 1: Create Consent with Gateway Flow

Specify the gateway flow type when creating a consent:

For Single Payments (Quick Payment):

Specify the gateway flow type with your redirect URI and flow hint.

For Single Consents:

Create a single consent with the gateway flow type and redirect the customer to the returned redirect URI.

For Recurring Payments (Enduring Consent):

Create an enduring consent with the gateway flow type, maximum amount period, and redirect the customer to the returned redirect URI.

Step 2: Redirect Customer to Gateway

Your backend should securely pass the redirect_uri to your frontend, which then redirects the customer to the gateway. The Gateway will:

1. Display available banks
2. Allow customer to select their bank
3. Let customer choose authentication method (redirect or decoupled)
4. Handle the authentication flow
5. Return the customer to your redirect_uri with the consent ID as cid (plus status and error when the outcome isn't a success)

HTML Example:

<a href="{{ redirect_uri }}" class="btn-pay"> Continue to Payment </a>

Step 3: Handle the Callback

When the customer completes authentication, they'll be redirected back to your redirect_uri:

https://yourapp.com/payment/callback?cid={consent_id}

cid is always present; for a quick payment it is the quick_payment_id. When the outcome isn't a success, the gateway adds status (cancelled, rejected, timeout, error, or pending while the outcome is still unknown) and, usually, a display-only error message. There is no success value. Branch on status, never on error. The full table is in Return Parameters.

Step 4: Verify and Process Payment

Always verify the outcome via the API before you act on it: the redirect URL does not indicate the final result and is not proof of payment.

For a quick payment, call GET /payments/v1/quick-payments/{quick_payment_id} 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, so don't delay it. Read the outcome from consent.payments[0].status.

For a single or enduring consent, retrieve the consent and, once it is Authorised, create the payment with POST /payments/v1/payments. For a single consent send only the consent_id; for an enduring consent include the amount and PCR. See Single Payments and Recurring Payments.

Configuration

Redirect URI Requirements

Your redirect URI must:

• Be registered in the BlinkPay portal under Settings > API Settings (Whitelisted Redirect URLs), separately for sandbox and production
• Not use http:// or localhost in production (both are allowed in sandbox); a mobile app's custom scheme such as myapp://callback is allowed in both
• Handle both success and failure scenarios
• Accept the cid, status and error query parameters

Timeout Handling

Every timer on both products is listed in Timeouts and Deadlines.

A Gateway consent is bound by two successive windows — the Gateway session cutoff while the customer is still choosing a bank, then that bank's own authorisation window. Both are covered in Authorisation timeouts.

Either way the customer returns to your redirect_uri, so always verify the outcome via the API and prompt the customer to retry with a new consent if the consent didn't reach Authorised.

Mobile Considerations

The Gateway is responsive and works in mobile browsers. On a phone it opens the customer's banking app where the bank supports it, and offers "Send to app" (the decoupled flow) where the bank supports it. When the customer finishes, the gateway sends them to your redirect_uri; to land back in your app, use a custom scheme or universal link registered as a redirect URI.