Performing payouts

Overview

The ecommpay payment platform supports the capability to issue payouts to card accounts with the use of Payment Page. Each payout is at first registered via the Gate API and then the payment form is opened in the Payout operation mode. Along with that, payouts via Payment Page can originate both from the merchant and from a physical person, while their processing can involve Mastercard MoneySend and Visa Direct services.

To register a payout, send a corresponding request to the platform via the Gate API and receive a callback about the registration result. If the payout has been registered, the callback contains a special identifier (uuid) that must be specified in the request for opening Payment Page. Keep in mind that this identifier is valid for 30 minutes and the time that remains for confirming the payout is displayed on the payment form pages. In case if the customer does not confirm the payout until the allocated time expires, a corresponding notification is displayed to this customer and, for the payout to be processed, it has to be re-registered with a new payment identifier (payment_id) specified.

A payout via Payment Page is made upon the customer's confirmation with the use of a confirmation code. Such codes are sent from the payment platform to the customer's email address provided during the payout registration.

When the customer requests a payout with the use of Payment Page, they select a payment instrument, specify the instrument credentials, then enter the confirmation code, and receive a notification about the result. The payment instrument credentials can be specified in one of the following ways:

• On the payment form, by completing the fields. In this case, the customer completes all required fields on the payment form.
• On the payment form, by completing the fields or selecting saved payment information. In this case, the customer can either select one of the saved payment instruments or enter new payment information. The new payment instrument can also be saved for subsequent payment processing.
• Outside the payment form, by selecting previously saved payment information. In this case, the customer selects a specific card in the web service, the token associated with this card is specified in the request for opening Payment Page, and once the payment form is opened, it already contains all required payment information.

Payout processing can be finalised with the generation of payment card tokens. It is applicable when card details have not been saved before, and this capability has been set up for the merchant's project in use (details).

Customer payout scenario

Suppose that the customer Prostetnik Jeltz has won the third place in the Millstone Jennings Poetry competition with the prize of 70 EUR. To receive the funds, the customer specifies their payment instrument details, first name, and last name, then confirms the payout and waits for its result.

Restrictions

The following restrictions apply to processing payouts via Payment Page:

• You have to make sure that this capability has been added and set up for the project in use.

  When the payment form is opened in the Payout operation mode within the project without the integrated payouts functionality, a callback with the 317 error code is sent from the payment platform to the web service (details).

• To send requests for payouts registration, use the IP addresses that you provided to the ecommpay technical support specialists who subsequently added them to the whitelist.

  If a request is sent from an IP address that is not whitelisted, a response with the 403 error code is sent from the payment platform to the web service (details).

• The limits set for the payout recipient's payment card must be complied with. These limits include the number of payouts, their amount in total, and the amount of a one-time transfer of funds.

  If any of these limits is exceeded, the payout is declined, the customer is shown a page with the message that the payment has been declined, and a callback with the relevant error code is sent to the web service.

• The merchant's account balance must contain enough funds for issuing a payout.

  If there are insufficient funds, the payout is declined, the customer is shown a page with the message that the payment has been declined, and a callback with the relevant error code is sent to the web service. Balance information can be monitored via Dashboard (details) and retrieved via the Data API (details). If you have any questions, contact your ecommpay account manager.

• You must comply with requirements imposed by global card networks and programs within which payouts are issued as well as requirements and rules that are specific to particular regions, payment systems, and providers.

  Depending on the program, for example, there are different requirements as to what information about the payout sender or recipient should be provided in the requests for opening Payment Page.

  Note:

  These requirements may have to do with such cases as follows:

  • For payouts performed as part of the Mastercard MoneySend service when the payout sender is a physical person, it is required that the first name and the last name of the payout recipient as well as the first name and the last name, the payment instrument identifier and the address of the payout sender are specified—if this data is not specified, the payout is declined.
  • For payouts performed as part of the Visa Direct Money Transfer program, in case of a payout to a card issued in Canada, it is required that the payout recipient's address is specified—if this data is not specified, an additional page with fields to fill in with the details is displayed to the customer.

  For more in-depth understanding of performing payouts depending on different conditions, refer to your account manager.

