Bulk payments

Subsection overview

This subsection is designed to perform payments, for example, single and mass payouts or mass refunds, to perform confirmation of withdrawal of the held funds or cancelling of the held funds on the customer bank card, and track the history of requests performed by using the Old Dashboard.

This subsection displays the table with information about requests, filters to the table, and tabs for payments performing.

Figure: Information about performed payments

The table provides information about sent requests: identifiers of payments and batches (payment ID is for single payout, batch ID is for mass payment), the total number of operations in file, as well as the number of operations performed with success or decline status with plus and minus signs, respectively, in parentheses, status and date of request, the name of a file used for mass operation, and the name of a project under which operations are performed.

The status of the request is displayed in the column Status and can be one of the following values:
  • processing—the request awaits to be sent
  • done the request is formed and sent for processing
The information in this section is displayed only for projects that are permitted to the Old Dashboard user account. To create requests in this subsection, it is necessary to:
  • obtain rights to perform payments by using Old Dashboard
  • specify the phone number to which a confirmation code will be sent (see the User Profile section for details),
  • enable two-factor authentication for signing in Old Dashboard (see the Security section for details).

The data in the table is displayed approximately 2 minutes after a payment is initiated.

Single payout

To create and send a single payout request do the following:
  1. Move to the Single payout tab in the right side of the window.
  2. Select the project from the list.
  3. Specify an amount and select a currency from the list, the amount can be integer-valued or with a fractional part separated by dot, for example, 100 or 55.50.
  4. Select the payment method available for payout within the framework of this project, for example, card.
  5. Fill in all the fields on the form so that their values meet the requirements of the API specification according to the chosen payment method. The most commonly used parameters are described below.

    If you click Back, the data entry is reset.

  6. Send the request by clicking Request payout
  7. Ensure that the request is successfully sent by receiving the notification window.

Figure: Single payout sending form on the example of cards

After sending the request, you can track the request processing status in the subsection table, and the payment status in the Payments section.

Mass payment

General information

A bulk payment is a batch of operations that are sent in a specially prepared CSV file. This file is created on the merchant side and contains a set of necessary parameters for each operation.

The available operations within the mass payment are:
  • capture — confirmation of withdrawal of the held funds on the customer card
  • cancel — cancelling of the held funds on the customer card.
  • refund — credit funds to a customer
  • payout — paying out the funds to a customer by using payment instrument credentials
  • payout/token — paying out the funds to a customer by using card token

To prepare the file, you can use the Bulk payment template available for download at the bottom of the tab or here. After downloading the template, you can fill it in any CSV file editor, for example, "MS Excel".

Figure: Example of a filled file

An example of a ready file for payments to customer cards is available at the link.

An example of a filled file for payments to customer by using alternative payment methods is available at the link.

After downloading the file by using Old Dashboard, the ECommPay payment platform checks the validity of the data in the file and performs all specified operations.

Requirements for the uploaded files

Each file used for bulk payments must meet the following requirements:
  • The file format should be CSV and the character encoding should be UTF-8 without BOM (Byte Order Mark string).
  • The file size should not exceed 128 MB.
  • The first row must contain the names of parameters. The order of parameters can be random.
  • The subsequent rows must contain values of target parameters, for optional parameters values may not be specified.
  • The values of the parameters in the file must meet the requirements provided in the table below.
  • If operation parameters are specified in strings (not in table format), parameter values in each row must be separated by a ";" (semicolon) sign, fields without values are separated by semicolons in the same way as the fields with values assuming a situation with two or more ";" characters in a raw, for example:

Mass payment processing

To request a mass payment do the following:
  1. move to the Bulk Payments tab on the right og the window
  2. upload by clicking browse or drag-and-drop a filled CSV file with the list of operations
  3. click Request
  4. Ensure that the request is successfully sent by receiving the notification window.

Figure: Mass payment sending form

After sending the request, you can track the request processing status in the subsection table, and the operations status in the Operations section.

Parameters for mass payments

When filling in data in files, the parameters presented in the table can be used. For more information about the parameters, see the API specification.

