Collect funds with Open Banking, UPI, wallets, bank transfer and QR codes

Payment methods

Pick a category, then jump to a method to see how it works, its request fields and an example.

Alternative Cards Wallets Redirects

Jump to Open Banking UPI E-wallets Bank Transfer QR Code Direct API Integration

Open Banking

Overview Integrate

Bank-initiated payment via Open Banking APIs. Send one request to /api/transactions/payment with method set to OPEN_BANKING. Most methods redirect the customer to the provider, and the final status arrives by webhook.

method: OPEN_BANKING
Endpoint: POST /api/transactions/payment
Optional fields: description, customer, country, customer_ip, metadata, return_url, options, originator_url

Required fields

Field	Description
`terminal_id`	Must support payment transactions (`TRX_TYPE_PAYMENT`).
`reference`	Unique per terminal, max 80 characters. Idempotent: the same reference with the same amount and currency returns the existing transaction.
`method`	One of `OPEN_BANKING`, `UPI`, `WALLETS`, `BANK_TRANSFER` or `QR_CODE`.
`currency`	ISO 4217 currency code.
`amount`	Integer in minor units, e.g. `10000` = 100.00. Decimal values are rejected.

Payments reference Direct API Integration

cURLNode.js

POST /api/transactions/payment

curl -X POST https://api.altitudepay.solutions/api/transactions/payment \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "TERM001",
    "reference": "ORDER-123456",
    "method": "OPEN_BANKING",
    "amount": 10000,
    "currency": "EUR",
    "return_url": "https://shop.example/return"
  }'

POST /api/transactions/payment

const res = await fetch('https://api.altitudepay.solutions/api/transactions/payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    terminal_id: 'TERM001',
    reference: 'ORDER-123456',
    method: 'OPEN_BANKING',
    amount: 10000, // minor units
    currency: 'EUR',
    return_url: 'https://shop.example/return',
  }),
});

const { status, redirect } = await res.json();
// PENDING: send the customer to the provider via redirect

UPI

Overview Integrate

Unified Payments Interface (India). Send one request to /api/transactions/payment with method set to UPI. Most methods redirect the customer to the provider, and the final status arrives by webhook.

method: UPI
Endpoint: POST /api/transactions/payment
Optional fields: description, customer, country, customer_ip, metadata, return_url, options, originator_url

Required fields

Field	Description
`terminal_id`	Must support payment transactions (`TRX_TYPE_PAYMENT`).
`reference`	Unique per terminal, max 80 characters. Idempotent: the same reference with the same amount and currency returns the existing transaction.
`method`	One of `OPEN_BANKING`, `UPI`, `WALLETS`, `BANK_TRANSFER` or `QR_CODE`.
`currency`	ISO 4217 currency code.
`amount`	Integer in minor units, e.g. `10000` = 100.00. Decimal values are rejected.

Payments reference Direct API Integration

cURLNode.js

POST /api/transactions/payment

curl -X POST https://api.altitudepay.solutions/api/transactions/payment \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "TERM001",
    "reference": "ORDER-123456",
    "method": "UPI",
    "amount": 10000,
    "currency": "INR",
    "return_url": "https://shop.example/return"
  }'

POST /api/transactions/payment

const res = await fetch('https://api.altitudepay.solutions/api/transactions/payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    terminal_id: 'TERM001',
    reference: 'ORDER-123456',
    method: 'UPI',
    amount: 10000, // minor units
    currency: 'INR',
    return_url: 'https://shop.example/return',
  }),
});

const { status, redirect } = await res.json();
// PENDING: send the customer to the provider via redirect

E-wallets

Overview Integrate

Digital wallet payments. Send one request to /api/transactions/payment with method set to WALLETS. Most methods redirect the customer to the provider, and the final status arrives by webhook.

method: WALLETS
Endpoint: POST /api/transactions/payment
Optional fields: description, customer, country, customer_ip, metadata, return_url, options, originator_url

Required fields

Field	Description
`terminal_id`	Must support payment transactions (`TRX_TYPE_PAYMENT`).
`reference`	Unique per terminal, max 80 characters. Idempotent: the same reference with the same amount and currency returns the existing transaction.
`method`	One of `OPEN_BANKING`, `UPI`, `WALLETS`, `BANK_TRANSFER` or `QR_CODE`.
`currency`	ISO 4217 currency code.
`amount`	Integer in minor units, e.g. `10000` = 100.00. Decimal values are rejected.

Payments reference Direct API Integration

cURLNode.js

POST /api/transactions/payment

curl -X POST https://api.altitudepay.solutions/api/transactions/payment \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "TERM001",
    "reference": "ORDER-123456",
    "method": "WALLETS",
    "amount": 10000,
    "currency": "EUR",
    "return_url": "https://shop.example/return"
  }'

POST /api/transactions/payment

