Card-to-card money transfers

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 are processed through the ECommPay payment platform. These operations are sale, payout, and reversal (if the payout operation is declined).
  • Partial. This workflow implies that either the sale operation or the payout operation is processed through the ECommPay payment platform. This workflow type can be 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 basic money transfer processing, payment information of the sender and the recipient can be provided in one of the following ways:

  • Card details—the sender provides the card details of both the sender and the recipient. These details are then passed by the web service in the money transfer request to the payment platform.
  • Saved card ID—the web service sends the identifier associated with the corresponding card details in the payment platform (for more information, see Saving payment data). It is possible to pass both the sender's and the recipient's saved card IDs in the money transfer request as well as either the ID of the sender's saved card or the ID of the recipient's saved card.

In case of the partial money transfer workflow, the payment information can be provided either in the form of the actual card details or as a token associated with these card details in the payment platform (for more information, see Using tokens). In case of debiting of funds, the sender's card details can be also passed in the request in the form of the saved card identifier.

Restrictions and special aspects

When setting up money transfer processing, consider the following restrictions:

  • 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.

When sending a request to return funds debited from the sender's card as part of the partial money transfer workflow (requests to the money_transfer/in and money_transfer/in/saved endpoints), consider the following:

  • Before attempting to return funds to the sender, make sure that the funds have not been credited to the recipient's card. It is necessary in order to prevent returning debited funds that have already been sent to the recipient. In case of partial money transfer, the burden of confirming that crediting took place is on the merchant.
  • Use the request to return funds only when the crediting of the recipient's card has not been completed and you need to return the amount intended for the said crediting to the sender. The recommended time to send such request is 30 minutes from the moment when the debiting has been completed. If for any reasons there is a need to return debited funds after the recommended time span, consider the following requirements of the global card networks for this operation type.

    Note:

    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. Upon expiration of the 24 hour time span, you have to contact the technical support specialists to return debited funds to the sender.

    According to Mastercard rules, you can send the request to return debited funds until the current business day is closed. After the current business day is closed, contact the technical support specialists to determine if this option is available.

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 return funds debited as part of the partial money transfer processing through Gate, the web service is required to send a request to the v2/payment/card/money_transfer/in/refund endpoint and subsequently to receive a callback with the result of the reversal operation.

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 section describes the request format for the basic and the partial money transfer processing workflows (debiting only and crediting only), including the request to return funds debited as part of the partial money transfer processing.

Basic workflow

When creating a request for basic money transfer processing, 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 ID assigned by ECommPay at the stage of integration;
      • payment_id—the payment ID unique within the merchant project;
      • signature—the request signature generated after all required parameters have been specified (for more information, see Signature generation and verification);
    • customer—the object containing the sender information:
      • id—the ID of the customer (money transfer sender) within the merchant project;
      • ip_address—the IP address;
      • country—the country code in ISO 3166-1 alpha-2;
      • city—the city (or any other place of residence);
      • first_name—the customer's first name;
      • last_name—the customer's last name;
      • zip—the customer's postal code;
      • address—the customer's address;
    • payment—the object containing the money transfer information:
      • sender_amount—the amount to be debited from the sender's card in minor currency units;
      • sender_currency—the currency code for the debited amount in ISO-4217 alpha-3;
      • recipient_amount—the amount to be credited to the recipient's card in minor currency units;
      • recipient_currency—the currency code for the credited amount in ISO-4217 alpha-3.
  3. The request must contain the following information about the sender's card:
    • When sending the actual card details, include the following parameters in the sender object:
      • pan—the card number;
      • year—the card expiration year;
      • month—the card expiration month;
      • card_holder—sender's first and last name (as specified on the card);
      • cvv—card verification code;
    • When sending the saved card ID, include the following parameters in the sender object:
      • saved_account_id—the identifier 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 card:
    • When sending the actual card details, include the following parameters in the recipient object:
      • pan—the recipient's card number;
      • card_holder—the recipient's first and last name (as specified on the card);
    • When sending the saved card ID, include the saved_account_id parameter in the recipient object.
  5. If Address Verification Service is required (obligatory for payments made in the UK, and optional for payments made 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.
  6. If necessary, you can also add any other additional parameters and objects specified in the API specification.

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 and the recipient's card details or saved card IDs.

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"
  },