Parameter Mandatory Type Description Example
operation_type Yes string The operation type. The available values: capture, cancel, refund, payout, payout/token payout
project_id Yes integer The project identifier, received from ECommPay 35
method Yes string Payment method code through which the payout is performed, the list of codes see in IDs of payment methods supported in Old Dashboard card
payment_id Yes string (minLength: 1; maxLength: 255) ID of the payment, must be unique within project. Any letters, digits, and symbols in UTF-8 encoding 123ID
payment.amount Yes integer (minimum: 1 maximum: 10000000000000) Payment amount in minor currency units (without separator between integer and fractional parts) 1000
payment.currency Yes string Payment currency code in ISO 4217 alpha-3 format EUR
payment.description Yes for refund string (maxLength: 255) Description of payment refund123
account.number No string (maxLength: 100 minLength: 1) Customer account number 1670033323
account.bank_id No integer (minimum: 1) Bank identifier of the customer account in the ECommPay payment platform. The list can be received from the technical documentation or the ECommPay technical support 123
account.customer_name No string (minLength: 1) Full name of the account holder John Johnson
account.branch No string (maxLength: 255) Bank branch name Branch
account.city No string (minimum: 1 maxLength: 255) City of the bank branch location London
account.region_id No integer (minimum:1) Region or state identifier of the bank branch location received from ECommPay 123
card.pan Yes for payout and if card.token is not specified integer (maxLength: 32) The card number of a customer 4242424242424242
card.token Yes for payout and if card.pan is not specified integer (minimum:2019 maximum:9999) Card token, received from ECommPay Z0yTL5shY8ddhpxdQyplRPJYmGV7Kv
card.year Yes for payout integer (minimum:1 maximum:12) The year of expiry of a card 2020
card.month Yes for payout string (maxLength:255) The month of expiry of a card 12
card.card_holder Yes for payout string The name of a card holder John Johnson
customer.id Yes for payout string (maxLength:255) Customer ID in a project 312ID
customer.country Yes for payout string The customer country code in ISO 3166-1 alpha-2 format GB
customer.city Yes for payout string (maxLength:255) The customer city London
customer.state No string (maxLength:255) The region or state of customer billing address West Midlands
customer.zip No string (maxLength:16) The postcode of customer billing address B152SA
customer.street No string The street of customer billing address Edgbaston
customer.first_name Yes for payout string (maxLength:255) The customer first name John
customer.last_name Yes for payout string (maxLength:255) The customer last name Johnson
customer.day_of_birth Yes for payout string The customer day of birth in DD-MM-YYYY format 21-12-1989
customer.phone No string The customer phone number containing from 4 to 24 digits 442072296412
customer.email No string (maxLength:255) The customer email test@gmail.com
customer.ip_address Yes for payout string (maxLength:255) The customer IP address

The list of possible errors

After the system checks the accuracy of the filled data, you receive a message about a successfully processed request or about an error that occurred during the processing. You can also get a list of errors by clicking on the number of operations in the Count column of the table with the list of downloaded files. Possible errors are described below.

Table 1. Common file processing errors
Error message Possible reason
Incorrect file format Incorrect extension or format of the file
Broken file Incorrect encoding or data structure
Payment method is not available (line# number) The payment method is not available
Specified project_id does not belong to specified merchant account The project does not belong to the merchant
Project_id is not numeric (line# number) The project ID is not numeric
Project_id does not exist (line# number) A nonexistent project ID is specified
Payment_id is empty (line# number) The payment ID is not specified
Payment with payment_id already exists (line# number) The payment ID already registered in the payment platform
Amount is empty (line# number) The payment amount is not specified
Incorrect Amount (line# number) Incorrect amount value
Currency is empty (line# number) The payment currency is not specified
Incorrect Currency (line# number) Incorrect currency value
Invalid date The expiry date of the card is not specified or is incorrect
Card.year is in past (line# number) The card has expired or the month value is incorrect
Card.month is in past (line# number) The card has expired or the month value is incorrect