Payouts to bank accounts in different countries

Introduction

Payouts to bank accounts in different countries is a payment method which allows you to process payments in different currencies by using bank accounts in most countries. This method supports payouts.

This article provides information about working with the Payouts to bank accounts in different countries method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

General information

Interaction diagram

Payment processing by using the Payouts to bank accounts in different countries method involves the merchant's web service, one of ecommpay interfaces, the ecommpay payment platform, and technical facilities of the provider service.

Operations support

Payouts by using the Payouts to bank accounts in different countries method can be processed by using Gate. At the same time, the following properties are applicable.

When working with the Payouts to bank accounts in different countries the following properties are applicable.

Processing scenarios

To process a payout by using the Payouts to bank accounts in different countries method, you need to notify the customer via the web service.

Figure: Payout by using Gate

General information

To process a payout through Gate by using the Payouts to bank accounts in different countries method, send a request with all required parameters and signature to the ecommpay URL and receive a callback with the result. The full sequence and special aspects of payout processing are provided below.

Information about the formats of requests and callbacks used for processing payouts by using the Payouts to bank accounts in different countries method via Gate is presented further in this section. General information about working with the Gate API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending payout requests by using the Payouts to bank accounts in different countries method:

1. To initiate each payout send a separate POST request to the /v2/payment/bank-transfer/world/payout endpoint. This endpoint belongs to the group /v2/payment/bank-transfer/{payment_method}/payout.
2. Each request must include the following objects and parameters:
   • Object general—general payout information:
     • project_id—project identifier obtained from ecommpay during integration
     • payment_id—payment identifier unique within the project
     • signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) details
   • Object payment—payment information:
     • amount—payout amount in the smallest currency unit
     • currency—payout currency code in the ISO-4217 alpha-3 format
   • Object customer—customer information:
     • id—customer identifier unique within the project
     • ip_address—customer IP address relevant for the initiated payout

3. In requests specifying EUR and GBP currencies, when working with some providers, it may be necessary to pass the recipient's country code in the ISO 3166-1 alpha-2 format in the value of two parameters: payment.extra_param and customer.country. This is relevant for recipients from the following countries: AR, AU, BR, CA, CN, CO, CL, GB, HK, KR, IN, ID, LK, MX, MY, NP, PE, PH, SG, TH, TR, US, UY, VN.

   Refer to your ecommpay key account manager for clarification regarding the requirement for such an indication of the country code.

4. It is recommended to specify a number of additional parameters. If the request is missing the parameters, the list of parameters is sent in the clarification callback. The callback body is formed in accordance with the JSON-Schema specification. For more details, see Submission of additional payment information.

   It is recommended to use the following objects and parameters:

   • Object customer—recipient information:
     • address—address
     • country—country code in the ISO 3166-1 alpha-2 format
     • person_type—account type (available values: individual for accounts of individuals, company for accounts of companies)
     • first_name—name of the recipient (only the first name is sufficient) or title of the company
   • Object account—recipient account information:
     • number—account number
     • routing_type—type of interbank transfer system, allowed values: ACH CODE—for USA, BANK CODE—for Hong Kong, BSB CODE—for Australia, IFSC—for India, SORT CODE—for UK, TRANSIT NUMBER—for Canada, BRANCH CODE—for Brazil, SWIFT—for other countries supported by this payment method
     • routing_number—bank identifier in the interbank transfer system
5. Also, depending on the specifics of a particular payment and the peculiarities of different banks, other parameters may be needed to process a payment. In this case, an additional clarification callback is sent to clarify information about the payment. These parameters include:
   • Object payment—payout information:
     • local_conversion_currency—currency code of the recipient country in the ISO-4217 alpha-3 format (can be required if US or CA country code is specified in the customer.country parameter; however, in certain cases, the absence of this parameter in the initial request may lead to a declined payment; refer to ecommpay technical support if you have questions about using this parameter)
   • Object sender—sender information:
     • beneficiary_relationship—legal relationship between the sender and the recipient (for example employee, buyer, etc.)
   • Objectcustomer—recipient information:
     • city—city
     • email—email address
     • phone—must be specified using a country code and without punctuation or special characters, for example 13125555251
     • state—state or region
     • zip—zip code
     • Object identify—information about the document which establishes identity:
       • doc_type—type of the identity document, for example Passport, Company Organization Code, Company Social Credit Code, etc.
       • doc_number—number of the identity document
   • Object account—recipient account information:
     • type—type of bank account, for exampleChecking for specifying a checking account, Saving for a savings account, etc.)
     • bank_name—recipient bank name
     • bank_code—recipient bank code (consists of three digits, can be required if BRL, HKD or CAD currency code is specified in the payment.currency parameter; refer to your ecommpay key account manager for the list of allowed bank codes)