const res = await fetch('https://api.altitudepay.solutions/api/transactions/payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    terminal_id: 'TERM001',
    reference: 'ORDER-123456',
    method: 'WALLETS',
    amount: 10000, // minor units
    currency: 'EUR',
    return_url: 'https://shop.example/return',
  }),
});

const { status, redirect } = await res.json();
// PENDING: send the customer to the provider via redirect

Bank Transfer

Overview Integrate

Direct bank transfer. Send one request to /api/transactions/payment with method set to BANK_TRANSFER. Most methods redirect the customer to the provider, and the final status arrives by webhook.

method: BANK_TRANSFER
Endpoint: POST /api/transactions/payment
Optional fields: description, customer, country, customer_ip, metadata, return_url, options, originator_url

Required fields

Field	Description
`terminal_id`	Must support payment transactions (`TRX_TYPE_PAYMENT`).
`reference`	Unique per terminal, max 80 characters. Idempotent: the same reference with the same amount and currency returns the existing transaction.
`method`	One of `OPEN_BANKING`, `UPI`, `WALLETS`, `BANK_TRANSFER` or `QR_CODE`.
`currency`	ISO 4217 currency code.
`amount`	Integer in minor units, e.g. `10000` = 100.00. Decimal values are rejected.

Payments reference Direct API Integration

cURLNode.js

POST /api/transactions/payment

curl -X POST https://api.altitudepay.solutions/api/transactions/payment \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "TERM001",
    "reference": "ORDER-123456",
    "method": "BANK_TRANSFER",
    "amount": 10000,
    "currency": "EUR",
    "return_url": "https://shop.example/return"
  }'

POST /api/transactions/payment

const res = await fetch('https://api.altitudepay.solutions/api/transactions/payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    terminal_id: 'TERM001',
    reference: 'ORDER-123456',
    method: 'BANK_TRANSFER',
    amount: 10000, // minor units
    currency: 'EUR',
    return_url: 'https://shop.example/return',
  }),
});

const { status, redirect } = await res.json();
// PENDING: send the customer to the provider via redirect

QR Code

Overview Integrate

QR code-based payment. Send one request to /api/transactions/payment with method set to QR_CODE. Most methods redirect the customer to the provider, and the final status arrives by webhook.

method: QR_CODE
Endpoint: POST /api/transactions/payment
Optional fields: description, customer, country, customer_ip, metadata, return_url, options, originator_url

Required fields

Field	Description
`terminal_id`	Must support payment transactions (`TRX_TYPE_PAYMENT`).
`reference`	Unique per terminal, max 80 characters. Idempotent: the same reference with the same amount and currency returns the existing transaction.
`method`	One of `OPEN_BANKING`, `UPI`, `WALLETS`, `BANK_TRANSFER` or `QR_CODE`.
`currency`	ISO 4217 currency code.
`amount`	Integer in minor units, e.g. `10000` = 100.00. Decimal values are rejected.

Payments reference Direct API Integration

cURLNode.js

POST /api/transactions/payment

curl -X POST https://api.altitudepay.solutions/api/transactions/payment \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "TERM001",
    "reference": "ORDER-123456",
    "method": "QR_CODE",
    "amount": 10000,
    "currency": "THB",
    "return_url": "https://shop.example/return"
  }'

POST /api/transactions/payment

const res = await fetch('https://api.altitudepay.solutions/api/transactions/payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    terminal_id: 'TERM001',
    reference: 'ORDER-123456',
    method: 'QR_CODE',
    amount: 10000, // minor units
    currency: 'THB',
    return_url: 'https://shop.example/return',
  }),
});

const { status, redirect } = await res.json();
// PENDING: send the customer to the provider via redirect

Payments (deposits)

Alternative payment methods go through /api/transactions/payment. Most methods redirect the customer to the provider, and the final status arrives by webhook.

Payments reference

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway
    participant Provider

    Customer->>Merchant: Select payment method
    Merchant->>Gateway: POST /api/transactions/payment
    Gateway->>Gateway: Validate request & terminal
    Gateway->>Gateway: Resolve payment provider
    Gateway->>Provider: Initiate payment

    alt Redirect Required
        Provider-->>Gateway: Redirect URL
        Gateway-->>Merchant: Response with redirect
        Merchant->>Customer: Redirect to provider
        Customer->>Provider: Complete payment (bank login, wallet, QR scan)
        Provider->>Gateway: Callback with result
    else Direct Response
        Provider-->>Gateway: Processing result
    end

    Gateway-->>Merchant: Transaction response
    Gateway->>Merchant: Webhook notification (APPROVED/DECLINED)

Jump to Cards Card Authorize Encryption example 3D Secure 3DS Authentication Simulator Network Token Network Token Authorize

Cards

Overview Integrate Test

Process card payments through /api/transactions/authorize. All sensitive card data must be encrypted with your merchant public key before it is sent to the API.

