Merchant Onboarding APIs

These onboarding services help ensure that merchant configuration data, payment method enablement, and onboarding status information remain synchronised across supported payment experiences.

Overview

The onboarding flow is responsible for:

Merchant onboarding and registration
Merchant configuration management
Payment method enablement
Merchant configuration updates
Onboarding status tracking
Synchronisation of merchant onboarding data

Depending on the onboarding state, merchants may be newly onboarded or updated within the Visa Click to Pay onboarding flow.

High-Level Onboarding Flow

flowchart LR

%% --- Lifecycle Stages ---
A[Configuration Updated] --> B[Onboarding Triggered]

B --> C[Request Processing]

C --> D[Validation]

D -->|Valid| E[Merchant Onboarded / Updated]
D -->|Invalid| X[Validation Failed]

E --> F[Status Stored]

F --> G[Configuration Synced]

%% --- Styling ---
classDef start fill:#E8F0FE,stroke:#1A73E8,stroke-width:1.5px;
classDef process fill:#F1F3F4,stroke:#5F6368,stroke-width:1px;
classDef success fill:#E6F4EA,stroke:#188038,stroke-width:1.5px;
classDef error fill:#FCE8E6,stroke:#D93025,stroke-width:1.5px;

class A,B start;
class C,D,F process;
class E,G success;
class X error;

Merchant Onboarding Requirements

Merchant onboarding may require:

Business identification information
Legal business details
Trade name information
Merchant address information
Domain or website configuration
Payment method enablement

The onboarding document notes that business identification fields and merchant configuration details may be required during onboarding and update flows.

Merchant Configuration Updates

Updates to merchant configuration data may trigger additional onboarding update flows.

This can include changes to:

Business identification information
Domain or website details
Legal business name
Trade name
Full business address

The source document specifically references these fields as onboarding update triggers.

Onboarding Status Management

During onboarding and update operations, onboarding statuses may be recorded and made available within the merchant or organisational management experience.

This helps:

Track onboarding progress
Review onboarding results
Identify onboarding failures
Review onboarding exceptions
Confirm successful enablement

The source document notes that onboarding and amendment results should be visible within the organisational hierarchy experience.

Merchant Configuration Retrieval

Merchant onboarding configuration data may be retrieved using the merchant configuration endpoint.

Base URL

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

Example Endpoint

GET /config/merchants/{merchantRef}/configs/vctp

Path Parameters

Parameter	Description
merchantRef	Merchant identifier associated with the Visa Click to Pay configuration

This endpoint may be used to:

Retrieve merchant onboarding configuration
Obtain onboarding-related values
Retrieve Click to Pay configuration information
Access merchant-level onboarding details

The onboarding configuration endpoint is documented within the Visa Click to Pay API definitions.

Onboarding Behaviour

Depending on the onboarding state:

New merchants may be onboarded directly into Visa Click to Pay
Existing merchants may trigger onboarding update flows
Configuration updates may trigger synchronization requests
Merchant onboarding data may be updated automatically

The source document notes that onboarding and merchant updates may be triggered automatically when merchant configuration changes occur.

Error Handling

If onboarding or update operations fail:

Onboarding exceptions may be recorded
Validation failures may be surfaced to users
Retry behaviour may depend on onboarding configuration state
Additional onboarding updates may be required

The onboarding design notes mention onboarding exception handling and update retry behaviour.

Integration Considerations

When implementing onboarding integrations, developers should consider:

Merchant configuration dependencies
Payment method enablement
Merchant update synchronisation
Onboarding status handling
Validation and retry behaviour
Tenant and platform-level configuration