Merchant Configuration

The CloudLink API provides functionality to request and retrieve merchant configuration information from payment devices. This allows you to discover multiple merchants configured on a single device, each with their own settings, currencies, and configurations.

Overview

Merchant configuration functionality enables multi-tenant POS setups where multiple businesses can share a single physical device. For example:

4 dentists sharing one device with different merchant IDs and currencies
Multiple retail locations using the same terminal with different configurations
Multi-currency businesses with separate merchant setups for each currency
Franchise operations where each franchisee has their own merchant configuration

Each merchant configuration includes: - Unique merchant ID for transaction identification - Currency code (EUR, USD, GBP, etc.) - Merchant name for display purposes - Terminal ID for device identification

Merchant configuration functionality is available through both webhook and polling mechanisms, providing flexibility for different integration patterns.

Endpoints

Webhook-based Merchant Configuration

Request Merchant Configuration

POST /requestMerchantConfig

Request Body:

{
  "deviceToken": "b16526c3447ba6cea4818d",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "callbackUrl": "http://example.com/webhook-endpoint",
  "timeToLive": 300
}

Response: - 202 Accepted - Request accepted and sent to terminal - 400 Bad Request - Invalid request parameters - 401 Unauthorized - Invalid API key - 500 Internal Server Error - Server error

Receive Merchant Configuration Webhook

POST /callback/configCallback

Webhook Payload:

{
  "eventType": "MERCHANT_CONFIG",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "merchantConfig": [
    {
      "currencyCode": "EUR",
      "merchantId": "12345678",
      "merchantName": "Sample Store",
      "terminalId": "TERM001"
    },
    {
      "currencyCode": "USD",
      "merchantId": "87654321",
      "merchantName": "Sample Store USD",
      "terminalId": "TERM001"
    }
  ]
}

Polling-based Merchant Configuration

Request Merchant Configuration

POST /poll/requestMerchantConfig

Request Body:

{
  "deviceToken": "b16526c3447ba6cea4818d",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "pollId": "550e8400-e29b-41d4-a716-446655440000",
  "timeToLive": 300
}

Response: - 202 Accepted - Request accepted and sent to terminal - 400 Bad Request - Invalid request parameters - 401 Unauthorized - Invalid API key - 500 Internal Server Error - Server error

Poll for Merchant Configuration Response

GET /poll/terminalConfigResponse/{pollId}

Response: - 200 OK - Merchant configuration available - 404 Not Found - Response not yet available - 408 Request Timeout - Response has timed out - 429 Too Many Requests - Rate limit exceeded - 500 Internal Server Error - Server error

Success Response Body:

{
  "eventType": "MERCHANT_CONFIG",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "merchantConfig": [
    {
      "currencyCode": "EUR",
      "merchantId": "12345678",
      "merchantName": "Sample Store",
      "terminalId": "TERM001"
    }
  ]
}

Enhanced Sale Requests

The CloudLink API now supports enhanced sale requests with additional features including tip amounts, voucher codes, whitelist filtering, and multi-tenant merchant selection. These enhanced features work in conjunction with the merchant configuration to provide a more flexible and powerful payment processing experience.

Enhanced Sale Request Features

Multi-Tenant Merchant Selection

merchantIdentifier - Select which merchant profile to use for the transaction
Use after requestMerchantConfig to discover available merchants
Required for multi-tenant devices to ensure proper transaction attribution
Example: "merchantIdentifier": "12345678" for Dr. Smith's EUR transactions

Tip Amount Support

tipAmount - Allows customers to add tips to transactions
Amount is represented in minor units (e.g., 500 = 5.00 EUR)
Supported by terminals with tip functionality enabled

Voucher Code Support

voucherCode - Mastercard voucher codes for promotions and discounts
Unique alphanumeric codes for specific value or discount redemption
Requires terminal support for voucher processing

Whitelist Filtering

whitelistAids - Specify allowed Application Identifiers (AIDs)
whitelistBins - Specify allowed Bank Identification Numbers (BINs)
Terminal must have predefined lists configured to use these features

Integration with Merchant Configuration

Enhanced sale requests work seamlessly with merchant configuration in multi-tenant setups:

Use requestMerchantConfig to discover all available merchants and their capabilities
Select appropriate merchant based on business logic (dentist, currency, feature support)
Include merchantIdentifier in the sale request to specify which merchant profile to use
Send enhanced sale request with supported features enabled for the selected merchant
Receive comprehensive response with detailed transaction information under the correct merchant profile

Example: Multi-Tenant Sale Request

{
  "deviceToken": "b16526c3447ba6cea4818d",
  "amount": "100",
  "merchantIdentifier": "12345678",
  "tipAmount": "500",
  "language": "en_GB",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "callbackUrl": "http://example.com/webhook-endpoint",
  "referenceId": "dr-smith-patient-abc123",
  "voucherCode": "200001",
  "whitelistAids": ["AIDNAME1", "AIDNAME2"],
  "whitelistBins": ["BIN1", "BIN2"]
}