//when sending the actual card details of the sender:
  "sender":{
    "pan":"4276381374757433",
    "year":2024,
    "month":10,
    "card_holder":"Gio Boccaccio",
    "cvv":"334"
  },
//when sending the saved card ID of the sender:
  "sender":{
    "saved_account_id": 21121375,
    "cvv": "334"
  },
//when sending the actual card details of the recipient:
  "recipient":{
    "pan":"5484381034771304",
    "card_holder":"Fran Petrarca"
  }
//when sending the saved card ID of the recipient:
  "recipient":{
    "saved_account_id": 19071374
  }
}

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 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—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 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 first and last name (as specified on the card);
      • cvv—card verification code;
    • When sending the token—the following parameters in the sender object:
      • token—card token;
      • cvv—card verification code;
      • card_holder—recipient's first and last name (as specified on the card), this parameter should be included if it was not passed in the request for generating the token (for more information, see Using tokens);
    • 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. The request must contain the following information about the money transfer recipient:
    • When sending the details of the recipient's card—the following parameters in the recipient object:
      • pan—card number;
      • card_holder—recipient's first and last name (as specified on the card);
    • When sending the information about the recipient's account—the following parameters in the recipient object:
      • wallet_id—number of the wallet that can be used in the partial money transfer processing;
      • wallet_owner—recipient's first and last name;
      • country—recipient's country code in ISO 3166-1 alpha-2.
  5. 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.
  6. If necessary, you can also add any other additional parameters and objects specified in the API specification.

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), the sender's card details or saved card ID and the recipient's card details or account information.

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"
  },
//when sending the actual card details of the sender:
  "sender":{
    "pan":"4276381374757433",
    "year":2024,
    "month":10,
    "card_holder":"Gio Boccaccio",
    "cvv":"334"
  },
//when sending the card token of the sender:
  "sender":{
    "token":"f365bb1729f9b72fd9c09703a751c979f3becc67",
    "card_holder":"Gio Boccaccio",
    "cvv":"334"
  },
//when sending the saved card ID of the sender:
  "sender":{
    "saved_account_id": 21121375,
    "cvv": "334",
  },
//when sending the details of the recipient's card:
"recipient":{
    "pan":"5484381034771304",
    "card_holder":"Fran Petrarca"
  }
//when sending the information about the recipient's account:
"recipient":{
    "wallet_id":"WID20071304"
    "wallet_owner":"Fran Petrarca",
    "country":"IT"
  }
}

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 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—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. The request must contain the following information about the card of the money transfer recipient:
    • When sending the actual card details—the following parameters in the recipient object:
      • pan—recipient's card number;
      • card_holder—recipient's first and last name (as specified on the card);
    • When sending the token—the recipient object with the token parameter.
  4. The request must contain the details of the sender's payment instrument. In the sender object, pass either the sender's card number in the pan parameter, or the number of the wallet that can be used in the partial money transfer processing in the wallet_id parameter.
  5. If necessary, you can also add any other additional parameters and objects specified in the API specification.

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) including the details of the sender's payment instrument as well as the number or the token of the recipient's card.

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"
  },
//when sending the actual card details of the recipient:
  "recipient":{
    "pan":"5484381034771304",
    "card_holder":"Fran Petrarca"
  },
//when sending the token:
  "recipient":{
    "token": 1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713
  },
//when sending the details of the sender's card:
"sender":{
    "pan":"4276381374757433"
  }
//when sending the information about the sender's account:
"sender":{
    "wallet_id":"WID16061313" 
  }
}

Request format for returning debited funds

When creating a request, consider the following:

  1. Send the request by using HTTP POST method to the /v2/payment/card/money_transfer/in/refund endpoint.
  2. The request must contain the general object with the general identification information of the request:
    • project_id—the project ID assigned by ECommPay at the stage of integration;
    • payment_id—the ID of the payment which requires the reversal of debiting;
    • signature—the request signature generated after all required parameters have been specified (for more information, see Signature generation and verification);
  3. If necessary, you can also add any other additional parameters and objects specified in the API specification.