payment_method.type: card
Encrypted fields: Card number, CVV, expiration month, expiration year
3D Secure: Always initiated for card and saved_card. The authorize response returns an action (THREE_DS_2_FINGERPRINT, THREE_DS_2_CHALLENGE), a redirect or a form_submit.
Saved cards: Save with tokenization.save_card_for_future_payments, then pay with type saved_card.

Card payment data fields

Field	Description
`encrypted_card_number`	Card PAN (digits only, no spaces)
`encrypted_cvv`	Card security code (digits only)
`encrypted_expiration_month`	Expiration month (1–12, no leading zero)
`encrypted_expiration_year`	2-digit (`26`) or 4-digit (`2026`); must be current or future year

Overview Authorize Encryption example 3D Secure 3DS Authentication Simulator 3DS card payment recipe

Basic requestSaved card

POST /api/transactions/authorize

{
  "reference": "ORDER-123456",
  "terminal_id": "TERM001",
  "description": "Order payment",
  "currency": "EUR",
  "amount": 10000,
  "transaction_type": "PURCHASE",
  "payment_method": {
    "type": "card",
    "data": {
      "encrypted_card_number": "base64_encrypted_value",
      "encrypted_cvv": "base64_encrypted_value",
      "encrypted_expiration_month": "base64_encrypted_value",
      "encrypted_expiration_year": "base64_encrypted_value"
    }
  },
  "customer": { ... },
  "browser_info": { ... },
  "metadata": {},
  "return_url": "https://merchant.example.com/return"
}

POST /api/transactions/authorize

{
  "reference": "ORDER-789012",
  "terminal_id": "TERM001",
  "description": "Subscription renewal",
  "currency": "EUR",
  "amount": 5000,
  "transaction_type": "PURCHASE",
  "payment_method": {
    "type": "saved_card",
    "data": {
      "payment_method_id": "abc123def456ghi789",
      "encrypted_cvv": "base64_encrypted_value"
    }
  },
  "customer": { "id": "CUST123456", ... },
  "browser_info": { ... },
  "metadata": {},
  "return_url": "https://merchant.example.com/return"
}

3DS is always initiated for card payments. The /api/transactions/authorize response then guides you through up to two steps: device fingerprinting and challenge authentication.

How it works

THREE_DS_2_FINGERPRINTDecode action.token. If three_ds_method_url is present, submit threeDSMethodData to it in a hidden iframe and wait a fixed 5 seconds.
POST /api/transactions/three-ds/{id}/request-authenticationSend fingerprint_result (Base64 of Y if the fingerprint form was submitted, N if three_ds_method_url was absent) and pass through action.payment_data.
THREE_DS_2_CHALLENGEBuild a CReq from the decoded token and post it to acs_url. After the challenge, the gateway authorizes the transaction and redirects the customer back to your return_url.

Handling the response

Which field is populated determines your next step. The same logic applies after every call in the 3DS flow.

Response field	Meaning	Next step
`result`	Transaction finalized (approved or declined)	Done
`action` with type `THREE_DS_2_FINGERPRINT`	Device fingerprint required	Step 1 above
`action` with type `THREE_DS_2_CHALLENGE`	Challenge required	Step 3 above
`redirect`	Redirect the customer	Redirect the browser to `redirect.url`
`form_submit`	Auto-submit a form	Post a hidden form to `form_submit.url` with the fields in `form_submit.data`

Try it in the simulator 3DS card payment recipe

3DS overview 3DS full example

3D Secure flow overview

The /api/transactions/authorize response includes fields that guide you through up to two steps: device fingerprinting and challenge authentication.

3D Secure reference

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway as Payment Gateway
    participant ACS as Issuer ACS

    Merchant ->> Gateway: POST /api/transactions/authorize
    Gateway -->> Merchant: Response with action (THREE_DS_2_FINGERPRINT)

    Note over Merchant: Step 1 — Device Fingerprint
    Merchant ->> Merchant: Decode token from action response
    Merchant ->> ACS: POST threeDSMethodData (hidden iframe)
    ACS -->> Gateway: Notification (via three_ds_method_notification_url)

    Merchant ->> Gateway: POST /api/transactions/three-ds/{id}/request-authentication
    Gateway -->> Merchant: Response (approved, or challenge required)

    alt Frictionless Flow
        Note over Merchant: Transaction approved without customer interaction
    else Challenge Required
        Note over Merchant: Step 2 — Challenge
        Merchant ->> Merchant: Decode token, build CReq
        Merchant ->> ACS: POST creq (full-page redirect to ACS)
        Customer ->> ACS: Complete authentication (OTP, biometric, etc.)
        ACS -->> Gateway: Authentication result (CRes)
        Gateway ->> Gateway: Process authentication & authorize transaction
        Gateway -->> Customer: Redirect to merchant return_url
        Note over Merchant: Customer returned — verify status via API or webhook
    end

Complete 3DS integration example

A simplified example of the full 3DS flow for a card payment, with the frictionless, challenge and redirect outcomes.