In this example: - merchantIdentifier: "12345678" selects Dr. Smith's EUR merchant profile - tipAmount: "500"** adds a 5.00 EUR tip - **voucherCode: "200001" applies a Mastercard voucher - Transaction is processed under Dr. Smith's merchant account

Comprehensive Terminal Response Object

When processing enhanced sale requests, the terminal returns a comprehensive CloudLinkResponse object containing detailed transaction information. This object includes all the enhanced features and provides complete visibility into the transaction process.

Key Response Fields for Enhanced Features

tipAmount - Confirmed tip amount processed
voucherBalance - Remaining voucher balance after transaction
voucherExpirationDate - When the voucher expires
dccTransaction - Dynamic Currency Conversion details
walletProvider - Digital wallet information if applicable
approved - Whether the enhanced transaction was approved

For complete details on all available response fields, see the Terminal Response Documentation.

Flow Diagrams

Webhook Flow

Merchant Configuration Webhook Flow

Polling Flow

Merchant Configuration Polling Flow

Rate Limiting

The polling endpoints are rate-limited to one call per second per pollId to prevent abuse and ensure optimal performance.

Timeout Handling

Poll Response Timeout: Default timeout for polling responses
Terminal Response TTL: Time-to-live for stored terminal responses
Request Timeout: Timeout for callback HTTP requests

Error Handling

Common Error Scenarios

Terminal Not Available: Terminal is offline or busy
Invalid Device Token: Device token is invalid or expired
Request Timeout: Terminal response timeout
Rate Limit Exceeded: Too many polling requests
Invalid Configuration: Missing or invalid request parameters

Error Response Codes

400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid API key
404 Not Found - Resource not found
408 Request Timeout - Request timed out
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error
504 Gateway Timeout - Callback request timeout

Best Practices

Correlation IDs: Always use unique correlation IDs for tracking requests
Error Handling: Implement proper error handling for all response codes
Rate Limiting: Respect rate limits and implement exponential backoff
Timeout Management: Set appropriate timeouts based on your business requirements
Logging: Log all requests and responses for debugging and monitoring
Retry Logic: Implement retry logic for transient failures
Webhook Security: Validate webhook signatures and use HTTPS endpoints

Multi-Tenant Device Setup

How It Works

A single payment device can be configured with multiple merchant profiles, each representing a different business or business unit. This is particularly useful for:

Shared office spaces where multiple professionals share equipment
Multi-location businesses with different merchant IDs per location
Multi-currency operations requiring separate merchant setups
Franchise systems with independent merchant configurations

Example: Dental Practice Setup

Consider a dental office where 4 dentists share one payment device:

Device: Payment Device (Terminal ID: TERM001)

Merchant Configurations:
├── Dr. Smith (Merchant ID: 12345678, Currency: EUR)
├── Dr. Johnson (Merchant ID: 87654321, Currency: USD) 
├── Dr. Williams (Merchant ID: 11223344, Currency: GBP)
└── Dr. Brown (Merchant ID: 44332211, Currency: EUR)

Workflow

Discover Available Merchants
Call requestMerchantConfig to get all merchant configurations
Terminal returns list of all configured merchants
Select Appropriate Merchant
Choose merchant based on business logic (dentist, currency, etc.)
Use the selected merchantId in subsequent transactions
Process Transactions
Include merchantIdentifier in sale requests
Terminal processes transaction under the selected merchant profile
All transaction records are properly attributed to the selected merchant

Benefits

Cost Efficiency - Multiple businesses share one device
Flexibility - Each merchant maintains independent configuration
Multi-Currency Support - Handle different currencies seamlessly
Simplified Management - Single device, multiple business profiles

Practical Use Cases

1. Shared Office Spaces

Scenario: Multiple professionals share office space and equipment - Dental practices - 4 dentists, 1 device, different merchant IDs - Medical clinics - Multiple doctors with separate billing - Law firms - Different attorneys with independent merchant accounts - Consulting offices - Multiple consultants sharing POS equipment

Benefits: - Reduced hardware costs - Simplified equipment management - Independent transaction tracking - Professional billing separation

2. Multi-Location Businesses

Scenario: Business with multiple locations using shared terminals - Retail chains - Different stores with unique merchant IDs - Restaurant franchises - Each location maintains separate accounts - Service businesses - Multiple branches with independent billing - Healthcare networks - Different facilities with separate merchant setups

Benefits: - Centralized device management - Location-specific transaction tracking - Independent financial reporting - Flexible deployment options

3. Multi-Currency Operations

Scenario: Businesses operating in multiple currencies - International retailers - EUR, USD, GBP transactions - Tourist businesses - Multiple currency support - E-commerce fulfillment - Different currency merchant accounts - Cross-border services - Multi-currency payment processing

Benefits: - Seamless currency handling - Local payment processing - Reduced conversion fees - Better customer experience

4. Franchise Systems

Scenario: Franchise operations with independent merchant accounts - Fast food chains - Each franchisee has unique merchant ID - Retail franchises - Independent financial tracking - Service franchises - Separate billing and reporting - Healthcare franchises - Independent practice management

Benefits: - Franchisee independence - Centralized oversight - Independent financial reporting - Simplified compliance