Thus, a correct request for returning debited funds contains project and payment IDs as well as the signature.

{
  "general":{
    "project_id":91348,
    "payment_id":"135113521354",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  }
}

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 debited from the sender's card and the amount credited to the recipient's card. Objects sender and recipient each contain the account object that specifies the details of the payment card used for sending or receiving the money transfer. The account object also contains the type parameter that specifies the type of the customer's card, both for the sender and the recipient. In case of money transfer processing, possible values for this parameter include:

  • visa
  • mastercard
  • maestro

Basic workflow

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

Figure: Example of a callback body when debiting is declined

{
   "recipient":{                           //recipient's information
      "account":{
         "number":"473121******1778",
         "type":"visa",                    //type of the recipient's card
         "card_holder":"GREG KVITKA",
         "id":18111778,
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
   "sender":{                              //sender's information
      "account":{
         "number":"453912******1819",
         "type":"visa",                    //type of the sender's card
         "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":{                              //money transfer amount and currency
         "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":{                   //debited amount
            "amount":1827,
            "currency":"EUR"
         },
         "sum_converted":{                 //debited amount after conversion
            "amount":10150,
            "currency":"PLN"
         },
         "code":"10102",  //operation was 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":{                    //credited amount
            "amount":2185,
            "currency":"EUR"
         },
         "sum_converted":{                  //credited amount after conversion
            "amount":2185,
            "currency":"EUR"
         },
         "code":"100",
         "message":"General decline",
         "provider":{
            "id":2
         }
      }
   ],
   "signature":"hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
}

The following example 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 body when crediting is declined

{
   "recipient":{                             //recipient's information
      "account":{
         "number":"473121******1778",
         "type":"visa",                      //type of the recipient's card
         "card_holder":"GREG KVITKA",
         "id":18111778,
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
    "sender":{                               //sender's information
      "account":{
         "number":"453912******1819",
         "token": "c398469b3a88edb366b8b0407c084a8ead0c7fa88233d453d",
         "type":"visa",                      //type of the sender's card
         "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":{                                 //money transfer amount and currency
         "amount":0,
         "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":{                      //debited amount
            "amount":1856,
            "currency":"EUR"
         },
         "sum_converted":{                    //debited amount 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":{                      //credited amount
            "amount":1897,
            "currency":"EUR"
         },
         "sum_converted":{                    //credited amount 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":{                       //returned amount
            "amount":1897,
            "currency":"EUR"
         },
         "sum_converted":{                     //returned amount 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":"hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
}

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

Figure: Example of a callback body when money transfer has been completed

{
   "recipient":{                           //recipient's information
      "account":{
         "number":"473121******1778",
         "type":"visa",                    //type of the recipient's card
         "card_holder":"GREG KVITKA",
         "id":18111778,
         "country":"UA",
         "product_name":"Visa Rewards",
         "issuer_name":"JSC CB Privatbank"
      }
   },
    "sender":{                              //sender's information
      "account":{
         "number":"453912******1819",
         "token": "c398469b3a88edb366b8b0407c084a8ead0c7fa88233d453d",
         "type":"visa",                     //type of the sender's card
         "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":{                                //money transfer amount and currency
         "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":{                     //debited amount
            "amount":1856,
            "currency":"EUR"
         },
         "sum_converted":{                   //debited amount 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":{                     //credited amount
            "amount":1897,
            "currency":"EUR"
         },
         "sum_converted":{                    //credited amount 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=="
}

Partial workflow

The following example shows that the debiting has been completed as part of the basic money transfer processing.

Figure: Example of a callback body when the debiting has been completed

{
  "project_id":91663,
  "payment":{
    "id":"18641868",
    "type":"money_transfer",
    "status":"success",                        //payment status
    "date":"2020-10-08T18:52:54+0000",
    "method":"card",
    "sum":{                                    //money transfer amount and currency
      "amount":1856,
      "currency":"EUR"
    },
    "description":"card2cardtransfer"
  },
  "customer":{
    "id":"PK-184732WarStPT39"
  },
  "avs_result":"X",
  "tran_region":"domestic",
  "sender":{                                   //sender's information
    "account":{
      "number":"453912******1819",
      "type":"visa",
      "card_holder":"PANTOLEON KULISH",
      "country":"UA",
      "product_name":"Visa Rewards",
      "issuer_name":"JSC CB Privatbank",
      "expiry_month":"02",
      "expiry_year":"2024",
      "id":26071819,
      "token":"c398469b3a88edb366b8b0407c084a8ead0c7fa88233d453d"
    }
  },
  "operations":[
    {
      "id":1711000007251,
      "type":"sale",
      "status":"success",                      //operation status
      "date":"2020-10-08T18:52:54+0000",
      "created_date":"2020-10-08T18:52:19+0000",
      "request_id":"fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001712",
      "code":"0",
      "message":"Success",
      "provider":{
        "id":2,
        "payment_id":"18641868",
        "auth_code":"331040",
        "endpoint_id":2,
        "date":"2020-10-08T18:52:54+0000"
      },
      "sum_initial":{                           //debited amount
        "amount":1856,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":1856,
        "currency":"EUR"
      },
      "region":"domestic",
      "rrn":"000218401850"
    }
  ],
  "signature":"hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
}

The following example shows that the crediting has been completed as part of the basic money transfer processing.

Figure: Example of a callback body when the crediting has been completed

{
    "project_id": 91663,
    "payment": {
      "id": "18641868",
      "type": "money_transfer",
      "status": "success",                      //payment status
      "date": "2020-10-08T18:52:54+0000",
      "method": "card",
      "sum": {                                  //money transfer amount and currency
        "amount": 1856,
        "currency": "EUR"
      },
      "description": "card2cardtransfer"
    },
    "customer": {
      "id": "PK-184732WarStPT39"
    },
    "tran_region": "intereuropean",
    "recipient": {                              //recipient's information
      "account": {
        "number": "473121******1778",
        "type": "visa",
        "card_holder": "GREG KVITKA",
        "country": "UA",
        "product_name": "Visa Rewards",
        "issuer_name": "JSC CB Privatbank",
        "expiry_month": "03",
        "expiry_year": "2025",
        "id": 18111778
      }
    },
    "operations": [
      {
        "id": 1711000007252,
        "type": "payout",
        "status": "success",                    //operation status
        "date": "2020-10-08T18:52:54+0000",
        "created_date": "2020-10-08T18:52:19+0000",
        "request_id": "fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001712",
        "code": "0",
        "message": "Success",
        "provider": {
          "id":2,
          "payment_id": "18641868",
          "auth_code": "331040",
          "endpoint_id": 2,
          "date": "2020-10-08T18:53:53+0000"
        },
        "sum_initial": {                        //credited amount
          "amount": 1856,
          "currency": "EUR"
        },
        "sum_converted": {
          "amount": 1856,
          "currency": "EUR"
        },
        "region": "intereuropean",
        "rrn": "000218401856"
      }
    ],
    "signature": "hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
  }

Format of callback with information about returning funds

To communicate the result of processing the request to return debited funds to the sender, the standard format for callbacks is used. In addition to the information about the payment status and all operations initiated within this payment, the callback contains information about the sender of the money transfer as well as the information about the amount that was debited and then subsequently credited back to the sender's card.

The following example shows that the funds have been credited to the sender's card as part of the basic money transfer processing.

Figure: Example of a callback body when the funds have been returned to sender

{
  "project_id":91663,
  "payment":{
    "id":"18641868",
    "type":"money_transfer",
    "status":"reversed",                         //payment status
    "date":"2020-10-08T18:52:54+0000",
    "method":"card",
    "sum":{                                      //money transfer amount and currency
      "amount":0,
      "currency":"EUR"
    },
    "description":"card2cardtransfer"
  },
  "customer":{
    "id":"PK-184732WarStPT39"
  },
  "avs_result":"X",
  "tran_region":"intereuropean",
  "sender":{                                     //sender's information
    "account":{
      "number":"453912******1819",
      "type":"visa",
      "card_holder":"PANTOLEON KULISH",
      "country":"UA",
      "product_name":"Visa Rewards",
      "issuer_name":"JSC CB Privatbank",
      "expiry_month":"02",
      "expiry_year":"2024",
      "id":26071819
    }
  },
  "operations":[
    {
      "id":1711000007251,
      "type":"sale",
      "status":"success",                        //operation status                 
      "date":"2020-10-08T18:52:54+0000",
      "created_date":"2020-10-08T18:52:19+0000",
      "request_id":"fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001712",
      "code":"0",
      "message":"Success",
      "provider":{
        "id":2,
        "payment_id":"18641868",
        "auth_code":"331040",
        "endpoint_id":2,
        "date":"2020-10-08T18:52:54+0000"
      },
      "sum_initial":{                            //debited amount
        "amount":1856,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":1856,
        "currency":"EUR"
      },
      "region":"intereuropean",
      "rrn":"000218401850"
    },
    {
      "id":1711000007253,
      "type":"reversal",
      "status":"success",                        //operation status
      "date":"2020-10-08T18:58:24+0000",
      "created_date":"2020-10-08T18:58:12+0000",
      "request_id":"fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001712",
      "code":"0",
      "message":"Success",
      "provider":{
        "id":2,
        "payment_id":"18641868",
        "endpoint_id":2,
        "date":"2020-10-08T18:58:24+0000"
      },
      "sum_initial":{                             //returned amount
        "amount":1856,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":1856,
        "currency":"EUR"
      },
      "region":"intereuropean",
      "rrn":"000218401850"
    }
  ],
  "signature":"hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
}

The following example shows that the operation initiated to return funds to sender has been declined.

Figure: Example of a callback body when the operation to return funds has not been completed

{
  "project_id":91663,
  "payment":{
    "id":"18641868",
    "type":"money_transfer",
    "status":"success",                           //payment status
    "date":"2020-10-08T18:52:54+0000",
    "method":"card",
    "sum":{                                       //money transfer amount and currency
      "amount":1856,
      "currency":"EUR"
    },
    "description":"card2cardtransfer"
  },
  "customer":{
    "id":"PK-184732WarStPT39"
  },
  "avs_result":"X",
  "tran_region":"intereuropean",
  "sender":{                                      //sender's information
    "account":{
      "number":"453912******1819",
      "type":"visa",
      "card_holder":"PANTOLEON KULISH",
      "country":"UA",
      "product_name":"Visa Rewards",
      "issuer_name":"JSC CB Privatbank",
      "expiry_month":"02",
      "expiry_year":"2024",
      "id":26071819
    }
  },
  "operations":[
    {
      "id":1711000007251,
      "type":"sale",
      "status":"success",                         //operation status
      "date":"2020-10-08T18:52:54+0000",
      "created_date":"2020-10-08T18:52:19+0000",
      "request_id":"fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001712",
      "code":"0",
      "message":"Success",
      "provider":{
        "id":2,
        "payment_id":"18641868",
        "auth_code":"331040",
        "endpoint_id":2,
        "date":"2020-10-08T18:52:54+0000"
      },
      "sum_initial":{                             //debited amount
        "amount":1856,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":1856,
        "currency":"EUR"
      },
      "region":"intereuropean",
      "rrn":"000218401850"
    },
    {
      "id":1711000007253,
      "type":"reversal",
      "status":"decline",                         //operation status
      "date":"2020-10-08T18:58:24+0000",
      "created_date":"2020-10-08T18:58:12+0000",
      "request_id":"fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001712",
      "code":"10706",          //operation was declined by the issuer
      "message":"Refund unavailable for current operation",
      "provider":{
        "id":2,
        "payment_id":"18641868",
        "endpoint_id":2,
        "date":"2020-10-08T18:58:24+0000"
      },
      "sum_initial":{                             //returned amount
        "amount":1856,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":1856,
        "currency":"EUR"
      },
      "region":"intereuropean",
      "rrn":"000218401850"
    }
  ],
  "signature":"hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
}