Using Mastercard MoneySend and Visa Direct services

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.

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:
   • when sending the actual card details—/v2/payment/card/sale;
   • when sending the saved card identifiers—/v2/payment/card/sale/saved;
   • when sending the card tokens—/v2/payment/card/sale/token;
   • when Apple Pay or Google Pay is used to make a payment—/v2/payment/applepay/sale or /v2/payment/googlepay/sale respectively.
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.

{
  "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:
   • when sending the actual card details—/v2/payment/card/payout;
   • when sending the card tokens—/v2/payment/card/payout/token.
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.

{
  "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" 
  }
}