Card-to-card money transfer

This section covers information about processing card-to-card money transfers. It complements the corresponding section on payment models and statuses (Card-to-card money transfer).

Overview

Money transfer is a payment type which uses one request to initiate debiting funds from the sender's card and subsequently crediting these funds to the recipient's card. Money transfers can be sent from one customer to another as well as between the cards of the same customer.

In the payment platform, the following money transfer processing workflows are available:

  • Basic. This workflow implies that all operations necessary to execute a money transfer—sale, payout, and, if the payout operation is declined, reversal—are processed through the ECommPay payment platform.
  • Partial. This workflow implies that either the sale operation or the payout operation is processed through the ECommPay payment platform. This workflow type is relevant when the merchant needs to process one of the operations through an external payment services provider. For more information about partial money transfer processing, refer to your account manager.

In case of both basic and partial money transfer processing, the sender's payment information can be provided as follows:

  • Card details—the customer provides card details which are then sent by the web service in the money transfer request to the payment platform.
  • Saved card ID—the web service sends an identifier associated with the corresponding card details in the payment platform (to learn more, see Saving payment data).

The recipient's card details are provided the sender of the money transfer as is and are then sent by the web service in the money transfer request to the payment platform.

Restrictions

The following restrictions should be considered when setting up money transfer processing:

  • In the ECommPay payment platform, money transfer processing is supported only for Mastercard and Visa cards.
  • Merchants should consult their account manager in order to coordinate the possibility of setting up currency conversion on their side.

Available workflows

Basic workflow

To initiate basic money transfer processing through Gate, the web service is required to do the following:

  1. Send a request to the /v2/payment/card/money_transfer endpoint.
  2. If necessary, complete an additional procedure of the 3-D Secure authentication of the customer .
  3. Receive a callback with the money transfer result from the payment platform.

The following diagram illustrates the basic money transfer processing workflow (without completion of an additional procedure).

Figure: Basic money transfer processing

  1. A customer (the sender of the money transfer) initiates the money transfer.
  2. The web service sends a request for money transfer to a URL specified by ECommPay.
  3. The payment platform receives the request.
  4. The payment platform accepts the request and performs its validity check.
  5. The payment platform sends a validity check response to the merchant's web service.
  6. The request is processed in the payment platform.
  7. A request for debiting funds is sent by the payment platform to the payment system and subsequently—to the issuer of the customer's card.
  8. The request for debiting funds is processed by the issuer of the customer's card.
  9. The information about the result is sent from the issuer to the payment system and subsequently—to the payment platform.
  10. The payment platform processes the result.
  11. A request for crediting funds is sent by the payment platform to the payment system and subsequently—to the issuer of the recipient's card.
  12. The request for crediting funds is processed by the issuer of the recipient's card.
  13. The information about the result is sent from the issuer to the payment system and subsequently—to the payment platform.
  14. The payment platform sends a callback with the information about the result to the merchant's web service.
  15. The web service notifies the customer about the result of the money transfer processing.

If the request for crediting funds to the recipient's card is declined, the payment platform automatically initiates a reversal operation which cancels the debiting of funds from the sender's card. The following diagram illustrates the basic money transfer processing workflow if crediting of funds is declined.

Figure: Money transfer processing when debiting of funds is cancelled

  1. The payment platform processes the result.
  2. A request for crediting funds is sent by the payment platform to the payment system and subsequently—to the issuer of the recipient's card.
  3. The request is processed by the issuer of the recipient's card.
  4. The information about the result is sent from the issuer to the payment system and subsequently—to the payment platform.
  5. The payment platform processes the result and initiates cancellation of debiting funds from the sender's card.
  6. A request for cancelling the debiting of funds is sent by the payment platform to the payment system and subsequently—to the issuer of the sender's card.
  7. The request is processed by the issuer of the sender's card.
  8. The information about the result is sent from the issuer to the payment system and subsequently—to the payment platform.
  9. The payment platform sends a callback with the information about the result to the merchant's web service.
  10. The web service notifies the customer that the money transfer has been declined.

Partial workflow

To initiate the debiting of funds from the sender's card as part of the partial money transfer processing through Gate, the web service is required to do the following:

  1. Send a request to the /v2/payment/card/money_transfer/in endpoint.
  2. If necessary, complete an additional procedure of the 3-D Secure authentication of the customer .
  3. Receive a callback with the result of the debiting operation from the payment platform.