• When opening the payment form, the capability of limiting the time for working with it must not be used (details). The time of working with the payment form is limited by default and equals the validity period of the uuid identifier.

  If the request for opening the payment form contains the date and time limiting the work with the form, the customer is shown the payment form page with the error message.

Setup

To have the capability of processing payouts with the use of Payment Page set up, merchants should complete the following steps:

1. Discuss with the ecommpay account manager and agree on the capability setup steps, the need for testing the capability, and the application of restrictions in each particular case.
2. If it was agreed that testing is required, wait to be notified by the ecommpay specialists when the functionality is ready, then test the payment form workflow with the new capability. After that, inform the account manager that you are ready to launch the functionality in your production environment.
3. Receive a notification about the completion of the capability setup from the ecommpay specialists.

Workflow

To perform a payout via Payment Page, the web service is required to do the following:

1. Generate the request for registering a payout and send it to the payment platform.
2. Receive a callback with information about payout registration from the platform.
3. Generate and send a request for opening Payment Page in the Payout operation mode.
4. Receive a callback with information about the payment processing result from the payment platform.

It may be needed to carry out an additional procedure of the payment information submission when processing payouts. The customer will be shown a message and additional fields to be completed on the payment form. This procedure is performed without the merchant's web service involved, but it does require the participation of the customer.

Format of request for payout registration

There are several things you should consider when sending a request for payout registration:

1. In every case of payout registration, send a separate POST request to the /v2/payment/payout/registration endpoint.
2. Each request must include the following objects and parameters:
   • Object general—general identification information of the request:
     • 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)
   • Object payment—payment information:
     • amount—payment amount in the smallest currency unit
     • currency—payment currency code in the ISO-4217 alpha-3 format
   • Object customer—customer information:
     • id—customer's identifier unique within the project
     • email—customer's email address
     • phone—customer's phone number
     • ip_address—customer's IP address relevant for the payout being registered

Thus, a correct request for payout registration must contain the project identifier, basic payment information (identifier, amount, and currency code), customer information and signature.

  "general": {
    "project_id": 91348,
    "payment_id": "cosmoshop_payout_1323",
    "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer": {
    "id": "16061314",
    "email": "p.jeltz@mail.com",
    "phone": "44991234567",   
    "ip_address": "93.47.230.225"
  },
  "payment": {
    "amount": 7000,
    "currency": "EUR"
  }
}

Format of callback with the payout registration result

During the processing of a payout with the use of Payment Page, on the web service side it is required to receive an intermediate callback with information about the payout registration result from the payment platform and use the identifier submitted in the uuid parameter. The format of such callbacks is standard (details).

The following is an example of a callback indicating that a payout has been registered in the 91348 project for the 16061314 customer.

{
    "general": {
        "project_id": "91348",
        "payment_id": "cosmoshop_payout_1323",
        "signature": "V2mxcUcGUcCtAE51lgesBefZgfG9NHpQEbfdI2X1Q=="
    },
    "request_id": "50715",
    "payment": {
        "id": "cosmoshop_payout_1323",
        "type": "payout",
        "status": "awaiting_payout_completion",
     },
    "operation": {
        "id": "500359719",
        "type": "payout",
        "status": "awaiting_payout_completion"
    },
    "customer": {
        "id": "16061314"
    },
    "sum_request":
    {
        "amount": "7000",
        "currency": "EUR"
    },
    "transaction": {
        "type": "payout"
    },
    "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5GTkVvY/sRDLKAnSS+AagnGCJ1nsPg==",
    "uuid_expired_at": "2024-04-24T13:50:37+0000"
}

Format of request for opening the payment form