3D Secure reference

sequenceDiagram
    participant Browser as Customer Browser
    participant Server as Merchant Server
    participant Gateway as Payment Gateway
    participant ACS as Issuer ACS

    Browser ->> Server: Checkout (card details + browser info)
    Server ->> Gateway: POST /api/transactions/authorize
    Gateway -->> Server: action (type: THREE_DS_2_FINGERPRINT, token, payment_data)
    Server -->> Browser: Decoded token + payment_data

    Note over Browser: Step 1 — Device Fingerprint
    Browser ->> Browser: Build threeDSMethodData from token
    Browser ->> ACS: POST threeDSMethodData (hidden iframe to threeDsMethodUrl)
    Note over Browser: Wait up to 5 seconds

    Browser ->> Server: Fingerprint complete
    Server ->> Gateway: POST /api/transactions/three-ds/{id}/request-authentication
    Gateway -->> Server: Frictionless approval or challenge action

    alt Approved (Frictionless)
        Server -->> Browser: Payment successful
    else Challenge Required (action)
        Server -->> Browser: Challenge token + payment_data
        Note over Browser: Step 2 — Challenge
        Browser ->> Browser: Build CReq from token
        Browser ->> ACS: POST creq (full-page redirect to acsUrl)
        Browser ->> ACS: Customer completes authentication
        ACS -->> Gateway: Authentication result (CRes)
        Gateway ->> Gateway: Process authentication & authorize transaction
        Gateway -->> Browser: Redirect to merchant return_url
        Note over Browser: Customer returned — verify status via API or webhook
    else Redirect Required
        Server -->> Browser: Redirect URL
        Browser ->> ACS: Browser redirect
        ACS -->> Gateway: Authentication result
        Gateway -->> Browser: Redirect to merchant return_url
        Note over Browser: Customer returned — verify status via API or webhook
    end

UAT The default and recommended way to test 3DS in UAT: send a test card number and the gateway resolves a deterministic outcome, with no metadata required.

Test cards

Scenario	Visa	Mastercard
Frictionless, approved	`4000000000000002`	`5200000000000007`
Redirect, interactive approve or decline	`4000000000000010`	`5200000000000015`
Form submit, authenticated	`4000000000000028`	`5200000000000023`
Form submit, authentication declined	`4000000000000036`	`5200000000000031`
Frictionless authenticated, then processing decline	`4000000000000044`	`5200000000000049`

Metadata-driven flows

To exercise the full EMVCo fingerprint and challenge sequence, set metadata.simulated_flow on the authorize request. metadata.response_code controls the final result: TRX_STATUS_APPROVED, TRX_STATUS_DECLINED or TRX_STATUS_FAILED.

Full flow: fingerprint + challenge (default)VERSIONING_FINGERPRINT_Y_CHALLENGE Frictionless approval, no customer interactionVERSIONING_FINGERPRINT_A_FRICTIONLESS Frictionless declineVERSIONING_FINGERPRINT_N_FRICTIONLESS Card not enrolled in 3DS, skips authenticationVERSIONING_NOT_ENROLLED Fingerprint times out, then challengeVERSIONING_FINGERPRINT_TIMEOUT_CHALLENGE Fingerprint times out, then frictionlessVERSIONING_FINGERPRINT_TIMEOUT_FRICTIONLESS

POST /api/transactions/authorize

{
  "metadata": {
    "simulated_flow": "VERSIONING_FINGERPRINT_Y_CHALLENGE",
    "response_code": "TRX_STATUS_APPROVED"
  }
}

POST /api/transactions/authorize

{
  "metadata": {
    "simulated_flow": "VERSIONING_FINGERPRINT_A_FRICTIONLESS",
    "response_code": "TRX_STATUS_APPROVED"
  }
}

POST /api/transactions/authorize

{
  "metadata": {
    "simulated_flow": "VERSIONING_FINGERPRINT_N_FRICTIONLESS",
    "response_code": "TRX_STATUS_APPROVED"
  }
}

POST /api/transactions/authorize

{
  "metadata": {
    "simulated_flow": "VERSIONING_NOT_ENROLLED",
    "response_code": "TRX_STATUS_APPROVED"
  }
}

POST /api/transactions/authorize

{
  "metadata": {
    "simulated_flow": "VERSIONING_FINGERPRINT_TIMEOUT_CHALLENGE",
    "response_code": "TRX_STATUS_APPROVED"
  }
}

POST /api/transactions/authorize

{
  "metadata": {
    "simulated_flow": "VERSIONING_FINGERPRINT_TIMEOUT_FRICTIONLESS",
    "response_code": "TRX_STATUS_APPROVED"
  }
}

3DS Authentication Simulator

The test card number decides the outcome. It arrives in the same result, action, redirect and form_submit fields as a real 3DS transaction, so only the card number changes between the simulator and production.

Simulator reference