To initiate the crediting of funds to the recipient's card as part of the partial money transfer processing through Gate, the web service is required to do the following:

  1. Send a request to the /v2/payment/card/money_transfer/out endpoint.
  2. Receive a callback with the result of the crediting operation from the payment platform.

The sections that follow discuss in more detail the request format and the parameters to be used in requests for money transfer as well as provide information about the format of callbacks which communicate the result of the money transfer processing.

Request format

This sections describes the format of request for both the basic and the partial money transfer processing (debiting only and crediting only).

Basic workflow

When you create a request for basic money transfer processing, consider the following:

  1. Send the request by using HTTP POST method to one of the following endpoints:
  2. The request must contain the following objects and parameters:
    • Object general—general request identification information:
      • project_id—a project ID assigned by ECommPay at the stage of integration;
      • payment_id—payment ID unique within the merchant project;
      • signature—a request signature generated after all required parameters have been specified. (To learn more, see Signature generation and verification);
    • Object recipient—money transfer recipient information:
      • pan—recipient's card number;
      • card_holder—recipient's name and last name (as specified on the card);
    • Object customer—customer (money transfer sender) information:
      • id—the ID of the customer (money transfer sender) within the merchant project;
      • ip_address—IP address;
      • country—country code in ISO 3166-1 alpha-2;
      • city—city of residence;
      • first_name—customer's first name;
      • last_name—customer's last name;
      • zip—customer's postal code;
      • address—customer's address;
    • Object payment—money transfer information:
      • sender_amount—amount to be debited from the sender's card in minor units of currency;
      • sender_currency—currency code for the debited amount in ISO-4217 alpha-3;
      • recipient_amount—amount to be credited to the recipient's card in minor units of currency;
      • recipient_currency—currency code for the credited amount in ISO-4217 alpha-3.
  3. The request must contain the following information about the card of the customer (money transfer sender):
    • When sending the actual card details—the following parameters in the sender object:
      • pan—card number;
      • year—card expiration year;
      • month—card expiration month;
      • card_holder—sender's name and last name (as specified on the card);
      • cvv —card verification code;
    • When sending the saved card ID—the following parameters in the sender object:
      • saved_account_id—an identifier associated with the corresponding card details in the payment platform;
      • cvv—card verification code.
  4. If Address Verification Service is required (obligatory for payments made in the UK, and optional—in the USA, Australia, Canada and New Zealand), in the initial request include an AvsInfo object which specifies the address kept on file as current by the issuer for the money transfer sender:
    • avs_post_code—postal code;
    • avs_street_address—street and building number.
  5. If necessary, you can also add any other additional parameters and objects Gate supports.

Thus, a correct request for the basic money transfer processing contains project and payment IDs, the signature, the payment's amount and currency code, information about the customer (money transfer sender) as well as the sender's card details or saved card ID and the recipient's card details.

Figure: Example of a money transfer request

{
  "general":{
    "project_id":91348,
    "payment_id":"135113521354",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225",
    "first_name":"Gio",
    "last_name":"Boccaccio",
    "country":"IT",
    "city":"Florence",
    "zip":"50052",
    "address":"Via Certaldo 18"
  },
  "payment":{
    "sender_amount":100,
    "sender_currency":"EUR",
    "recipient_amount":100,
    "recipient_currency":"EUR"
  },
    "recipient":{
    "pan":"5484381034771304",
    "card_holder":"Fran Petrarca"
  },
//when sending the actual card details:
  "sender":{
    "pan":"4276381374757433",
    "year":2024,
    "month":10,
    "card_holder":"Gio Boccaccio",
    "cvv":"334"
  },
//when sending the saved card ID:
  "sender":{
    "saved_account_id": 21121375,
    "cvv": "334"
  }
}

Partial workflow