The format of request for opening Payment Page to process card payouts is the same as the one described in the Interaction concepts section. When generating such requests, you should consider the following:

1. The following parameters must be specified in the request:
   • mode—the indicator of the Payment Page operation mode. The value must be payout.
   • project_id—project identifier obtained from ecommpay during integration
   • payment_id—payment identifier specified in the request for payout registration and unique within the project
   • uuid—payout identifier received in a callback with information about the payout registration result
   • customer_id—customer's identifier specified in the request for payout registration and unique within the project
   • customer_email—customer's email address specified in the request for payout registration
   • payment_amount—payment amount specified in the request for payout registration, in the smallest currency unit
   • payment_currency—payment currency code specified in the request for payout registration, in the ISO-4217 alpha-3 format
   • signature— the request signature generated after all required parameters have been specified (for more information, see Signature generation and verification).
2. The following parameters required for any payment must be specified: mode (payout), project_id, payment_id, uuid, payment_currency, payment_amount, customer_id, customer_email, signature.
3. To use a token of the payment card that the customer has selected in the web service, specify this token as a value of the account_token parameter.
4. To provide information about the payout sender, specify the following parameters in the request:
   • sender_wallet_id—sender's wallet number
   • sender_first_name—sender's first name
   • sender_last_name—sender's last name
   • sender_country—sender's country code in ISO 3166-1 alpha-2
   • sender_state—the sender's country subdivision code (state, province, region, or territory). The value of this parameter is the second element of a code for a subdivision (in ISO 3166-2), without the two-letter country code and the hyphen-minus used as a separator. For example, ON for the province of Ontario in Canada (with CA-ON being the complete code for the subdivision)
   • sender_city—sender's city
   • sender_address—sender's street address
   • sender_zip—sender’s postal code
5. To provide information about the payout recipient, specify the following parameters in the request:
   • recipient_first_name—recipient's first name
   • recipient_last_name—recipient's last name
   • recipient_country—recipient's country code in ISO 3166-1 alpha-2
   • recipient_state—the recipient’s country subdivision code (state, province, region, or territory). The value of this parameter is the second element of a code for a subdivision (in ISO 3166-2), without the two-letter country code and the hyphen-minus used as a separator. For example, ON for the province of Ontario in Canada (with CA-ON being the complete code for the subdivision)
   • recipient_city—recipient's city
   • recipient_address—recipient's street address

   In the case of payout to a Visa card issued in Canada, the request must contain the payout recipient's address data: the country code (recipient_country), the city (recipient_city), the street address (recipient_address) and, if the recipient's country code is CA or US, the code of the state, province, or territory (recipient_state).

6. To display Payment Page in a required language, you need to additionally specify the language_code parameter. If this parameter is not specified, the payment form is displayed in the language selected automatically (by the browser settings, by the region, or by default—details).
7. To add a description of the payment, you need to specify the payment_description parameter. The value of this parameter is shown to the customer on the page with information about the payout result and is available to the merchant's employees in Dashboard and in callbacks.
8. Additionally, any other parameters supported by Payment Page in the Payout operation mode can be used in requests. The full list of parameters for opening Payment Page is provided in the article Parameters for opening payment form.

Thus, a correct request for payout must include project, payment, and customer identifiers, the identifier from the callback with information about the payout registration, the email address of the customer, signature, payment currency and amount. Along with that, other parameters can be used in requests.

{
   "project_id": "91348",
   "payment_id": "cosmoshop_payout_1323",
   "payment_currency": "EUR",
   "payment_amount": "7000",
   "customer_id": "16061314",
   "customer_email": "p.jeltz@mail.com",  
   "mode": "payout",
   "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5...",
   "signature": "xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB..."

// when processing payment using preselected card:
    "account_token":"959c664ad6045679d71d89caff6c242a0..."

}

Format of callback of payout processing result

The format of callbacks used to communicate the results of processing card payouts is the same as the one described in the Callbacks section.