sequenceDiagram
    participant Browser
    participant Server as Your Server
    participant Gateway as Payment Gateway

    Server ->> Gateway: POST /api/transactions/authorize (test card)
    Gateway ->> Gateway: Decrypt PAN → look up scenario

    alt Frictionless test card
        Gateway -->> Server: result (approved / declined)
    else Redirect test card
        Gateway -->> Server: redirect.url (gateway ACS page)
        Server -->> Browser: redirect browser to URL
        Browser ->> Gateway: Approve / Decline button
        Gateway -->> Browser: redirect to return_url
    else Form-submit test card
        Gateway -->> Server: form_submit (url + data)
        Server -->> Browser: auto-submit form
        Browser ->> Gateway: POST trans_status (Y / N)
        Gateway -->> Browser: redirect to return_url
    end

Network Token

Overview Integrate

For merchants who decrypt wallet tokens on their own infrastructure. Send the resulting DPAN, cryptogram and ECI from Apple Pay, Google Pay or a Token Service Provider through the gateway.

payment_method.type: network-token
Encrypted: Token number (DPAN), expiration month, expiration year, cryptogram
Plain text: eci, source
3D Secure: Skipped when a valid cryptogram and ECI are provided

Data fields

Field	Encrypted	Required	Description
`encrypted_token_number`	Yes	Yes	DPAN from the wallet/TSP
`encrypted_expiration_month`	Yes	Yes	Token expiration month (1–12)
`encrypted_expiration_year`	Yes	Yes	Token expiration year (4 digits, e.g. `2025`)
`encrypted_cryptogram`	Yes	No	Payment cryptogram (absent for PAN_ONLY)
`eci`	No	No	Electronic Commerce Indicator — required for CRYPTOGRAM_3DS, omitted for PAN_ONLY. Valid values: `00`, `01`, `02`, `05`, `06`, `07`
`source`	No	No	Token origin (`apple-pay`, `google-pay`, `network-token`). Defaults to `network-token`

Overview Authorize

Apple PayGoogle Pay · PAN_ONLY

POST /api/transactions/authorize

{
  "reference": "ORDER-NT-001",
  "terminal_id": "TERM001",
  "description": "Apple Pay payment",
  "currency": "EUR",
  "amount": 10000,
  "transaction_type": "PURCHASE",
  "payment_method": {
    "type": "network-token",
    "data": {
      "encrypted_token_number": "base64_encrypted_dpan",
      "encrypted_expiration_month": "base64_encrypted_value",
      "encrypted_expiration_year": "base64_encrypted_value",
      "encrypted_cryptogram": "base64_encrypted_cryptogram",
      "eci": "05",
      "source": "apple-pay"
    }
  },
  "customer": { ... },
  "browser_info": { ... },
  "metadata": {},
  "return_url": "https://merchant.example.com/return"
}

POST /api/transactions/authorize

{
  "reference": "ORDER-NT-002",
  "terminal_id": "TERM001",
  "description": "Google Pay payment",
  "currency": "EUR",
  "amount": 5000,
  "transaction_type": "PURCHASE",
  "payment_method": {
    "type": "network-token",
    "data": {
      "encrypted_token_number": "base64_encrypted_dpan",
      "encrypted_expiration_month": "base64_encrypted_value",
      "encrypted_expiration_year": "base64_encrypted_value",
      "source": "google-pay"
    }
  },
  "customer": { ... },
  "browser_info": { ... },
  "metadata": {},
  "return_url": "https://merchant.example.com/return"
}

Network token authorization

You decrypt the wallet token and send the DPAN, cryptogram and ECI. 3DS is skipped when a valid cryptogram and ECI are provided.

Network Token reference

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway as Payment Gateway
    participant Acquirer

    Customer->>Merchant: Initiates payment (Apple Pay / Google Pay)
    Merchant->>Merchant: Decrypts wallet token (DPAN, cryptogram, ECI)
    Merchant->>Merchant: Encrypts sensitive fields with merchant public key
    Merchant->>Gateway: POST /api/transactions/authorize<br/>payment_method.type = "network-token"
    Gateway->>Gateway: Decrypts & validates DPAN (Luhn, brand)
    Gateway->>Gateway: Builds 3DS authorization from cryptogram + ECI
    Gateway->>Acquirer: Processes transaction
    Acquirer-->>Gateway: Authorization result
    Gateway-->>Merchant: Transaction response
    Merchant-->>Customer: Payment confirmation

Jump to Google Pay Apple Pay Wallet Redirect

Google Pay

Overview Integrate

Customers pay with the cards stored in their Google Account. Once your account manager enables Google Pay on your terminal, it appears on the hosted payment form alongside the other payment methods. With API integration, you send the Google Pay token to the gateway.

payment_method.type: google-pay
Token: payment_method.data.google_pay_token, Base64-encoded
3D Secure: Initiated for PAN_ONLY tokens, skipped for CRYPTOGRAM_3DS tokens
Card networks: Visa, Mastercard