6. Payment currency can be only one of the supported ones.
7. Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the Payouts to bank accounts in different countries method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer identifier and account information (with additional information if required), and signature.

 {
  "general": {
    "project_id": 3027,
    "payment_id": "payout1",
    "signature": "M1vT4q9c8hA8xCjEwGFSANI+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
   "payment": {
     "amount": 1000,
     "currency": "EUR"
     "local_conversion_currency": "EUR",
     "extra_param": "US"
  },
   "sender": {
     "beneficiary_relationship": "Employee"
  },
   "customer": {
     "id": "customer1",
     "ip_address": "1.2.3.4",
     "address": "12 Spring Rd",
     "country": "US",
     "person_type": "individual",
     "first_name": "John",
     "city": "Los Angeles",
     "email": "customer@example.com",
     "phone": "12130019875",
     "state": "California",
     "zip": "12345",
     "identify": { 
         "doc_type": "Passport",
         "doc_number": "1234"
      }
  },
   "account": {
     "number": "1020304010",
     "routing_type": "SWIFT",
     "routing_number": "ADCBINBB"
     "type": "Saving",
     "bank_name": "Example Bank",
     "bank_code": "123"
  }
}

 {
  "general": {
    "project_id": 3027,
    "payment_id": "payout1",
    "signature": "M1vT4q9c8hA8xCjEwGFSANI+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
   "payment": {
     "amount": 1000,
     "currency": "EUR"
     "local_conversion_currency": "EUR",
     "extra_param": "US"
  },
   "sender": {
     "beneficiary_relationship": "Employee"
  },
   "customer": {
     "id": "customer1",
     "ip_address": "1.2.3.4",
     "address": "12 Spring Rd",
     "country": "US",
     "person_type": "individual",
     "first_name": "John",
     "city": "Los Angeles",
     "email": "customer@example.com",
     "phone": "12130019875",
     "state": "California",
     "zip": "12345",
     "identify": { 
         "doc_type": "Passport",
         "doc_number": "1234"
      }
  },
   "account": {
     "number": "1020304010",
     "routing_type": "SWIFT",
     "routing_number": "ADCBINBB"
     "type": "Saving",
     "bank_name": "Example Bank",
     "bank_code": "123"
  }
}

Callback format

The Payouts to bank accounts in different countries method uses the standard format for callbacks to deliver payout results. For more information, see Callbacks.

The following is the example of a callback with information about a 1,00 EUR payout made in the 1774 project.

{
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "LV81HABA06"
        },
        "project_id": 22351,
        "payment": {
            "id": "TEST_2_17022022",
            "type": "payout",
            "status": "success",
            "date": "2022-02-17T13:45:34+0000",
            "method": "world",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "id": 55969010087671,
            "type": "payout",
            "status": "success",
            "date": "2022-02-17T13:45:34+0000",
            "created_date": "2022-02-17T13:45:06+0000",
            "request_id": "0d9e9a0199baccc886a320da858e93919ce-00055970",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2421,
                "payment_id": "PY23297248",
                "auth_code": "",
                "date": "2022-02-17T13:45:26+0000"
            }
        },
        "signature": "dRj303+vVN+HghppyhEAK0c658yzVALLB4v192P6Bb8vhmA=="
    }

The following is the example of a callback with information about a declined payout.

{
    "project_id": 1774,
    "payment": {
        "id": "1234567891",
        "type": "payout",
        "status": "decline",
        "date": "2020-04-06T11:34:51+0000",
        "method": "world",
        "sum": {
            "amount": 100,
            "currency": "EUR"
        },
        "description": "Order 67"
    },
    "account": {
        "number": "123"
    },
    "customer": {
        "id": "31234"
    },
    "operation": {
        "id": 538,
        "type": "payout",
        "status": "decline",
        "date": "2020-04-06T11:33:51+0000",
        "created_date": "2020-04-06T11:33:44+0000",
        "request_id": "ea8cf9c100f6ce886540493cfc99be653d03e76e0500b8-00000002",
        "sum_initial": {
            "amount": 100,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 100,
            "currency": "EUR"
        },
        "code": "3028",
        "message": "Insufficient funds on merchant balance",
        "provider": {
            "id": 1971,
            "payment_id": "15861728285",
            "auth_code": "",
            "date": "2020-04-06T11:33:50+0000"
        }
    },
    "signature": "Q8xo7IGQBS+HSqBLSwLMgV8FO0qrHsDnlbUqOdN8fa3frn9tgg=="
}

Useful links

The following articles can be useful when implementing payouts via Gate:

• Interaction concepts—about the interaction with the payment platform by using Gate.
• Signature generation and verification—about the procedure of generating and verifying signatures in requests and callbacks.
• Payment models and statuses—about the types, processing models, and possible statuses of supported payments and operations.
• Payouts—about processing of payouts by using Gate.
• Information of operations performing—about error and response codes that are used in the payment platform to record information about performing of operations.