Using Mastercard MoneySend and Visa Direct services

Overview

The ecommpay payment platform supports the capabilities of Mastercard MoneySend and Visa Direct networks that significantly simplify transferring money between customers and merchants. These services offer the functionality that utilises specific operations to withdraw (i.e. debit) funds from the accounts of customers (senders) and to deliver (i.e. credit) funds to the accounts of customers (recipients). These debiting and crediting operations can be executed separately or combined, and since global card schemes require that the funds reach the target accounts in 30 minutes or less, using Mastercard MoneySend and Visa Direct services makes transferring funds fast and efficient as well as convenient for customers.

Main characteristics of these operations can be summed up as follows:

Debiting Crediting
Mastercard MoneySend operation Funding transaction (FT) Payment transaction (PT)
Visa Direct operation Account Funding Transaction (AFT) Original Credit Transaction (OCT)
ecommpay platform equivalent operation sale payout
Available payment methods
  • Card payments
  • Apple Pay
  • Google Pay

Card payments

Available payment instruments Mastercard or Visa cards Mastercard or Visa cards
Operation can be cancelled

after it has been processed

+

with certain time restrictions

Use cases
  • Adding funds to the customer’s account in the merchant’s service.
  • The first step of the card-to-card money transfer (with funds debited from the account of the sender).
  • A payout to a customer.
  • The second step of the card to card money transfer (with funds credited to the account of the recipient)

Since these operations are executed as sale and payout in the ecommpay payment platform (utilising the corresponding sets of required parameters), you can initiate them in any interface that fits your needs: debiting operations can be initiated not only via Gate but also via Payment Page and mobile SDKs while crediting operations can be initiated via Gate and Dashboard.

If you have any questions regarding the possible restrictions imposed by the global card schemes when these services are used and how to connect to them, refer to your ecommpay account manager.

Workflow

General information

Workflows of processing debiting and crediting operations via Gate are by and large identical to the workflows of processing one-step purchases and payouts: the web service must send a request to initiate each of these operations, perform intermediate actions if they are demanded by the prescriptive callbacks received from the platform, and accept the final informational callback. When a card-to-card money transfer is processed, these two operations have to be initiated consecutively: first, the debiting operation and, once it has been completed, the crediting operation.

Options to specify payment information

As in the case with other kinds of purchases and payouts in the ecommpay payment platform, when When working with debiting and crediting operations executed as part of the Mastercard MoneySend and Visa Direct services, you can choose from several options to specify payment card details:

  • Actual card details—in the request, pass the card number, expiry date, the first and last name of the cardholder, and CVV.
  • Arbitrary saved card identifier—in the request, pass the identifier associated with the corresponding card details in the payment platform (for more information, see Saving payment data).
  • Standardised card token—in the request, pass the token associated with the corresponding card details in the payment platform (for more information, see Using tokens).

Debiting

To initiate the debiting of funds via Gate, the web service is required to do the following:

  1. Send a request to the /v2/payment/{payment method}/sale[/selected option to specify payment information] endpoint.
  2. If necessary, complete a procedure of the 3‑D Secure customer authentication (for more information, see 3‑D Secure authentication).
  3. Receive a callback from the payment platform with the result of the debiting operation.

The format of the request for debiting is presented in the following section of this article.

Returning debited funds

In certain cases, you may need to return debited funds to the customer. From a technical standpoint, the cancellation of debiting is executed as a refund and is initiated with the request to the /v2/payment/{payment_method}/refund endpoint. Keep in mind that according to the rules of the global card schemes only full payments can be refunded within limited time periods.

According to Visa rules, you can send the request to return debited funds only during the first 24 hours from the moment when the debiting has been completed while according to Mastercard rules this should be done within three business days. Upon expiration of these time limits, you have to contact the ecommpay technical support to return debited funds to the customer.

Crediting

To initiate the crediting of funds via Gate, the web service is required to do the following:

  1. Send a request to the /v2/payment/card/payout[/token] endpoint.
  2. Receive a callback from the payment platform with the result of the crediting operation.

The format of the request for crediting is presented in the following section of this article.

Request format

Debiting