Integration methods

Method	Description	Additional development
Hosted Payment Page	Google Pay is displayed as a payment option on the hosted payment form	None required
API Integration	Merchant integrates directly with the Google Pay API and sends the payment token to the gateway	Yes — Google Pay API + gateway API

Overview Request example (PAN_ONLY) Wallet Redirect

API · google-payNetwork Token · PAN_ONLY

POST /api/transactions/authorize

{
  "reference": "ORDER-GP-001",
  "terminal_id": "TERM001",
  "description": "Google Pay payment",
  "currency": "EUR",
  "amount": 10000,
  "transaction_type": "PURCHASE",
  "payment_method": {
    "type": "google-pay",
    "data": {
      "google_pay_token": "<Base64-encoded Google Pay token>"
    }
  },
  "customer": { ... },
  "browser_info": { ... },
  "return_url": "https://merchant.example.com/return"
}

POST /api/transactions/authorize

{
  "reference": "ORDER-NT-002",
  "terminal_id": "TERM001",
  "description": "Google Pay payment",
  "currency": "EUR",
  "amount": 5000,
  "transaction_type": "PURCHASE",
  "payment_method": {
    "type": "network-token",
    "data": {
      "encrypted_token_number": "base64_encrypted_dpan",
      "encrypted_expiration_month": "base64_encrypted_value",
      "encrypted_expiration_year": "base64_encrypted_value",
      "source": "google-pay"
    }
  },
  "customer": { ... },
  "browser_info": { ... },
  "metadata": {},
  "return_url": "https://merchant.example.com/return"
}

Google Pay · HPP Google Pay · API

Google Pay on the Hosted Payment Page

Once your account manager enables Google Pay, it appears on the hosted payment form alongside the other payment methods.

Google Pay reference

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway as Payment Gateway
    participant Google as Google Pay
    Customer ->> Merchant: Initiates checkout
    Merchant ->> Gateway: Create HPP session
    Gateway -->> Merchant: Redirect URL
    Merchant ->> Customer: Redirect to HPP
    Customer ->> Gateway: Select Google Pay on HPP
    Gateway ->> Google: Initiate Google Pay
    Customer ->> Google: Authenticate & confirm payment
    Google -->> Gateway: Google Pay token
    Gateway ->> Gateway: Process payment
    Gateway -->> Merchant: Payment result (webhook/redirect)

Google Pay via API integration

Send the Base64-encoded Google Pay token as payment_method.data.google_pay_token. 3DS is initiated for PAN_ONLY tokens and skipped for CRYPTOGRAM_3DS tokens.

Google Pay reference

sequenceDiagram
    participant Customer
    participant Frontend as Merchant Frontend
    participant Backend as Merchant Backend
    participant Gateway as Payment Gateway
    participant Acquirer
    Customer ->> Frontend: Click Google Pay button
    Frontend ->> Customer: Google Pay dialog
    Customer ->> Frontend: Confirm payment
    Frontend ->> Frontend: Receive PaymentData from Google Pay
    Frontend ->> Backend: Send Google Pay token
    Backend ->> Backend: Base64-encode token
    Backend ->> Gateway: POST /api/transactions/authorize<br/>(payment_method.type = "google-pay")
    Gateway ->> Gateway: Decode & decrypt Google Pay token
    Gateway ->> Acquirer: Process transaction
    Acquirer -->> Gateway: Authorization result
    Gateway -->> Backend: Transaction response
    Backend -->> Frontend: Payment result
    Frontend -->> Customer: Payment confirmation

Apple Pay

Overview Integrate

Apple Pay lets customers pay with the cards stored in their Apple Wallet on iPhone, iPad, Apple Watch and Mac. Authentication happens on the customer's device through Face ID, Touch ID or a passcode, so no card details are typed into your checkout.

Card brands: Visa, Mastercard, Maestro, American Express, Discover and JCB, where enabled on your terminal and supported by your payment provider
3D Secure: Treated as CRYPTOGRAM_3DS. No additional 3DS challenge.
Activation: Request Apple Pay on your terminal from your account manager

Integration methods

Method	Who decrypts the Apple Pay token	Additional development
Wallet Redirect (`apple-pay-redirect`)	The PSP — the gateway never sees the token	None to minimal
Network Token (`network-token`)	You, on your own infrastructure	Yes — Apple Pay on the Web plus token decryption

Overview Request example (Apple Pay) Wallet Redirect Network Token

Network TokenWallet Redirect

POST /api/transactions/authorize

{
  "payment_method": {
    "type": "network-token",
    "data": {
      "encrypted_token_number": "<encrypted DPAN>",
      "encrypted_expiration_month": "<encrypted MM>",
      "encrypted_expiration_year": "<encrypted YYYY>",
      "encrypted_cryptogram": "<encrypted cryptogram>",
      "eci": "05",
      "source": "apple-pay"
    }
  }
}

POST /api/transactions/authorize

