Onboarding Guide
How to onboard a sponsor bank (tenant) and a partner (entity) in the CardPay multi-tenant platform
Multi-Tenant Architecture
CardPay uses a multi-tenant architecture where each sponsor bank is provisioned as a separate tenant with its own isolated data. Partners of a sponsor bank are configured as entities within that tenant.
How Tenancy Works
- Request Header: Every API request carries a
TENANTheader identifying the sponsor bank. - Tenant Isolation: The platform isolates each tenant's data, ensuring complete separation between sponsor banks.
- Dynamic Routing: Requests are automatically routed to the correct tenant context based on the header.
- Entity Identification: Within a tenant, a partner/entity is identified by the
entityorfromEntityIdfield in the API request.
Onboarding a Sponsor Bank (Tenant)
Provision the Tenant
M2P provisions a new isolated tenant environment for the sponsor bank, including data storage, configuration, and network connectivity.
Configure Network Credentials
The following credentials are configured for the tenant:
- API credentials — Visa Direct API username and password
- Mutual TLS certificates — Keystore with client certificate for secure communication
- Message Level Encryption (MLE) — Public certificate and private key for JWE encryption (V2 APIs)
- V2 API credentials — Separate credentials for Visa V2 endpoints (if enabled)
MasterCard Send uses per-partner configuration rather than tenant-level credentials. See the Partner Onboarding section below for details.
Register the Tenant
The tenant is registered in the platform's tenant registry, enabling routing of API requests based on the TENANT header.
Onboarding a New Partner (Entity)
VISA Direct Configuration
Each Visa Direct partner requires the following configuration to be set up by the M2P team:
| Parameter | Description | Example |
|---|---|---|
| Business Application ID | Use case identifier (AA, PP, FD, CP, etc.) | PP (Person-to-Person) |
| Acquiring BIN | Visa-assigned BIN for the acquirer/sponsor bank | Assigned by Visa |
| Acquirer Country Code | ISO numeric country code of the acquirer | 356 (India) |
| Merchant Category Code | MCC identifying the business type | 6012 |
| Source of Funds Code | Indicates the origin of funds | 03 (Credit) |
| Card Acceptor Details | Partner identification in the Visa ecosystem | ID, name, terminal, location |
| MLE Enabled | Whether Message Level Encryption is active | true for V2 APIs |
| POS Condition Code | Transaction origination context | 59 (Electronic Commerce) |
Multiple use cases per partner
A partner can be configured for multiple Business Application IDs (e.g., PP, FD, CP) — each with its own set of default parameters. The platform automatically selects the correct configuration based on the businessApplicationId in the API request.
MasterCard Send Configuration
MasterCard Send partners require per-partner configuration for API authentication and encryption:
| Parameter | Description |
|---|---|
| OAuth Consumer Key | OAuth 1.0a consumer key for Mastercard API authentication |
| Signing Certificate | PKCS12 file for OAuth signature generation |
| ICA | Interbank Card Association number — identifies the acquiring institution |
| Processor ID | Mastercard-assigned processor identifier |
| Partner ID | Mastercard-assigned partner ID |
| Payment Type | Type of payment (BDB, P2P, etc.) |
| Funding Source | How the transaction is funded (CREDIT, DEBIT, PREPAID) |
| Encryption Key | Public key for JWE encryption of request payloads |
API version
All MasterCard Send integrations use the Send 2.0 protocol. The platform validates this during request processing.
Per-Entity Settings
The following settings can be configured per partner entity:
| Setting | Default | Description |
|---|---|---|
| Network status polling | Enabled | Automatically poll the network for final status of pending transactions |
| Max polling retries | 5 | Maximum number of status check attempts |
| Auto-failure timeout | 6 hours | Time after which pending transactions are automatically declined |
| Webhooks | Configurable | Enable real-time event notifications to partner webhook URL |
Transaction Identifiers
Every transaction is assigned unique identifiers by the platform:
| Identifier | Description |
|---|---|
| RRN (Retrieval Reference Number) | 12-character unique reference for network reconciliation |
| STAN (Systems Trace Audit Number) | 6-digit trace number for transaction tracking |
| Transaction ID | Platform-generated unique identifier |