Using dynamic merchant descriptor

Overview

When processing card payments, ecommpay follows the rules of card networks and shares the merchant details with other parties involved in payment processing. These details contain the name and the country code of the organisation as well as the information about the headquarters location or other attributes, such as the phone number or the web service address, with regard to the card networks recommendations and the merchant's preferences. As a result, the parties in payment processing can use these details in their work. In particular, issuers can specify them in notifications and bank statements—this allows customers to identify merchants and payments more clearly thus helping merchants to improve customer experience and reduce chargebacks from customers.

When processing card payments, ecommpay follows the rules of card networks and provides other parties involved in payment processing with the following merchant details: the name and the country code of the organisation as well as the information about the headquarters location or other attributes. Due to this, such details can be specified in notifications and bank statements by issuers and used by other parties in payment processing.

Figure: Notification with the headquarters location specified

Figure: Notification with the web service address specified

Figure: Notification with the code specified

The basic details about every merchant are registered in the payment platform during the integration with the merchant web service and linked to the merchant identifier (Merchant ID, MID). These details are permanent, however, if needed, they can be modified—for this, address the ecommpay key account manager. Along with that, certain details about the merchant can change from operation to operation based on the information received in requests—these changeable details are called the dynamic descriptor. In such cases, the merchant details consist of the basic values for indicating the name and the country code of the organisation and the information from requests. This allows to use case-specific information, for example, the URL of the subscription management page when performing debiting of funds for the subscription.

Changeable merchant details can be used for the processing of one-time (one- and two-step) purchases and COF purchases as well as for making refunds for such purchases. Along with that, the transmitted data is restricted only by the string length and the set of valid characters (more on that further in the article), which provides enough flexibility in using this capability—including for customer authentication with the use of validation codes (similarly to the authentication on the merchant's request) by sending such codes in requests for them to be specified by the customers in the web service.

The basic details about every merchant are registered in the payment platform during the integration with the merchant web service and linked to the merchant identifier (Merchant ID, MID). Certain details about the merchant can change for separate operations based on the information received in the requests for processing these operations—these changeable details are called the dynamic descriptor. In such cases, the merchant details consist of the basic values for indicating the name and the country code of the organisation and the information from requests.

Setup

The basic details about the merchant are registered by the ecommpay specialists, which does not require the merchant's participation. The capability of using changeable details and inclusion of the specified details in final callbacks can be coordinated with the ecommpay key account manager. After the coordination, the ecommpay specialists perform the necessary setup in the payment platform and let the merchant know that the necessary configuration for using the changeable descriptions has been prepared.

The capability of using changeable details and inclusion of the specified details in final callbacks can be coordinated with the ecommpay key account manager. After the coordination, the ecommpay specialists perform the necessary setup in the payment platform and let the merchant know that the necessary configuration for using the changeable descriptions has been prepared.

Usage

After the capability of using changeable descriptions has been setup, the necessary details can be specified in the descriptor parameter of the merchant object in requests to the following endpoints:

• /v2/payment/card/sale—for one-time one-step purchases with the direct use of payment credentials;
• /v2/payment/card/sale/saved—for one-time one-step purchases with the use of the payment credentials identifiers;
• /v2/payment/card/sale/token—for one-time one-step purchases with the use of the payment credentials tokens;
• /v2/payment/card/recurring—for COF purchases;
• /v2/payment/card/refund—for purchase refunds.

• /v2/payment/card/sale,
• /v2/payment/card/sale/saved,
• /v2/payment/card/sale/token,
• /v2/payment/card/recurring,
• /v2/payment/card/refund.

The maximum length of the descriptor parameter value is 13 characters which can be Latin letters from the basic Latin alphabet, numbers, and the following valid special characters.

If this has been coordinated, the details sent in the requests are included in the merchantDescriptor parameter in final callbacks.

{
    "account": {
        "number": "431422******0056",
        "token": "f365bb1729f9b72fd9d18070d15654",
        "type": "visa",
        "card_holder": "ALBERT ASTONE",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "cosmo_customer_12"
    },
    "payment": {
        "date": "2022-06-23T09:07:00+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 2990,
            "currency": "USD"
        },
        "type": "purchase",
        "description": "Cosmoshop order"
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2022-06-23T09:08:00+0000",
        "created_date": "2022-06-23T09:07:45+0000",
        "request_id": "c6eed1e086d...d0413246c",
        "sum_initial": {
            "amount": 2990,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 2990,
            "currency": "USD"
        },
        "merchantDescriptor": "cosmoshop.com", // merchant details
        "code": "0",
        "message": "Success",
    },
    "signature": "v7KNMpfogAx1ZZ5D/aZAebMdeR+CqGilUwSm...=="
}

{
    "account": {
        "number": "431422******0056",
        "token": "f365bb1729f9b72fd9d18070d15654",
        "type": "visa",
        "card_holder": "ALBERT ASTONE",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "cosmo_customer_12"
    },
    "payment": {
        "date": "2022-06-23T09:07:00+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 2990,
            "currency": "USD"
        },
        "type": "purchase",
        "description": "Cosmoshop order"
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2022-06-23T09:08:00+0000",
        "created_date": "2022-06-23T09:07:45+0000",
        "request_id": "c6eed1e086d...d0413246c",
        "sum_initial": {
            "amount": 2990,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 2990,
            "currency": "USD"
        },
        "merchantDescriptor": "cosmoshop.com", // merchant details
        "code": "0",
        "message": "Success",
    },
    "signature": "v7KNMpfogAx1ZZ5D/aZAebMdeR+CqGilUwSm...=="
}