# Payouts {#en_Gate_payout .concept} An article about processing payouts via Gate. **Note:** This article covers processing payouts via Gate and describes requests and callbacks that are used in case of card payments. In addition, use the following materials to gain a fuller understanding of performing payouts: - [Payout](en_platform_payout_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of processing payouts in the Ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it. - articles of the [Payment methods](en_pm_about.md) section containing a description of performing payouts via Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks. ## Overview {#section_htd_ylv_cjb .section} *Payout* is a payment type which uses one request to make a one-time transfer of funds from merchant to customer. Basically, the payment platform performs payouts on demand \(one-time payments\)and P2P \(person-to-person\) payouts; though, you can implement bulk payouts by using Dashboard. In the latter case, you can have the required payouts generated automatically. For more information about bulk payouts, see [Monitoring and performing payments](en_dbl_payments.md). Basically, payout initiation request contains payment instrument details. However,if you perform payout on a payment card you can perform payout by token that is associated with the payment card details. To enable this option, you need to perform an initial payment \(purchase\) to create a token.For more information about using tokens, see [Using tokens](en_Gate_Token.md). ## The payout workflow {#section_lsx_3jl_ggb .section} To perform a payout by using Gate the web service is required to do the following: 1. Send the payout request to the following endpoint `/v2/payment/{payment method}/payout[/token]`. 2. If necessary, complete the additional procedure of payment information submission that is used when any payment stakeholder requires additional information. The procedure is not currently supported for alternative payment methods.For more information, see [Submission of additional payment information](en_Gate_Clarification.md). 3. Receive the callback with payout results from the payment platform. The following diagram provides the information about the basic payout processing case \(without the completion of the additional procedure\). ![](images/en_uml_gate_payout.svg) 1. A customer initiates a payout. 2. The web service sends the payout request by using Gate to the payment platform. 3. The payment platform receives the payout request. 4. The payment platform performs the initial request processing that includes validation of the required parameters and signature. 5. The payment platform sends to the web service the response with request receipt confirmation and correctness check result. 6. The payment platform performs the internal payment request processing and sends it to the payment environment.If you process the payout by using payment card, the payment environment is a bank service. If you process the payout by using alternative payment instrument, one is the payment system service. 7. The payout is processed on the payment service side. 8. The payment platform receives the payout result notification. 9. The payment platform sends the callback to the web service. 10. The customer receives the payment result from the web service. The sections that follow discuss in more details the request format and the parameters to be used in requests for payouts to payment cards, as well as provide information about the format of callbacks which contain payout results. Information about possible statuses of this payment type can be found in [the corresponding article](en_platform_payment_model.md). ## Request format {#section_t11_mfk_1jb .section} There are several things you need to consider when using payout requests to payment cards: 1. You perform payout by sending the request by using POST \(HTTP\) method to one of the following endpoints: - when making a payout by card number—[/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout), - when making a payout by the token that is associated with payment card details—[/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token), - when making a P2P payout—[/v2/payment/individual/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-individual-payout). 2. The following objects and parameters must be specified in the request: - Object `general`—general request identification information: - `project_id`—the project ID obtained from Ecommpay - `payment_id`—payment ID unique within the merchant project - `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md) - Object `customer`—customer information: - `id`—the ID of the customer within the merchant project - `first_name`—customer first name - `middle_name`—customer middle name or patronymic - `last_name`—customer last name - `ip_address`—IP address **Note:** The first name, the middle name \(or patronymic\), and the last name must be specified in Basic Latin characters for all cards with the exception of CUP cards for which this information must be provided in Chinese characters. In case of payouts that originate from physical persons and that are processed as part of the programs supported for the Mastercard MoneySend service, it is required that the first and last names of the payout recipient are specified in the `recipient` object. Therefore, it is not necessary to specify this information in the `customer` object \([more](en_Gate_payout.md#li_ucr_fj5_tqb)\). This requirement applies to all cards regardless of where they were issued. - Object `payment`—payment information: - `amount`—payout amount in minor units - `currency`—payout currency in the ISO-4217 alpha-3 format - `cryptocurrency_type`—the indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies. This parameter should be assigned one of the following values: - `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority; - `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution; - `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments; - `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation. 3. The request must contain the following information about the payment card of the payout recipient: - For a payout by card number—the card number in the `pan` parameter of the `card` object. In the case of global payouts, together with the card number the request must contain the expiration date and the name of the cardholder specified in the `year`, `month`, and `card_holder` parameters of the `card` object. To learn more about global payouts, contact your Ecommpay account manager. - For a payout by token—the card token received from Ecommpay in the `token` parameter. In some cases, together with the token the payout request must contain the name of the cardholder specified in the `card_holder` parameter of the `card` object. Passing the `card_holder` parameter is not required if at least one of the following criteria applies: - The name of the cardholder was provided correctly in a payment request payload that was used to generate the token. - The requirement to specify the cardholder name together with the token is disabled for your project because the underlying risk is low. In other cases, in particular when tokens were generated within Apple Pay and Google Pay payments, the payout request must contain the name of the cardholder. By default, passing the `card_holder` parameter is recommended to avoid payment declines. To learn more about using tokens without specifying the name of the cardholder, contact your Ecommpay account manager. 4. In the case of a payout to any Visa card, the request should contain the date of birth of the sender, specified in `DD-MM-YYYY` format in the `day_of_birth` parameter in the `sender` object. 5. In the case of a payout to a Visa card issued in Canada, the request must contain the `recipient` object with the payout recipient's address data: - `country`—recipient's country code in ISO 3166-1 alpha-2 - `city`—recipient's city - `address`—recipient's address - if the specified country code is [CA](references/en/countries/CA.md) or [US](references/en/countries/US.md), also pass the `state` parameter that provides information about the recipient's state, province, or any other region 6. In the case of a payout processed as part of the Visa Money Transfer program to a card issued in Brazil or Qatar, the request must contain the sender's phone number in the `phone` parameter of the `sender` object. 7. In the case of a payout to a Mastercard, the value of the `address` parameter passed in the `customer` object cannot exceed 50 characters. 8. In the case of a payout that originates from a physical person and that is processed as part of the programs supported for the Mastercard MoneySend service, the request must contain the information about the payout recipient's name in the `first_name` and `last_name` parameters of the `recipient` object and the information about the payout sender in the `sender` object: - number of the sender's payment instrument—`pan` for the sender's card or `wallet_id` for the sender's electronic wallet - `first_name`—sender's first name - `last_name`—sender's last name - `address`—sender's address - `city`—sender's city - `zip`—sender's postal code - `country`—sender's country code in ISO 3166-1 alpha-2 - if the specified country code is [CA](references/en/countries/CA.md) or [US](references/en/countries/US.md), also pass the `state` parameter that provides information about the sender's state, province, or any other region 9. In the case of a P2P payout it is recommended to specify the sender data: - `first_name`—first name - `last_name`—last name, - `citizenship`—citizenship - `residence`—country of residence - `birthplace`—place of birth - Object `billing`—sender billing address information 10. If required, you can also add any other additional parameters and objects Gate supports. Thus, to perform a payout on a payment card, the correct payout request must include project and payment IDs, signature, the ID and IP-address of the customer, amount and currency of the payout, as well as the number or token of the card \(for crediting\), as shown in the following example: ```language-json { "general": { "project_id": 874, "payment_id": "1553840734526111", "signature": "1wR1YgDoDlJppOdLzFOFKY4YonbWmspbFh7x1o1ut5PxxTIJfQ==", }, // Card number when payout by the card number "card": { "pan": "5413330000000019" }, "customer": { "id": "1", "ip_address": "185.123.193.224" }, "payment": { "amount": 15000, "currency": "EUR" }, // Card token when payout by the token "token": "pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7" } ``` ```language-json { "general": { "project_id": 100, "payment_id": "Payment 12", "signature": "2tlMuYxLW9Yu6RETr8pdCfmi0UPE8euD+2AbrQgJgu...==" }, "card": { "pan": "4242424242424242", "year": 2020, "month": 11 }, "customer": { "ip_address": "127.0.0.1", "id": "New", "phone": "999123456", "first_name": "John", "middle_name": "Jr", "last_name": "Jonson", "datetime": "2017-10-04T19:06:31+05:00", "birthplace": "Manchester", "identify": { "doc_number": "4666 123456", "doc_type": "Passport", "doc_issue_date": "20.12.2012", "doc_issue_by": "12346" }, "billing": { "country": "GB", "city": "London", "address": "Level st, 23", "postal": "112233" }, "day_of_birth": "05-06-1981" }, "sender": { "phone": "39999999999", "first_name": "Jack", "middle_name": "Willy", "last_name": "Jackson", "datetime": "2018-12-05T19:06:31+05:00", "birthplace": "Manchester", "residence": "BL", "citizenship": "LV", "identify": { "doc_number": "1234 654321", "doc_type": "Passport", "doc_issue_date": "07-08-2014", "doc_issue_by": "23456" }, "billing": { "country": "GB", "city": "London", "address": "Level st, 25", "postal": "406879" }, "day_of_birth": "07-08-1993" }, "payment": { "amount": 5000, "currency": "GBP" } } ``` ## Callback format {#section_wsx_3jl_ggb .section} The standard format for callbacks is used to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md). The following is the example of a callback with an information about successful `100.00 USD` payout made to the card number `553691******0802` of the `customer_10` customer in the `874` project. ```language-json { { "project_id": 874, "payment": { "id": "3013", "type": "payout", "status": "success", "date": "2019-06-24T11:08:49+0000", "method": "card", "sum": { "amount": 10000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019" }, "customer": { "id": "customer_10" }, "operation": { "id": 14, "type": "payout", "status": "success", "date": "2019-06-24T11:08:49+0000", "created_date": "2019-06-24T11:07:42+0000", "request_id": "71228f54d21e776a481", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "provider": { "id": 1496, "payment_id": "60-1c6072de6000", "date": "2019-06-24T11:08:47+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+TaK4UzSgifLxgB6c9TSeb/peLxw==" } } ``` The following example of callback is for a payout rejected due to the maximum payout limit being exceeded. ```language-json { { "project_id": 874, "payment": { "id": "3013", "type": "payout", "status": "decline", "date": "2019-06-24T11:08:49+0000", "method": "card", "sum": { "amount": 10000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019" }, "customer": { "id": "customer_10" }, "operation": { "id": 14, "type": "payout", "status": "decline", "date": "2019-06-24T11:08:49+0000", "created_date": "2019-06-24T11:07:42+0000", "request_id": "71228f54d21e776a481", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "provider": { "id": 1496, "payment_id": "60-1c6072de6000", "date": "2019-06-24T11:08:47+0000", "auth_code": "" }, "code": "3104", "message": "Payment Constraint Invalid Payout Amount" }, "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+MEXXja28RXtr8v2EITaK4UzSg...==" } } ``` **Parent topic:**[Gate](en_Gate_Integration_About.md)