When creating a request for debiting, consider the following:

  1. The request must be sent to one of the following endpoints with the use of the HTTP POST method:
  2. The request must contain the following objects and parameters:
    • general—the object containing the general identification information of the request:
      • project_id—the project identifier assigned by ecommpay;
      • payment_id—the payment identifier unique within the project;
      • signature—the request signature generated after all required parameters have been specified (for more information, see Signature generation and verification);
    • payment—the object containing the debiting information:
      • amount—the amount to be debited from the customer’s (sender's) card in the smallest currency units;
      • currency—the currency code for the debited amount in ISO-4217 alpha-3;
    • customer— the object containing the information about the customer (sender):
      • id—the identifier of the customer within the project;
      • ip_address—the IP address of the customer;
      • country—the customer’s country code in ISO 3166-1 alpha- 2;
      • address—the customer's address, required when Visa cards are used;
      • city—the customer’s city (or any other place of residence), required when Visa cards are used;
      • state_code—the customer’s state or province code, required when funds are credited to Visa cards issued in the USA or Canada;
      • phone—the customer’s phone number, required when funds are credited to Visa cards issued in Brazil or Qatar;
      • account_id—the customer’s wallet number, required when Mastercard cards are used;
      • first_name—the customer's first name, required when Apple Pay or Google Pay is used;
      • last_name—the customer's last name, required when Apple Pay or Google Pay is used.
  3. The request must contain the following information about the sender’s (customer’s) card:
    • When sending the actual card details, include the following parameters in the card object:
      • pan—the card number;
      • year—the card expiration year;
      • month—the card expiration month;
      • card_holder—the first and last name of the cardholder (as specified on the card);
      • cvv—the card verification code.
    • When sending the saved card identifier, include the following parameters in the card object:
      • saved_account_id—the identifier associated with the corresponding card details in the payment platform;
      • cvv—the card verification code.
    • When sending the token—include the following parameters:
      • token—the token associated with the corresponding card details in the payment platform;
      • cvv—the card verification code.
  4. The request must contain the following information about the recipient’s payment instrument:
    • When sending the recipient’s wallet information—include the following parameters in the recipient object:
      • wallet_id—the wallet number;
      • wallet_owner—the first and last name of the wallet owner;
      • country—the wallet owner’s country code in ISO 3166-1 alpha- 2, required when a Mastercard is linked to this wallet.
    • When sending the card details—include the following parameters in the recipient object:
      • pan—the recipient's card number;
      • card_holder—the first and last name of the cardholder (as specified on the card).
    • When sending the details of a Visa card issued in Canada, include the following parameters (in addition to the required card data):
      • country—the recipient’s country code in ISO 3166-1 alpha-2;
      • address—the recipient’s address;
      • city—the recipient’s city (or any other place of residence);
      • state_code—the recipient’s state or province code.
  5. If necessary, you can also add any other additional parameters and objects specified in the API specification.

Thus, a correct request for debiting funds contains project and payment identifiers, the signature, the amount to be debited and the corresponding currency code, information about the sender, and the payment information of the sender and the recipient specified as one of the options described above.

The following example contains the body of the request for debiting from a Visa with the funds intended for subsequent crediting to a Mastercard.

Figure 1. Example of the debiting request
{
  "general":{
    "project_id":91348,
    "payment_id":"135113521354",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "payment":{
    "amount":1000,
    "currency":"EUR"
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225,
    "country":"IT",
    "city":"Florence",
    "address":"Via Certaldo 18"
  },
//when sending the details of the sender's card:
  "card":{
    "pan":"4314220000000056",
    "year":2024,
    "month":10,
    "card_holder":"Gio Boccaccio",
    "cvv":"334"
  },
//when sending the saved card identifier:
  "card":{
    "saved_account_id": 21121375,
    "cvv": "334"
  },
//when sending the card token:
    "token":"f365bb1729f9b72fd9c09703a751c979f3becc67",
    "cvv":"334",
//when sending the details of the recipient's card:
"recipient":{
    "pan":"5413330000000019",
    "card_holder":"Fran Petrarca"
  }
//when sending the information about the recipient's wallet:
"recipient":{
    "wallet_id":"WID20071304",
    "wallet_owner":"Fran Petrarca",
    "country":"IT"
  }
}

Crediting

When creating a request for crediting, consider the following:

  1. The request must be sent to one of the following endpoints with the use of the HTTP POST method:
  2. The request must contain the following objects and parameters:
    • general—the object containing the general identification information of the request:
      • project_id—the project identifier assigned by ecommpay;
      • payment_id—the payment identifier unique within the project;
      • signature—the request signature generated after all required parameters have been specified (for more information, see Signature generation and verification);
    • payment—the object containing the crediting information::
      • amount—the amount to be credited the recipient's card in the smallest currency units;
      • currency—the currency code for the credited amount in ISO-4217 alpha-3;
    • customer—the object containing the information about the sender:
      • id—the identifier of the customer (sender) within the project;
      • ip_address—the IP address of the customer.
  3. The request must contain the following information about the recipient’s card:
    • When sending the card details—include the following parameters in the card object:
      • pan—the recipient's card number;
      • card_holder—the first and last name of the cardholder (as specified on the card).
    • When sending the token—include the following parameters:
      • token—the token associated with the corresponding card details in the payment platform.
  4. The request must contain the following information about the sender in the sender object:
    • Payment instrument information is specified in one of the following parameters:
      • pan—the sender's card number;
      • wallet_id—the sender's wallet number.
    • In addition, include the following parameters in the request:
      • country—the sender’s country code in ISO 3166-1 alpha- 2;
      • address—the sender's address, required when Visa cards are used;
      • city—the sender’s city (or any other place of residence), required when Visa cards are used;
      • first_name—the sender's first name;
      • last_name—the sender's last name;
      • state_code—the sender’s state or province code, required when funds are credited to Visa cards issued in the USA or Canada;
      • zip—the sender’s postal code, required when Mastercard cards are used;
      • day_of_birth—the sender's date of birth in the DD-MM-YYYY format, recommended when Visa cards are used;
      • phone—the sender’s phone number, required when funds are credited to Visa cards issued in Brazil or Qatar.
  5. The request must contain the following information about the recipient in the recipient object:
    • first_name—the first name of the recipient;
    • last_name—the last name of the recipient.
  6. If necessary, you can also add any other additional parameters and objects specified in the API specification.

Thus, a correct request for crediting funds contains project and payment identifiers, the signature, the amount to be credited and the corresponding currency code, information about the sender and the recipient, and the payment information of the sender and the recipient specified as one of the options described above.

The following example contains the body of the request for crediting funds to a Mastercard with the funds previously debited from a Visa.

Figure 2. Example of the crediting request
{
  "general":{
    "project_id":91348,
    "payment_id":"135113521355",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225"
  },
  "payment":{
    "amount":1000,
    "currency":"EUR"
  },
  "recipient":{
    "first_name":"Fran",
    "last_name":"Petrarca"
  },
  "sender":{
    "country":"IT",
    "city":"Florence",
    "address":"Via Certaldo 18",
    "first_name":"Gio",
    "last_name":"Boccaccio",
    "day_of_birth":"16-06-1313"
  },
//when sending the details of the recipient's card:
  "card":{
    "pan":"5413330000000019",
    "card_holder":"Fran Petrarca"
  },
//when sending the card token:
    "token": 1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713,
//when sending the details of the sender's card:
"sender":{
    "pan":"4314220000000056"
  }
//when sending the number of the sender's wallet:
"sender":{
    "wallet_id":"WID16061313" 
  }
}

Callback format

Results of processing Mastercard MoneySend and Visa Direct operations are communicated in callbacks of standard format. To learn more about the callback format, see Callbacks.

Figure 3. Example of callback with the debiting result
    {
        "project_id": 91348,
        "payment": {
            "id": "135113521354",
            "type": "purchase",
            "status": "success",
            "date": "2022-02-22T19:52:14+0000",
            "method": "card",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "account": {
            "number": "431422******0056",
            "type": "visa",
            "token": "f365bb1729f9b72fd9c09703a751c979f3becc67",
            "country": "IT",
            "bank": "Intesa Sanpaolo SpA",
            "product": "debit"
        },
        "customer": {
            "id": "16061313"
        },
        "operations": [
            {
                "provider": {
                    "result_message": "Success",
                    "result_code": "00",
                    "id": 2,
                    "payment_id": "135113521354",
                    "auth_code": "661786",
                    "endpoint_id": 3651,
                    "date": "2022-02-22T19:52:14+0000"
                },
                "rrn": "305440290856",
                "region": "domestic",
                "code": "0",
                "message": "Success",
                "eci": "05",
                "id": 52901540107953,
                "type": "sale",
                "status": "success",
                "date": "2022-02-22T19:52:14+0000",
                "created_date": "2022-02-22T19:51:18+0000",
                "request_id": "a51091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-d7bc0c44525",
                "sum_initial": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "sum_converted": {
                    "amount": 1000,
                    "currency": "EUR"
                }
            }
        ],
        "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
    }
Figure 4. Example of callback with the crediting result
    {
        "project_id": 91348,
        "payment": {
            "id": "135113521355",
            "type": "payout",
            "status": "success",
            "date": "2022-02-22T20:01:36+0000",
            "method": "card",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "account": {
            "number": "541333******0019",
            "type": "mastercard",
            "token": "1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713"
        },
        "customer": {
            "id": "16061313"
        },
        "issuer_name": "UniCredit SpA",
        "product_name": "World Mastercard",
        "country": "IT",
        "card_product_type": "debit",
        "card_holder": "Fran Petrarca",
        "operations": [
            {
                "type": "payout",
                "provider": {
                    "result_message": "Success",
                    "result_code": "00",
                    "id": 2,
                    "payment_id": "135113521355",
                    "auth_code": "309410",
                    "endpoint_id": 3651,
                    "date": "2022-02-22T20:01:35+0000"
                },
                "status": "success",
                "date": "2022-02-22T20:01:36+0000",
                "rrn": "301360291143",
                "created_date": "2022-02-22T20:01:34+0000",
                "region": "domestic",
                "request_id": "fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001711",
                "code": "0",
                "sum_initial": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "message": "Success",
                "sum_converted": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "id": 5013600010130727
            }
        ],
        "signature": "hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
    }