{
  "payment_method": {
    "type": "apple-pay-redirect",
    "data": {}
  }
}

Wallet Redirect

Overview Integrate

Accept Google Pay and Apple Pay without integrating the wallet SDKs on your own site. The gateway returns a redirect URL to a PSP that renders the wallet button and authorizes the payment end to end, so the gateway never sees card data, the wallet token or the decrypted PAN.

payment_method.type: google-pay-redirect or apple-pay-redirect
payment_method.data: Empty object, {}
Transaction types: PURCHASE only

Integration methods

Method	Effort	Notes
Hosted Payment Page	None	Google Pay / Apple Pay appear automatically on the HPP once enabled on your terminal
Embedded Fields	Minimal	A stub script (`google-pay-redirect` / `apple-pay-redirect`) registers a factory; your page renders its own "Pay" button
API Integration	Low	Send a single `authorize` request with `payment_method.type` set to `google-pay-redirect` or `apple-pay-redirect` and follow the returned redirect

Overview

Google PayApple Pay

POST /api/transactions/authorize

{
  "payment_method": {
    "type": "google-pay-redirect",
    "data": {}
  }
}

POST /api/transactions/authorize

{
  "payment_method": {
    "type": "apple-pay-redirect",
    "data": {}
  }
}

Jump to Bank Redirect Paysafe Redirect Paysafe Direct API Integration Paysafe Customization Options Neogated (BLIK) Neogated Direct API Integration

Bank Redirect

Bank Redirect lets you accept payments made directly from a customer's bank account. You select the payment method on your platform and the gateway returns a redirect URL to a PSP-hosted page where the customer signs in to their bank and approves the payment.

payment_method.type: interac-redirect or openbanking-redirect
3D Secure: None. The customer's bank performs its own strong customer authentication.
Transaction types: PAYMENT only
Availability: Interac for customers banking in Canada; Open Banking coverage depends on your PSP and the customer's country

Overview

Paysafe Redirect

Paysafe Redirect gives access to a wide range of alternative payment methods through a single integration. Customers are redirected to a secure environment to complete their payment with the method they selected.

payment_method.type: paysafe-redirect-{code}, all lowercase, for example paysafe-redirect-psc for PaySafeCard
Required data: email, first_name, last_name
Integration: Hosted Payment Page or Direct API

Overview Direct API Integration Customization Options

Neogated (BLIK)

BLIK is a Polish instant payment system that enables customers to make payments using their mobile banking app. Through Neogated integration, merchants can offer BLIK as a payment option to Polish customers.

payment_method.type: neogated-blik
Currency: PLN only
Transaction types: PURCHASE only
Required data: email, first_name, last_name

Overview Direct API Integration

Processing flows

How requests move between your systems, Altitude Pay and third parties for each payment type.

Payments OCT

Payments (deposits)

Alternative payment methods go through /api/transactions/payment. Most methods redirect the customer to the provider, and the final status arrives by webhook.

Payments reference

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway
    participant Provider

    Customer->>Merchant: Select payment method
    Merchant->>Gateway: POST /api/transactions/payment
    Gateway->>Gateway: Validate request & terminal
    Gateway->>Gateway: Resolve payment provider
    Gateway->>Provider: Initiate payment

    alt Redirect Required
        Provider-->>Gateway: Redirect URL
        Gateway-->>Merchant: Response with redirect
        Merchant->>Customer: Redirect to provider
        Customer->>Provider: Complete payment (bank login, wallet, QR scan)
        Provider->>Gateway: Callback with result
    else Direct Response
        Provider-->>Gateway: Processing result
    end

    Gateway-->>Merchant: Transaction response
    Gateway->>Merchant: Webhook notification (APPROVED/DECLINED)

OCT (Original Credit Transaction)

A card payout pushes funds to a cardholder's card instead of pulling them. It is authorized with transaction_type OCT and needs no 3DS.

OCT reference

sequenceDiagram
    participant Merchant
    participant Gateway
    participant PSP

    Merchant->>Gateway: POST /api/transactions/authorize<br/>(transaction_type: OCT)
    Gateway->>Gateway: Decrypt & validate card number
    Gateway->>Gateway: Extract BIN, determine card brand
    Gateway->>Gateway: Route to payment provider
    Gateway->>PSP: Process OCT
    PSP-->>Gateway: Processing result
    Gateway-->>Merchant: Transaction response

Transaction statuses

Payments are asynchronous. Wait for the webhook, then confirm the final status with the Transaction Status API.

Status	Description	Final State
`CREATED`	Transaction created but not yet processed	No
`PENDING`	Payment submitted and awaiting customer action or provider confirmation	No
`APPROVED`	Payment successfully completed	Yes
`DECLINED`	Payment rejected by the provider or bank	Yes
`CANCELED`	Payment canceled by the customer or system	Yes
`INVALID`	Transaction marked as invalid due to validation errors	Yes
`SESSION_EXPIRED`	Payment session expired before completion	Yes