When you create a request for debiting funds from the sender's card as part of the partial money transfer processing, consider the following:

  1. Send the request by using HTTP POST method to one of the following endpoints:
  2. The request must contain the following objects and parameters:
    • Object general—general request identification information:
      • project_id—a project ID assigned by ECommPay at the stage of integration;
      • payment_id—payment ID unique within the merchant project;
      • signature—a request signature generated after all required parameters have been specified. (To learn more, see Signature generation and verification);
    • Object recipient with the recipient's name and the last name in the card_holder parameter;
    • Object payment—money transfer information:
      • sender_amount—amount to be debited from the sender's card in minor units of currency;
      • sender_currency—currency code for the debited amount in ISO-4217 alpha-3;
    • Object customer—customer (money transfer sender) information:
      • id—the ID of the customer within the merchant project;
      • ip_address—IP address.
  3. The request must contain the following information about the card of the customer (money transfer sender):
    • When sending the actual card details—the following parameters in the sender object:
      • pan—card number;
      • year—card expiration year;
      • month—card expiration month;
      • card_holder—sender's name and last name (as specified on the card);
      • cvv —card verification code;
    • When sending the saved card ID—the following parameters in the sender object:
      • saved_account_id—an identifier associated with the corresponding card details in the payment platform;
      • cvv—card verification code.
  4. If Address Verification Service is required (obligatory for payments made in the UK, and optional—in the USA, Australia, Canada and New Zealand), in the initial request include an AvsInfo object which specifies the address kept on file as current by the issuer for the money transfer sender:
    • avs_post_code—postal code;
    • avs_street_address—street and building number.
  5. If necessary, you can also add any other additional parameters and objects Gate supports.

Thus, a correct request for debiting funds from the sender's card contains project and payment IDs, the signature, the amount to be debited and the corresponding currency code, the ID and the IP address of the customer (money transfer sender) as well as the sender's card details or saved card ID.

Figure: Example of the request for debiting funds

{
  "general":{
    "project_id":91348,
    "payment_id":"135113521354",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225"
  },
  "payment":{
    "transfer_type":"in",
    "sender_amount":100,
    "sender_currency":"EUR"
  },
  "recipient":{
    "card_holder":"Fran Petrarca"
  },
//when sending the actual card details:
  "sender":{
    "pan":"4276381374757433",
    "year":2024,
    "month":10,
    "card_holder":"Gio Boccaccio",
    "cvv":"334"
  },
//when sending the saved card ID:
  "sender":{
    "saved_account_id": 21121375,
    "cvv": "334"
  }
}

When you create a request for crediting funds to the recipient's card as part of the partial money transfer processing, consider the following:

  1. Send the request by using HTTP POST method to the /v2/payment/card/money_transfer/out endpoint.
  2. The request must contain the following objects and parameters:
    • Object general—general request identification information:
      • project_id—a project ID assigned by ECommPay at the stage of integration;
      • payment_id—payment ID unique within the merchant project;
      • signature—a request signature generated after all required parameters have been specified. (To learn more, see Signature generation and verification);
    • Object recipient—money transfer recipient information:
      • pan—recipient's card number;
      • card_holder—recipient's name and last name (as specified on the card);
    • Object payment—money transfer information:
      • recipient_amount—amount to be credited to the recipient's card in minor units of currency;
      • recipient_currency—currency code for the credited amount in ISO-4217 alpha-3;
    • Object customer—customer (money transfer sender) information:
      • id—the ID of the customer (money transfer sender) within the merchant project;
      • ip_address—IP address;
      • country—country code in ISO 3166-1 alpha-2;
      • city—city of residence;
      • first_name—customer's first name;
      • last_name—customer's last name;
      • zip—customer's postal code;
      • address—customer's address;
  3. If necessary, you can also add any other additional parameters and objects Gate supports.

Thus, a correct request for crediting funds to the recipient's card contains project and payment IDs, the signature, the amount to be credited and the corresponding currency code, information about the customer (money transfer sender), and the recipient's card details.

Figure: Example of the request for crediting funds

{
  "general":{
    "project_id":91348,
    "payment_id":"135113521354",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225",
    "first_name":"Gio",
    "last_name":"Boccaccio",
    "country":"IT",
    "city":"Florence",
    "zip":"50052",
    "address":"Via Certaldo 18"
  },
  "payment":{
    "transfer_type":"out",
    "recipient_amount":100,
    "recipient_currency":"EUR"
  },
  "recipient":{
    "pan":"5484381034771304",
    "card_holder":"Fran Petrarca"
  }
}

Callback format

To communicate money transfer results, the standard format for callbacks is used. To learn more, see Callbacks. In addition to the information about the payment status and all operations initiated within this payment, the callback contains information about the sender and the recipient of the money transfer as well as the information about the amount to be debited from the sender's card and the amount to be credited to the recipient's card.

The following example of a callback shows that the operation to debit funds from the sender's card has been declined.

