Overview

Visa Click to Pay Direct API integrations allow merchants to process Click to Pay transactions using backend-driven payment flows and tokenized wallet data.

This integration model provides:

• greater frontend flexibility,
• advanced payment orchestration,
• direct wallet processing,
• backend-controlled authorization flows,
• custom checkout experiences.

Direct API integrations are intended for merchants requiring deeper control over payment processing and authentication handling.

Supported Flow

The Direct API integration supports:

• tokenized wallet payments,
• backend payment authorization,
• decrypted payload processing,
• custom frontend experiences,
• advanced 3DS handling,
• wallet transaction processing.

High-Level Flow

The Direct API flow typically follows these steps:

1. Merchant creates an order
2. Frontend initializes Click to Pay SDK
3. Customer completes Click to Pay checkout
4. SDK returns signed checkout response
5. Backend validates JWS signature
6. Backend decrypts the payload
7. Wallet token data is extracted
8. Backend submits payment authorization
9. 3DS handling occurs if required
10. Payment result is returned

flowchart LR

%% --- Frontend ---
subgraph FE["Frontend (Checkout Experience)"]
    A[Create Order]
    B[Initialise SDK]
    C[Complete Click to Pay Checkout]
    D[Return Signed Checkout Response]
end

%% --- Backend ---
subgraph BE[Backend Processing]
    E[Validate JWS Signature]
    F[Decrypt Payload]
    G[Extract Token Data]
    H[Submit Authorisation]
end

%% --- Decision ---
I{3DS Required?}
J[Handle 3DS Authentication]
K[Return Payment Result]
A --> B --> C --> D --> E --> F --> G --> H --> I

I -->|Yes| J --> K
I -->|No| K

%% --- Styling ---
classDef frontend fill:#E8F0FE,stroke:#1A73E8,stroke-width:1.5px;
classDef backend fill:#E6F4EA,stroke:#188038,stroke-width:1.5px;
classDef decision fill:#FFF4E5,stroke:#F9AB00,stroke-width:1.5px;

class A,B,C,D frontend;
class E,F,G,H backend;
class I decision;

Architecture Overview

The Direct API integration consists of:

• frontend SDK interaction,
• backend payload validation,
• backend payload decryption,
• tokenized wallet processing,
• payment authorization orchestration.

The frontend is responsible for customer interaction and SDK operations, while the backend controls secure payment execution.

Direct Wallet Processing

Direct API integrations process wallet token data obtained from the decrypted Click to Pay payload.

The decrypted payload may contain:

• payment token values,
• cryptograms,
• ECI values,
• transaction identifiers,
• 3DS verification data.

These values are used during backend payment authorization.

Checkout Response Handling

After a successful frontend checkout() operation, the SDK returns a signed checkout response.

The response should:

• be forwarded to the backend without modification,
• undergo JWS signature validation,
• be decrypted using backend private keys.

Important

Signature validation must occur before payload decryption.

Direct Payment Processing Endpoint

Endpoint

POST /transactions/outlets/{outletId}/orders/{orderRef}/payments/{paymentRef}/click-to-pay/direct

Base URL:

https://api-gateway.sandbox.ngenius-payments.com

Purpose

This endpoint:

• processes Direct Wallet Click to Pay transactions,
• accepts tokenized payment data,
• supports backend wallet authorization flows,
• handles advanced payment processing scenarios.

Path Parameters

Query Parameters

Authentication

Bearer Token required.

Required permission:

CREATE_AUTHORIZATION

Direct Wallet Payload Fields

The Direct Wallet flow may require values extracted from the decrypted payload.

These may include:

• pan
• expiry
• transactionId
• eci
• cryptogram
• dsTransId
• dsTransStatus
• verificationMethod

These values are derived from the Click to Pay checkout response and associated payload structures.

ECI and 3DS Handling

Direct API integrations may require additional 3DS handling depending on the ECI value returned during checkout.

Example Behavior

The backend may need to:

• return await_3ds,
• pause authorization,
• continue processing after customer authentication.

Cryptogram Handling

The cryptogram value is extracted from the decrypted payload and used during authorization processing.

Supported cryptogram formats may include:

• CARD_APPLICATION_CRYPTOGRAM_LONG_FORM
• CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM

Payload Decryption

The encrypted checkout payload is decrypted using Network International private keys.

The decrypted payload may contain:

• tokenized PAN data,
• masked card values,
• payment credentials,
• transaction metadata.

Private keys must never be exposed outside secure backend environments.

Security Responsibilities

Direct API integrations place greater security responsibility on backend systems.

Backend systems are responsible for:

• secure payload validation,
• decryption handling,
• authorization processing,
• credential protection,
• 3DS orchestration,
• secure storage practices.

Frontend Responsibilities

The frontend is responsible for:

• SDK initialization,
• customer interaction,
• invoking checkout(),
• forwarding responses securely to backend systems.

Sensitive authorization logic should not occur on the frontend.

Error Handling

Direct API integrations should gracefully handle:

• invalid signatures,
• decryption failures,
• authorization failures,
• invalid token data,
• expired wallet credentials,
• 3DS authentication failures,
• unsupported ECI values.

Sensitive payment data should never be logged or exposed in client-side error responses.

Direct Wallet Enablement

Direct API integrations require:

• Visa Click to Pay payment method enablement,
• Direct Wallet proposition service enablement,
• platform-level configuration,
• tenant-level configuration.

Related Documentation

• Overview
• Payment Flow
• API Endpoints
• Security & Encryption
• Hosted Session Integration
• Mobile SDK Integration

Additional Notes

The Direct API integration flow is based on:

• Visa Click to Pay wallet processing flows,
• backend token authorization architecture,
• decrypted payload handling,
• 3DS orchestration requirements,
• Direct Wallet payment processing.

Additional payload examples, authorization schemas, and implementation samples may be added in future revisions as integration artifacts become available.