Refunds depend on the payment provider and method. Capture and void do not apply to payments. For the full transaction lifecycle, see Supported Transaction Statuses.

Payment Method

A Payment transaction allows merchants to collect funds from a customer using alternative payment methods such as Open Banking, UPI, wallets, bank transfers, or QR codes. Unlike card-based transactions that use the /api/transactions/authorize endpoint, payments are initiated via a dedicated /api/transactions/payment endpoint with a simplified request structure.

Payments are processed asynchronously — the transaction may initially return a PENDING status or a redirect URL, with the final result delivered via webhook.

Key Characteristics

Alternative Payment Methods
- Payments support non-card payment methods: Open Banking, UPI, Wallets, Bank Transfer, and QR Code.
- The payment method is specified as a simple string in the method field — no structured payment data object is required.
Fixed Transaction Type
- The transaction type is always PAYMENT. Unlike the authorize endpoint, there is no transaction_type field to set.
No Card Data or Encryption
- Payment requests do not include card data. No encryption is required.
- The browser_info field is not required.
Redirect-Based Flow
- Most payment methods involve a redirect to a third-party provider (bank, wallet app, QR page) where the customer completes the payment.
- The API response will typically include a redirect object with the URL to redirect the customer.
Terminal ID Specification
- The terminal_id must be specified in the request. The terminal must be configured to support payment transactions (feature: TRX_TYPE_PAYMENT).
Asynchronous Processing
- Payments are typically processed asynchronously. The initial API response may return a PENDING status or a redirect.
- The final transaction status is delivered via a Transaction Processed Webhook.
- Always verify the final status using the Transaction Status API.

Request Requirements

Field	Required	Notes
`terminal_id`	Yes	Must support payment transactions (`TRX_TYPE_PAYMENT`)
`reference`	Yes	Unique payment reference per terminal (max 80 chars). Idempotent — duplicate references with the same amount/currency will return the existing transaction.
`method`	Yes	Payment method type: `OPEN_BANKING`, `UPI`, `WALLETS`, `BANK_TRANSFER`, or `QR_CODE`
`currency`	Yes	ISO 4217 currency code (e.g., `EUR`, `USD`, `THB`)
`amount`	Yes	Amount in minor units, as an integer (e.g., `10000` = 100.00 EUR). Decimal or fractional values such as `100.00` or `"100.00"` are rejected at request validation.
`description`	No	Human-readable payment description (max 100 chars)
`customer`	No	Customer details (name, email, address, etc.)
`country`	No	ISO 3166-1 alpha-2 country code (e.g., `TH`, `ID`, `IN`)
`customer_ip`	No	Customer IP address (defaults to request IP)
`metadata`	No	Arbitrary key-value metadata
`return_url`	No	URL to redirect after payment completes (approved, declined, canceled, or error)
`options`	No	Provider-specific or payment-type-specific options
`originator_url`	No	URL of the website on which the customer started the purchase (defaults to the terminal website). Kept on retries and forwarded to providers that require it

Processing Flow

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway
    participant Provider

    Customer->>Merchant: Select payment method
    Merchant->>Gateway: POST /api/transactions/payment
    Gateway->>Gateway: Validate request & terminal
    Gateway->>Gateway: Resolve payment provider
    Gateway->>Provider: Initiate payment

    alt Redirect Required
        Provider-->>Gateway: Redirect URL
        Gateway-->>Merchant: Response with redirect
        Merchant->>Customer: Redirect to provider
        Customer->>Provider: Complete payment (bank login, wallet, QR scan)
        Provider->>Gateway: Callback with result
    else Direct Response
        Provider-->>Gateway: Processing result
    end

    Gateway-->>Merchant: Transaction response
    Gateway->>Merchant: Webhook notification (APPROVED/DECLINED)

Supported Transactions

Transaction Type	Supported	Description
PAYMENT	Yes	Collect funds via alternative payment method
REFUND	Depends	Depends on payment provider and method
CAPTURE	No	Not applicable (single-step flow)
VOID	No	Not applicable

Redirect Handling

After the customer completes (or abandons) the payment on the provider's page, they are redirected back to the merchant:

Transaction Status	Redirect Destination
APPROVED	Merchant's `return_url`
DECLINED / CANCELED	Merchant's `return_url`
PENDING	Awaits callback resolution

Always verify the final transaction status via the Transaction Status API regardless of the redirect outcome.

Important Notes

The reference field is idempotent per terminal. Sending the same reference with the same amount and currency returns the existing transaction. Different amount/currency values will result in a validation error.
No card data or encryption is required — the method field specifies the payment type as a simple string.
The browser_info field is not required for payment transactions.
Always subscribe to webhooks to receive the final payment status, as payments are typically processed asynchronously.
The country field may be required by certain providers to determine the correct payment flow or bank selection.
Provider-specific configuration can be passed via the options field.

Payments API reference