Figure: Example of a callback when debiting is declined

{
   "recipient":{                           //sender's information
      "account":{
         "number":"4731216543211778",
         "type":"visa",
         "card_holder":"GREG KVITKA",
         "id":18111778,
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
   "sender":{                              //recipient's information
      "account":{
         "number":"4539124567981819",
         "type":"visa",
         "card_holder":"PANTOLEON KULISH",
         "id":26071819,
         "expiry_month":"02",
         "expiry_year":"2024",
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
   "customer":{
      "id":"PK-184732WarStPT39"
   },
   "payment":{
      "date":"2019-10-08T18:52:54+0000",
      "id":"18161821",
      "method":"card",
      "status":"decline",                  //payment status
      "sum":{                              //amount and currency to be credited
         "amount":1827,
         "currency":"EUR"
      },
      "type":"money_transfer",
      "description":"card2cardtransfer"
   },
   "project_id":91663,
   "operations":[
      {
         "id":1711000007251,
         "type":"sale",
         "status":"decline",
         "date":"2019-10-08T18:52:54+0000",
         "created_date":"2019-10-08T18:52:19+0000",
         "request_id":"fda091a6bc3b81-069b9fd5abb47bac02-00001712",
         "sum_initial":{                   //amount to be debited
            "amount":1827,
            "currency":"EUR"
         },
         "sum_converted":{              //amount to be debited after conversion
            "amount":10150,
            "currency":"PLN"
         },
         "code":"10102",  //operation declined due to incorrectly entered data
         "message":"Incorrect data entered",
         "eci":"05",
         "provider":{
            "id":2,
            "payment_id":"18161821",
            "auth_code":"331040",
            "endpoint_id":2,
            "date":"2019-10-08T18:52:53+0000"
         }
      },
      {
         "id":1711000007252,
         "type":"payout",
         "status":"decline",
         "date":"2019-10-08T18:52:54+0000",
         "created_date":"2019-10-08T18:52:19+0000",
         "request_id":"fda091ae66bc52e587a81-069b9fd5b47bac02-00001712",
         "sum_initial":{                    //amount to be credited                  
            "amount":2185,
            "currency":"EUR"
         },
         "sum_converted":{             //amount to be credited after conversion
            "amount":2185,
            "currency":"EUR"
         },
         "code":"100",
         "message":"General decline",
         "provider":{
            "id":2
         }
      }
   ]
}"signature":"hQAYY7mMIeAbeT234Ka26PaXSdm8ptxuEq/g=="

The following example of a callback shows that the operation to credit funds to the recipient's card has been declined and the cancellation of debiting has been completed.

Figure: Example of a callback when crediting is declined

{
   "recipient":{                           //recipient's information
      "account":{
         "number":"4731216543211778",
         "type":"visa",
         "card_holder":"GREG KVITKA",
         "id":18111778,
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
    "sender":{                               //sender's information
      "account":{
         "number":"4539124567981819",
         "token": "c398469b3a88edb366b8b0407c084a8ead0c7fa88233d453d",
         "type":"visa",
         "card_holder":"PANTOLEON KULISH",
         "id":26071819,
         "expiry_month":"02",
         "expiry_year":"2024",
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
    "customer":{
      "id":"PK-184732WarStPT39"
   },
   "payment":{
      "date":"2019-10-08T18:52:54+0000",
      "id":"18641868",
      "method":"card",
      "status":"reversed",                    //payment status
      "sum":{                                 //amount and currency to be credited
         "amount":1856,
         "currency":"EUR"
      },
      "type":"money_transfer",
      "description":"card2cardtransfer"
   },
   "project_id":91663,
   "operations":[
      {
         "id":1711000007251,
         "type":"sale",                       //operation status
         "status":"success",
         "date":"2019-10-08T18:52:54+0000",
         "created_date":"2019-10-08T18:52:19+0000",
         "request_id":"fda091ae6387af268ef81-069b9fd57bac02-00001712",
         "sum_initial":{                      //amount to be debited
            "amount":1856,
            "currency":"EUR"
         },
         "sum_converted":{              //amounted to be debited after conversion
            "amount":10150,
            "currency":"PLN"
         },
         "code":"0",
         "message":"Success",   
         "eci":"05",
         "provider":{
            "id":2,
            "payment_id":"18641868",
            "auth_code":"331040",
            "endpoint_id":2,
            "date":"2019-10-08T18:52:53+0000"
         }
      },
      {
         "id":1711000007252,
         "type":"payout",
         "status":"decline",            //operation status
         "date":"2019-10-08T18:52:54+0000",
         "created_date":"2019-10-08T18:52:19+0000",
         "request_id":"fda091ae66bc387af268ef81-069b9fd5ab4639898b47bac02-00001712",
         "sum_initial":{                 //amount to be credited
            "amount":1897,
            "currency":"EUR"
         },
         "sum_converted":{               //amount to be credited after conversion
            "amount":1897,
            "currency":"EUR"
         },
         "code":"100",
         "message":"General decline",
         "provider":{
            "id":2,
            "payment_id":"18641868",
            "auth_code":"331041",
            "endpoint_id":2,
            "date":"2019-10-08T18:53:53+0000"
         }
      },
      {
         "id":1711000007253,
         "type":"reversal",
         "status":"success",                //operation status
         "date":"2019-10-08T18:52:54+0000",
         "created_date":"2019-10-08T18:52:19+0000",
         "request_id":"fda091ae66bc52387af268ef81-069b9fd5ab9b07898b47bac02-00001712",
         "sum_initial":{                   //amount supposed to be debited
            "amount":1897,
            "currency":"EUR"
         },
         "sum_converted":{      //amount supposed to be debited after conversion
            "amount":10150,
            "currency":"PLN"
         },
         "code":"0",
         "message":"Success",
         "provider":{
            "id":2,
            "payment_id":"290583056",
            "endpoint_id":2,
            "date":"2019-10-08T18:55:53+0000"
         }
      }
   ]
}"signature":"hQAYY7mMIelgkBWPrBmfFaxNxzaskXE/TiUZ26PaXSdm8ptxuEq/g=="

The following example of a callback shows that the money transfer has been completed successfully.

Figure: Example of a successful money transfer callback

{
   "recipient":{                           //recipient's information
      "account":{
         "number":"4731216543211778",
         "type":"visa",
         "card_holder":"GREG KVITKA",
         "id":18111778,
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
    "sender":{                              //sender's information
      "account":{
         "number":"4539124567981819",
         "token": "c398469b3a88edb366b8b0407c084a8ead0c7fa88233d453d",
         "type":"visa",
         "card_holder":"PANTOLEON KULISH",
         "id":26071819,
         "expiry_month":"02",
         "expiry_year":"2024",
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
    "customer":{
      "id":"PK-184732WarStPT39"
   },
  "payment":{
      "date":"2019-10-08T18:52:54+0000",
      "id":"18641868",
      "method":"card",
      "status":"success",                    //payment status
      "sum":{                                //amount and currency to be credited
         "amount":1856,
         "currency":"EUR"
      },
      "type":"money_transfer",
      "description":"card2cardtransfer"
   },
   "project_id":91663,
   "operations":[
      {
         "id":1711000007251,
         "type":"sale",                      //operation status
         "status":"success",
         "date":"2019-10-08T18:52:54+0000",
         "created_date":"2019-10-08T18:52:19+0000",
         "request_id":"fda091ae6387af268ef81-069b9fd57bac02-00001712",
         "sum_initial":{                     //amount to be debited
            "amount":1856,
            "currency":"EUR"
         },
         "sum_converted":{               //amount to be debited after conversion
            "amount":10150,
            "currency":"PLN"
         },
         "code":"0",
         "message":"Success",   
         "eci":"05",
         "provider":{
            "id":2,
            "payment_id":"18641868",
            "auth_code":"331040",
            "endpoint_id":2,
            "date":"2019-10-08T18:52:53+0000"
         }
      },
      {
         "id":1711000007252,
         "type":"payout",
         "status":"success",                  //operation status     
         "date":"2019-10-08T18:52:54+0000",
         "created_date":"2019-10-08T18:52:19+0000",
         "request_id":"fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001712",
          "sum_initial":{                     //amount to be credited
            "amount":1897,
            "currency":"EUR"
         },
         "sum_converted":{              //amount to be credited after conversion
            "amount":1897,
            "currency":"EUR"
         },
         "code":"0",
         "message":"Success",
         "provider":{
            "id":2,
            "payment_id":"18641868",
            "auth_code":"331040",
            "endpoint_id":2,
            "date":"2019-10-08T18:53:53+0000"
         }
      }
   ]
}"signature":"hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="