Introduction

Welcome to the E-Gates Payment API!

Through this docs the following variables will be used if format ${VARIABLE_NAME}:

Variable	Meaning	Example
`POS_ID`	Point Of Sale identifier. Used to uniquely identify merchant in API.	`dc728de1-51ef-4ef1-80f7-3b44b07b5667`
`API_KEY`	Key used to merchant for authorization purposes.	`2c2b91a3-9b73-4551-81ac-84e0d0360995`
`API_SECRET`	Secret used to merchant for authorization purposes in API and webhooks signing.	`ktMdTyollYMRkEfvgqbaWmvFiXPy1a80`
`ENDPOINTS_KEY`	Endpoints authorization key. Used to access the API.	`AIzaSyBiVfwG--8qIr4GOGuC2-XYoulwqqAAAAA`

See Authentication for details.

Definitions

Term	Definition
MCC	Merchant Category Code - is a four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides.
3-D Secure	3-D Secure - is an additional authentication step for online payments.
ECI	Electronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure

Available payment operations

Payment modes

E-Gates defines two options for processing payments, a.k.a. modes:

hosted - the most popular way to integrate E-Gates. It provides hosted checkout which can be connected to merchant's project. The request define preferred Payment method and include full Product details and customer information. The user interface can be adjust in merchant's styles and host at merchant's domain name.
direct - seamless integration. Let customer enter card data details on merchant's website or pay by card tokens issued by E-Gates.

Primary operations

Depending on merchant business there are different options for accepting payment. a.k.a. methods:

purchase - one-step payment. Charges customer's card for specified amount.
auth - two-step payment. Amount is simply hold on payer's card. For actual charging, complete the transaction with capture method.

Customer may see the same notification message as for purchase. This message is under bank issuer control.

credit - payout operation. Replenishes customer's card with specified amount from merchant's balance.
p2p - money transfer from one card to another.

Retrying credit or p2p operations are allowed only after receiving final unsuccessful status. In case of timeout you should use status polling api to find out current status of operation.

lookup - card authorization method that means blocking of the amount up to 1 usd for up to 30 days to verify the validity of the client's card. To check card validation you are sending request for card authorization with the amount. To verify that the card belongs to the client, a dynamic authorization code is used.

Secondary operations

Secondary operations are bound to primary.

refund - return full or partial amount of captured transaction.

capture - confirm hold. Optionally takes an alternative amount (less than hold amount) to be captured.
void - release hold. Declines previously made authorization.

Controlling 3D-Secure flow

3-D Secure could be controlled by order_3ds_bypass parameter in API. Valid parameters are:

supported (default) - depends on card 3-D Secure support.
always - transaction will be declined if card does not support 3-D Secure.
never - transaction will be made without 3-D Secure involving.

By default, merchants are allowed to use supported and always only. If merchant needs never flow, please contact integration team.

Order Id uniqueness

This uniqueness doesn’t depend on status of previous transaction done using this order_id. For example, if previous transaction was a failure, when attempt to create new reusing same order_id will be rejected anyway. This also means that for same pos_id secondary operations should reuse order_id of corresponding primary operation.

API

API URL

In order to test whether host is reachable use https://paygates.e-gates.io/health endpoint:

$ curl https://paygates.e-gates.io/health

OK # Expected response

All requests to E-Gates API should be sent to https://paygates.e-gates.io host in JSON format.

Authentication

To test whether credentials and headers are correct, use the following request:

$ curl "https://paygates.e-gates.io/api/v1/pos/${POS_ID}/orders/0" \
       -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
       -H "X-API-KEY: ${ENDPOINTS_KEY}"

Expected response

[]

E-Gates uses HTTP headers for authentication in the following format:

Header field name	Value	Example
`X-API-AUTH`	`CPAY ${API_KEY}:${API_SECRET}`	`X-API-AUTH: CPAY 2c2b91a3-9b73-4551-81ac-84e0d0360995:ktMdTyollYMRkEfvgqbaWmvFiXPy1a80`
`X-API-KEY`	`${ENDPOINTS_KEY}`	`X-API-KEY: AIzaSyBiVfwG--8qIr4GOGuC2-XYoulwqqAAAAA`

E-Gates expects these headers in all API requests sent to the server for both GET and POST requests.

If these headers were not passed or contain incorrect values then 401 Unauthorized will be returned

Request signing

Requests to E-Gates could be optionally signed, it is recommended. In this case, header X-API-AUTH should be replaced with appropriate signing algorithm. See examples below.

HMAC-SHA1 (recommended)

OpenSSL HMAC-SHA1 signing example:

SECRET=changeme # replace with ${API_SECRET}
DATA='{"name":"Joe","age":20}' # replace with raw request
SIGNATURE=$(echo -n "$DATA" | openssl sha1 -hmac "$SECRET")
echo "$SIGNATURE"
# Expected signature
48731878acbb41e6ee70eac5f1e6f8b8031f9484

Recommended way to sign requests is HMAC-SHA1 algorithm. See an example on the right.

Authentication header: X-API-AUTH: CPAY-HMAC ${API_KEY}:${SIGNATURE}

SHA1

OpenSSL SHA1 signing example:

SECRET=changeme # replace with ${API_SECRET}
DATA='{"name":"Joe","age":20}' # replace with raw request
SIGNATURE=$(echo -n "$SECRET$DATA$SECRET" | openssl sha1)
echo "$SIGNATURE"
# Expected signature
8c8a2929897286196bb906216379f84c9ec17573

If merchant's system has no support for HMAC signing, requests could be simply signed with SHA1 algorithm. See an example on the right.

Authentication header: X-API-AUTH: CPAY-SHA1 ${API_KEY}:${SIGNATURE}

Data types

Type name	Represented as	Values	Example
`UUID`	String(36)		`"a8d80c86-0c7b-41bc-b63d-1e78f80edcd9"`
`TIMESTAMP`	String(23)		`"2020-10-10T10:10:22.100"`
`MODE`	String(≤32)	`direct`, `hosted`	Payment modes
`METHOD`	String(≤255)	`purchase`, `capture`, `auth`, `void`	Payment methods
`URL`	String(≤2048)		`https://examle.com/some/path?with=query`
`IP`	String(7-45)		`"8.8.8.8"` (IPv4), `"FE80::0202:B3FF:FE1E:8329"` (IPv6)
`GW_ID`	String(≤1024)		`4212523:GssqUUQa`
`BILLING_ID`	String(≤1024)		`123125124`
`CURRENCY`	String(3)		`"UAH"`, `"USD"`, `"EUR"`
`STATUS`	String(≤32)		`"success"` (Transaction status)
`STATUS_CODE`	String(4)		`"1000"` (E-Gates payment status code)
`STATUS_DESCRIPTION`	String(≤1024)		`"Transaction is successful."` (E-Gates payment status code description)
`ECI`	String(≤2)		`"7"` (ECI )
`MCC`	String(≤5)		`"3455"` (MCC )
`CC_NUMBER`	String(13-20)		`"4242424242424242"`
`CC_MASK`	String(13-20)		`"424242******4242"`
`CC_TOKEN`	String(≤255)		`"SDJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZq"` (E-Gates tokens )

Products

Example of product entity:

{
  "id": "1",
  "url": "https://example.com/products/tv",
  "category": "TV",
  "name": "Brand new TV",
  "description": "Brand new TV with awesome screen",
  "amount": 6600,
  "currency": "UAH",
  "price_type": "VAT",
  "vat": 6600,
  "qty": 1,
  "payload": "ref_no=1231; discount=false"
}

For each payment you can optionally pass array of products that are being paid for.

Parameter definitions (all parameters are optional):

Parameter	Type	Description
`id`	String	Product identifier in merchant's system
`url`	String	Product URL
`category`	String	Product category
`name`	String	Product name
`description`	String	Product description
`amount`	Number	Product price (does not influence total payment amount)
`currency`	String	Product price currency
`price_type`	String	Either VAT or NET
`vat`	Number	VAT price for the product
`qty`	Number	Product quantity
`payload`	String	Field for custom data. Max 4000 symbols.

Browser fingerprint

For each direct or p2p payment you can optionally pass browser fingerprint data.

Example of browser fingerprint:

"browser_fingerprint": {
  "browserColorDepth":       "24",
  "browserScreenHeight":     "860",
  "browserScreenWidth":      "1600",
  "browserJavaEnabled":      "false",
  "browserLanguage":         "uk-UA",
  "browserTimeZone":         "Europe/Kiev",
  "browserTimeZoneOffset":   "-120",
  "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
  "browserIpAddress":        "127.0.0.1",
  "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
}

Allowed properties for browser fingerprint

Parameter	Type	Description
`browserColorDepth`	String	Browser's color depth
`browserScreenHeight`	String	Browser's screen height
`browserScreenWidth`	String	Browser's screen width
`browserJavaEnabled`	String	Browser's java enabled
`browserLanguage`	String	Browser's language
`browserTimeZone`	String	Browser's timezone
`browserTimeZoneOffset`	String	Browser's timezone offset
`browserAcceptHeader`	String	Browser's accept header
`browserIpAddress`	String	Browser's IP address
`browserUserAgent`	String	Browser's user agent

API statuses

status field can contain the following values:

Status	Description
`init`	Transaction was created, but processing has not been started.
`pending`	Transaction is being processed.
`success`	Transaction is successful.
`failure`	Unsuccessful transaction.

Create hosted payment

HTTP method: POST

Request parameters

Request example:

$ curl -i "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

Successful response with 303 HTTP status has Location header where customer should be redirected to proceed with payment:

HTTP/2 303
# .. other headers
Location: https://checkout.e-gates.io/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`hosted`
`method`	METHOD	✅	Payment method (`auth` or `purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`products`	Array[Product]		Array of products to be paid, empty array can be specified
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String	✅	Customer email
`customer_phone`	String	✅	Customer phone
`customer_ip`	String		Customer IP address
`customer_lang`	String		Checkout language. Supported values.
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL

customer_lang supported values: "EN", "ES", "PL", "AR", "AZ", "BG", "CS", "DA", "DE", "EL", "FA", "FI", "FR", "HE", "HI", "HR", "HU", "IT", "JA", "KO", "NL", "NO", "PT", "PT_BR", "RO", "SK", "SL", "SR", "Ї", "SV", "TH", "TR", "UK", "ZH", "ZH_HA"

Create QR code payment

HTTP method: POST

Request parameters

Request example:

$ curl -i "https://paygates.e-gates.io/api/v1/payment?qr=true" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

Response example:

{
  "qr_link": "https://checkout.e-gates.io/api/v1/checkout/baf1592f-d7e8-4c28-9b86-43499bc54904/qr"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`hosted`
`method`	METHOD	✅	Payment method (`auth` or `purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`products`	Array[Product]		Array of products to be paid, empty array can be specified
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String	✅	Customer email
`customer_phone`	String	✅	Customer phone
`customer_ip`	String		Customer IP address
`customer_lang`	String		Checkout language. Supported values.
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL

Direct payments with card data

PCI-DSS certification is required in order to use direct mode.

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`auth` or `purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`cc_number`	CC_NUMBER	✅	Card number
`exp_month`	Number	✅	Card expiration month field
`exp_year`	Number	✅	Card expiration year field
`card_cvv`	String	✅	Card CVV
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String	✅	Customer email
`customer_phone`	String	✅	Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for merchant custom data. Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
`customer_referrer`	URL		Page customer is redirected from.

Response parameters

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String(≤256)	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	Payment method (`auth` or `purchase`)
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String(≤2048)	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`user_action_url`	URL	If `user_action_required` is `true` then user should be redirected to this URL
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`cc_mask`	CC_MASK	Card number mask
`cc_token`	CC_TOKEN	E-Gates card token generated for this card
`cc_token_expiration`	String	Token expiration timestamp
`customer_id`	String	Customer identifier in merchant's system
`customer_ip`	String	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String	Field for custom data
`bank_short_name`	String	Bank short name.

Direct payments using Privat24

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat24",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`auth` or `purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`payway`	String	✅	Optional payway. Use "privat24" for processing direct payments through Privat24
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for merchant custom data. Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL

Response parameters

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "privat24",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	Payment method (`auth` or `purchase`)
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`user_action_url`	URL	If `user_action_required` is `true` then user should be redirected to this URL
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`payway`	String	Optional payway. Use "privat24" for processing direct payments through Privat24
`customer_id`	String	Customer identifier in merchant's system
`customer_ip`	String	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data
`bank_short_name`	String	Bank short name.

Direct payments using Privat Payment by Parts

Payment by Parts from Privat is a cost-effective loan, given to a customer according to a credit limit set in case of payment for a product/service in trade and service enterprises and/or online stores. Could be paid only by Privat bank card. Details are here: Details are here: https://privatbank.ua/kredity/oplata-chastyami

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           300,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat_payparts",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties":       {
        "part_counts": 2
      },
      "products":         [
        {
          "name"    : "Apple",
          "amount"  : 100,
          "currency": UAH,
          "qty"     : 2
        },
        {
          "name"    : "Pineapple",
          "amount"  : 100,
          "currency": UAH,
          "qty"     : 1
        }
      ]
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`auth` or `purchase`)
`amount`	Number	✅	Transaction amount (must be > 300 UAH)
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`payway`	String	✅	Optional payway. Use "privat_payparts" for processing direct payments through Privat Payment by Parts
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for merchant custom data. Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL
`properties.parts_count`	String		The number of parts into which the payment amount is divided (must be > 1 and <= 25)

Response parameters

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               300,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "privat_payparts",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	Payment method (`auth` or `purchase`)
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`user_action_url`	URL	If `user_action_required` is `true` then user should be redirected to this URL
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`payway`	String	Optional payway. Use "privat_payparts" for processing direct payments through Privat Payment by Parts
`customer_id`	String	Customer identifier in merchant's system
`customer_ip`	String	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data
`bank_short_name`	String	Bank short name.

Direct payments using E-Gates tokens

HTTP method: POST

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_token":         "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Request parameters

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`auth` or `purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`cc_token`	CC_TOKEN	✅	E-Gates card token, obtained from previous payments
`order_3ds_bypass`	String	✅	3-D Secure flow option
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String	✅	Customer email
`customer_phone`	String	✅	Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
`customer_referrer`	URL		Page customer is redirected from.

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "rnn":                  "014681438245",
  "authcode":             "442413",
  "bank_short_name":      "Bank name"
}

Response parameters

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String(≤256)	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	Payment method (`auth` or `purchase`)
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String(≤2048)	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`user_action_url`	URL	If `user_action_required` is `true` then user should be redirected to this URL
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`cc_mask`	CC_MASK	Card number mask
`cc_token`	CC_TOKEN	E-Gates card token generated for this card
`cc_token_expiration`	TIMESTAMP	Token expiration timestamp
`customer_id`	String	Customer identifier in merchant's system
`customer_ip`	IP	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data.
`rnn`	String	Transaction unique bank identifier
`authcode`	String	Transaction authentication code
`bank_short_name`	String	Bank short name

P2P payments

HTTP method: POST

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "p2p",
      "amount":              1,
      "currency":            "UAH",
      "description":         "P2P description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_number":           "4242424242424242",
      "exp_month":           2,
      "exp_year":            24,
      "card_cvv":            "111",
      "recipient_cc_number": "5555555555554444",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true",
      "external_fee":        0.05,
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Request parameters

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	`p2p`
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of transfer
`cc_number`	CC_NUMBER	✅	Card number
`exp_month`	Number	✅	Card expiration month field
`exp_year`	Number	✅	Card expiration year field
`card_cvv`	String	✅	Card CVV
`recipient_cc_number`	String	✅	Recipient's card number
`order_3ds_bypass`	String	✅	3-D Secure flow option
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL
`external_fee`	Number		Transaction external fee. Note: usage of the parameter requires an approval
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "p2p",
  "amount":               1,
  "currency":             "UAH",
  "description":          "P2P description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}

Response parameters

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String(≤256)	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`p2p`
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String(≤2048)	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	String	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`user_action_url`	URL	If `user_action_required` is `true` then user should be redirected to this URL
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`cc_mask`	CC_MASK	Card number mask
`cc_token`	CC_TOKEN	E-Gates card token generated for this card
`cc_token_expiration`	TIMESTAMP	Token expiration timestamp
`customer_id`	String	Customer identifier in merchant's system
`customer_ip`	IP	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data.

P2P payments using E-Gates tokens

HTTP method: POST

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "p2p",
      "amount":              1,
      "currency":            "UAH",
      "description":         "P2P description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_token":            "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "recipient_cc_number": "5555555555554444",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true",
      "external_fee":        0.05,
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Request parameters

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	`p2p`
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of transfer
`cc_token`	CC_TOKEN	✅	E-Gates card token, obtained from previous payments
`recipient_cc_token`	CC_TOKEN	✅	E-Gates card token, obtained from previous payments. Note: you can use recipient_cc_number instead
`order_3ds_bypass`	String	✅	3-D Secure flow option
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL
`external_fee`	Number		Transaction external fee. Note: usage of the parameter requires an approval
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "p2p",
  "amount":               1,
  "currency":             "UAH",
  "description":          "P2P description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}

Response parameters

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String(≤256)	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	Mode	`direct`
`method`	Method	`p2p`
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String(≤2048)	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`user_action_url`	URL	If `user_action_required` is `true` then user should be redirected to this URL
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`cc_mask`	CC_MASK	Card number mask
`cc_token`	CC_TOKEN	E-Gates card token generated for this card
`cc_token_expiration`	TIMESTAMP	Token expiration timestamp
`customer_id`	String	Customer identifier in merchant's system
`customer_ip`	String	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country
`result_url`	String	Customer will be redirected to this URL after payment.
`created_at`	String	Timestamp when transaction was created
`processing_time`	String	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data.

Lookup

PCI-DSS certification is required in order to use direct mode.

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "lookup",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct` or `hosted`
`method`	METHOD	✅	Payment method (`lookup`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`cc_number`	CC_NUMBER	✅	Card number
`exp_month`	Number	✅	Card expiration month field
`exp_year`	Number	✅	Card expiration year field
`card_cvv`	String	✅	Card CVV
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for merchant custom data. Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL

Response parameters

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "lookup",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String(≤256)	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	Payment method (`lookup`)
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String(≤2048)	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`user_action_url`	URL	If `user_action_required` is `true` then user should be redirected to this URL
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`cc_mask`	CC_MASK	Card number mask
`cc_token`	CC_TOKEN	E-Gates card token generated for this card
`cc_token_expiration`	String	Token expiration timestamp
`customer_id`	String	Customer identifier in merchant's system
`customer_ip`	String	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String	Field for custom data.

Credit payments

HTTP method: POST

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "credit",
      "amount":              1,
      "currency":            "UAH",
      "description":         "Credit description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_number":           "4242424242424242",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true"
    }'

Request parameters

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	`credit`
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of transfer
`cc_number`	CC_NUMBER	✅	Recipient's card number
`order_3ds_bypass`	String	✅	3-D Secure flow option
`customer_id`	String		Customer's identifier in merchant's system
`customer_fname`	String		Customer's first name
`customer_lname`	String		Customer's last name
`customer_email`	String		Customer's email
`customer_phone`	String		Customer's phone
`customer_ip`	String	✅	Customer's IP address
`customer_country`	String		Customer's country (ISO_3166-2)
`customer_city`	String		Customer's city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL
`properties`	JSON		Additional specific parameters for integrations

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "credit",
  "amount":               1,
  "currency":             "UAH",
  "description":          "P2P description",
  "status":               "success",
  "status_code":          "1000",
  "status_description":   "Transaction is successful.",
  "user_action_required": false,
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "customer_city":        "Ivano-Frankivsk",
  "customer_birthday":    "1999-04-02",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "properties": {
     "recipient_first_name":"Petro",
     "recipient_last_name":"Petrenko",
     "recipient_middle_name":"Petrovych",
     "recipient_doc_number":"1234567890",
     "recipient_doc_issue_date":"2015-08-12",
     "recipient_doc_issued_by":"Kyiv RV UMVS",
     "recipient_phone":"380999999999",
     "recipient_birth_date":"2000-01-01",
     "recipient_birth_place":"Kyiv",
     "recipient_country":"UA",
     "recipient_city":"Kyiv",
     "recipient_address":"Kyiv City, Akademika Yangelia St. 18/1, ap. 309",
     "recipient_postcode":"03056",
     "wallet_number":"12345678900987"
  }
}

Response parameters

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String(≤256)	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`credit`
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String(≤2048)	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	String	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`cc_mask`	CC_MASK	Card number mask
`cc_token`	CC_TOKEN	E-Gates card token generated for this card
`cc_token_expiration`	TIMESTAMP	Token expiration timestamp
`customer_id`	String	Customer's identifier in merchant's system
`customer_ip`	IP	Customer's IP address
`customer_fname`	String	Customer's first name
`customer_lname`	String	Customer's last name
`customer_email`	String	Customer's email
`customer_phone`	String	Customer's phone
`customer_country`	String	Customer's country (ISO_3166-2)
`customer_city`	String	Customer's city
`customer_birthday`	Date	Customer's birthday
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data.
`properties`	JSON	Additional specific parameters for integrations

Allowed properties for credit payment request/response

Parameter	Type	Description
`recipient_first_name`	String	Recipient's first name
`recipient_middle_name`	String	Recipient's middle name
`recipient_last_name`	String	Recipient's last name
`recipient_doc_number`	String	Recipient's document number
`recipient_doc_issue_date`	Date	Recipient's document issue date (format: yyyy-MM-dd)
`recipient_doc_issued_by`	String	Recipient's place that issued his/her document
`recipient_phone`	String	Recipient's phone
`recipient_birth_date`	Date	Recipient's birth date (format: yyyy-MM-dd)
`recipient_birth_place`	String	Recipient's birth place
`recipient_country`	String	Recipient's citizenship (ISO_3166-2)
`recipient_city`	String	Recipient's city
`recipient_address`	String	Recipient's address
`recipient_postcode`	String	Recipient's postcode
`wallet_number`	String	Wallet number

Credit payments using E-Gates tokens

HTTP method: POST

Request example:

$ curl "https://paygates.e-gates.io/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "credit",
      "amount":              1,
      "currency":            "UAH",
      "description":         "Credit description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_token":            "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true"
    }'

Request parameters

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	`credit`
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of transfer
`cc_token`	CC_TOKEN	✅	E-Gates card token, obtained from previous payments
`order_3ds_bypass`	String	✅	3-D Secure flow option
`customer_id`	String		Customer's identifier in merchant's system
`customer_fname`	String		Customer's first name
`customer_lname`	String		Customer's last name
`customer_email`	String		Customer's email
`customer_phone`	String		Customer's phone
`customer_ip`	String	✅	Customer's IP address
`customer_country`	String		Customer's country (ISO_3166-2)
`customer_city`	String		Customer's city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL
`properties`	JSON		Additional specific parameters for integrations

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "credit",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Credit description",
  "status":               "success",
  "status_code":          "1000",
  "status_description":   "Transaction is successful.",
  "user_action_required": false,
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "customer_city":        "Ivano-Frankivsk",
  "customer_birthday":    "1999-04-02",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "properties": {
     "recipient_first_name":"Petro",
     "recipient_last_name":"Petrenko",
     "recipient_middle_name":"Petrovych",
     "recipient_doc_number":"1234567890",
     "recipient_doc_issue_date":"2015-08-12",
     "recipient_doc_issued_by":"Kyiv RV UMVS",
     "recipient_phone":"380999999999",
     "recipient_birth_date":"2000-01-01",
     "recipient_birth_place":"Kyiv",
     "recipient_country":"UA",
     "recipient_city":"Kyiv",
     "recipient_address":"Kyiv City, Akademika Yangelia St. 18/1, ap. 309",
     "recipient_postcode":"03056",
     "wallet_number":"12345678900987"
  }
}

Response parameters

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String(≤256)	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	Mode	`direct`
`method`	Method	`credit`
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String(≤2048)	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`cc_mask`	CC_MASK	Card number mask
`cc_token`	CC_TOKEN	E-Gates card token generated for this card
`cc_token_expiration`	TIMESTAMP	Token expiration timestamp
`customer_id`	String	Customer's identifier in merchant's system
`customer_ip`	String	Customer's IP address
`customer_fname`	String	Customer's first name
`customer_lname`	String	Customer's last name
`customer_email`	String	Customer's email
`customer_phone`	String	Customer's phone
`customer_country`	String	Customer's country (ISO_3166-2)
`customer_city`	String	Customer's city
`customer_birthday`	Date	Customer's birthday
`result_url`	String	Customer will be redirected to this URL after payment.
`created_at`	String	Timestamp when transaction was created
`processing_time`	String	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data.
`properties`	JSON	Additional specific parameters for integrations

Allowed properties for credit payment using E-Gates tokens request/response

Parameter	Type	Description
`recipient_first_name`	String	Recipient's first name
`recipient_middle_name`	String	Recipient's middle name
`recipient_last_name`	String	Recipient's last name
`recipient_doc_number`	String	Recipient's document number
`recipient_doc_issue_date`	Date	Recipient's document issue date (format: yyyy-MM-dd)
`recipient_doc_issued_by`	String	Recipient's place that issued his/her document
`recipient_phone`	String	Recipient's phone
`recipient_birth_date`	Date	Recipient's birth date (format: yyyy-MM-dd)
`recipient_birth_place`	String	Recipient's birth place
`recipient_country`	String	Recipient's citizenship (ISO_3166-2)
`recipient_city`	String	Recipient's city
`recipient_address`	String	Recipient's address
`recipient_postcode`	String	Recipient's postcode
`wallet_number`	String	Wallet number

Capture

Capture could be called only for authorizations with success status.

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/capture" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`comment`	String		Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates capture identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`capture`
`amount`	Number	Actual captured amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`fee`	Object	Amount and currency of commission
`comment`	String	Capture comment

Partial capture

Capture could be called only for authorizations with success status.

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/capture" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "charge_amount":  80,
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`charge_amount`	Number	✅	Optional amount to be captured
`comment`	String		Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates capture identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`capture`
`amount`	Number	Actual captured amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`fee`	Object	Amount and currency of commission
`comment`	String	Capture comment

Void

Void could be called only for authorizations with success status.

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/void" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be voided (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`comment`	String		Void comment. Can be used for describing reasons of void or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "void",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1009",
  "status_description":  "Reverse successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates void identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`void`
`amount`	Number	Actual void amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`fee`	Object	Amount and currency of commission
`comment`	String	Void comment

Refund

Refund could be called only for transactions with success status (authorizations should be captured).

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/refund" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be refunded (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`comment`	String		Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates refund identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`refund`
`amount`	Number	Actual refund amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`fee`	Object	Amount and currency of commission
`comment`	String	Refund comment

Partial refund

Refund could be called only for transactions with success status (authorizations should be captured).

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/refund" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "refund_amount":  80,
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be refunded (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`refund_amount`	Number	✅	Amount to be refunded
`comment`	String		Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates refund identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`refund`
`amount`	Number	Actual refund amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`fee`	Object	Amount and currency of commission
`comment`	String	Refund comment

P2P Credit

P2P Credit could be called only for transactions with success status (purchase or captured authorization).

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/p2p-credit" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "description":    "description_1",
      "cc_number":      "4242424242424242",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/p2p-credit"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be credited (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`description`	CURRENCY		Currency of original order
`cc_number`	CC_NUMBER	✅	Card number
`comment`	String		P2p comment. Can be used for describing reasons of p2p or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "credit",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:15.200",
  "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b"
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates refund identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`credit`
`amount`	Number	Actual p2p credit amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_at`	TIMESTAMP	Timestamp when transaction was updated last time
`registry_ref_no`	String	Gateway transaction identifier
`fee`	Object	Amount and currency of commission
`comment`	String	P2p comment

P2P Credit using E-Gates tokens

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/p2p-credit" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "description":    "description_1",
      "cc_token":       "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/p2p-credit"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be credited (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`description`	CURRENCY		Currency of original order
`cc_token`	CC_TOKEN	✅	E-Gates card token generated for this card
`comment`	String		P2p comment. Can be used for describing reasons of p2p or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "credit",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:15.200",
  "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b"
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates refund identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`gateio`)
`mode`	MODE	`direct`
`method`	METHOD	`credit`
`amount`	Number	Actual p2p credit amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	gateio description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_at`	TIMESTAMP	Timestamp when transaction was updated last time
`registry_ref_no`	String	Gateway transaction identifier
`fee`	Object	Amount and currency of commission
`comment`	String	P2p comment

Partial P2P Credit

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/p2p-credit" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "credit_amount":  25,
      "description":    "description_1",
      "cc_number":      "4242424242424242",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/p2p-credit"
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be credited (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`credit_amount`	Number	✅	Amount to be credited
`description`	CURRENCY		Currency of original order
`cc_number`	CC_NUMBER	✅	Card number
`comment`	String		P2p comment. Can be used for describing reasons of p2p or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "credit",
  "amount":              25,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:15.200",
  "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b"
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates refund identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`credit`
`amount`	Number	Actual p2p credit amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_at`	TIMESTAMP	Timestamp when transaction was updated last time
`registry_ref_no`	String	Gateway transaction identifier
`fee`	Object	Amount and currency of commission
`comment`	String	P2p comment

Get order transactions

Request example:

$ curl "https://paygates.e-gates.io/api/v1/pos/${POS_ID}/orders/${ORDER_ID}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Returns all transactions that are associated with order.

HTTP method: GET

Path parameters

Parameter	Type	Required	Description
`POS_ID`	String	✅	Merchant's identifier (`POS_ID`)
`ORDER_ID`	String	✅	Merchant's order identifier

Response example:

[
  {
    "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
    "order_id":            "111999991",
    "gateway_order_id":    "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
    "billing_order_id":    "123",
    "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
    "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
    "mode":                "direct",
    "method":              "auth",
    "amount":              0.28,
    "currency":            "UAH",
    "payway":              "privat24",
    "eci":                 "7",
    "status":              "success",
    "status_code":         "1000",
    "status_description":  "Transaction is successful.",
    "cc_mask":             "424242******4242",
    "cc_token":            "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
    "cc_token_expiration": "2020-10-10T10:10:22",
    "customer_id":         "123",
    "customer_phone":      "+380999999999",
    "created_at":          "2018-10-10T10:10:10.100",
    "processing_time":     "2018-10-10T10:10:22.100",
    "payload":             "",
    "bank_short_name":     "Bank name"
  },
  {
    "operation_id":          "edf7605c-99a8-43be-a1a5-2e96ebac8512",
    "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
    "order_id":              "123",
    "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
    "pos_id":                "6eb070d5-7fbe-1176-9488-c152b60dd346",
    "mode":                  "direct",
    "method":                "capture",
    "amount":                100,
    "currency":              "UAH",
    "status":                "success",
    "status_code":         "1000",
    "status_description":  "Transaction is successful.",
    "created_at":          "2018-10-10T10:11:11.100",
    "processing_time":     "2018-10-10T10:11:12.000"
  }
]

Response structure

Response contains an Array of transactions associated with merchant's order_id.

Get transactions for period

Request example:

$ curl "https://paygates.e-gates.io/api/v1/pos/${POS_ID}/transactions?startDate=${startDate}&enddate=${enddate}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Returns all transactions for specified period.

HTTP method: GET

Path parameters

Parameter	Type	Required	Description
`POS_ID`	UUID	✅	Merchant's identifier (`POS_ID`)

Query parameters

Parameter	Type	Required	Description
`startDate`	Number	✅	Time from - UNIX timestamp
`enddate`	Number	✅	Time to - UNIX timestamp

Response contains an Array of transactions for specified period.

Get transactions in JSON format

Request example:

$ curl --location --request POST 'https://paygates.e-gates.io/streaming-report/start' \
--header 'X-API-Auth:CPAY 28e957dc-aff7-4575-bd0f-739ec9bc77ee:UnE2Tmc4N0FnVm1JMmxHcGRIdmJ4aHZq' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "064ec3f8-8abb-414b-9eb3-49d977213967",
    "start_date": "2022-09-01T12:00:03.007+00:00",
    "end_date": "2022-09-30T23:58:03.007+00:00",
    "statuses": [ "success", "pending", "failure", "init" ],
    "methods": [
        "purchase",
        "auth",
        "capture",
        "void",
        "p2p",
        "credit",
        "lookup",
        "refund",
        "dispute"
        ],
    "transaction_details": [
       "projectId",
       "orderId",
       "paymentId",
       "amount",
       "currency",
       "method",
       "status",
       "dateTime",
       "cardMask",
       "payway",
       "entityName",
       "projectName",
       "originalAmount",
       "exchangeAmount",
       "exchangeCurrency",
       "exchangeRate",
       "tokenizationKind",
       "authCode",
       "rrnCode",
       "description",
       "payload",
       "customerFee",
       "merchantFee",
       "paymentSystem",
       "recipientCardMask"
    ]
}'

GET Report ID

First, you need to send a request to generate a report that will contain transactions that can be filtered by the following parameters:

Parameter	Required	Description
`project_id`	✅	Merchant's identifier (`POS_ID`)
`start_date`	✅	The start date of the period for which the data is required
`end_date`	✅	Period end date. The maximum period is 31 days
`statuses`		Array of Transaction status
`methods`		Payment methods (`auth`, `purchase`, `capture`, `void`, `p2p`, `credit`, `lookup`, `refund`, `dispute`, `recurrent`)
`transaction_details`		Array field with the parameters that are received for each of the transactions in report

List of transaction details parameters

Additionally, you can specify a list of parameters in the array transaction_details array that you want to receive for each of the transactions in this report. List of available options:

Parameter	Default	Description
`orderId`	✅	Merchant's order identifier to be captured
`paymentId`	✅	E-Gates payment identifier of primary operation
`amount`	✅	Transaction amount with fees applied
`currency`	✅	Transaction currency
`method`	✅	Payment methods
`status`	✅	Transaction status
`dateTime`	✅	Transaction date
`cardMask`	✅	Сard mask
`payway`	✅	Payway name
`customerFee`	✅	Customer fee
`merchantFee`	✅	Merchant fee
`entityName`		Entity name
`projectName`		Project name
`originalAmount`		Transaction amount with no fees applied
`exchangeAmount`		Exchange amount
`exchangeCurrency`		Exchange currency
`exchangeRate`		Exchange rate
`tokenizationKind`		Tokenization kind
`authCode`		Transaction authentication code
`rrnCode`		RRN code
`description`		Transaction description
`payload`		Field for custom data
`paymentSystem`		Payment system
`recipientCardMask`		Recipient's card mask
`reserveAmount`		Rolling reserve amount
`receiverName`		Name of sub merchant in split transaction
`receiverAmount`		Amount paid to sub merchant in split transaction
`receiverFee`		Fee amount paid by sub merchant in split transaction

If you does not set transaction_details with a list of parameters, you will receive those marked default.

Response example:

{"report_id":"57e79df2-b374-4998-9b0e-ac7848760bed","count":384}

Example of response body returned in case of report is not ready. Code 202:

{
  "message": "Report not ready",
  "code": "report_not_ready"
}

Response parameters

Parameter	Description
`report_id`	JSON file identifier
`count`	number of records (transactions)

Get JSON by report_id

Request example:

$ curl --location --request GET 'https://paygates.e-gates.io/streaming-report/fetch/57e79df2-b374-4998-9b0e-ac7848760bed'
--header 'X-API-Auth:CPAY 28e957dc-aff7-4575-bd0f-739ec9bc77ee:UnE2Tmc4N0FnVm1JMmxHcGRIdmJ4aHZq'

To get a list of all transactions (the number of which is specified in count), you need to send a request with a specific report_id.

Response example:

{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213999","orderId":"1456649508235","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb58","amount":"3","currency":"UAH","method":"void","status":"success","dateTime":1662033684016,"cardMask":"414141******2284","payway":"cc","entityName":"","projectName":"Project","originalAmount":"3","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"description","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}
{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213988","orderId":"1456649508236","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb51","amount":"2","currency":"UAH","method":"auth","status":"success","dateTime":1662033684916,"cardMask":"537541******2284","payway":"cc","entityName":"","projectName":"Project","originalAmount":"2","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"description","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}
{"projectId":"064ec3f8-8abb-414b-9eb2-49d977213967","orderId":"1456649508238","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb50","amount":"1","currency":"UAH","method":"purchase","status":"success","dateTime":1662033680916,"cardMask":"537541******1184","payway":"cc","entityName":"","projectName":"Test Project","originalAmount":"1","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"test qa","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}

The response will contain JSON with the number of records equal to count. Each record will have the set of parameters that was specified when creating the report.

Payment operation info

$ curl "https://paygates.e-gates.io/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/${OPERATION}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Returns specific operation for this ${ORDER_ID}.

HTTP method: GET

Parameter	Type	Required	Description
`POS_ID`	UUID	✅	Merchant's identifier (`POS_ID`)
`ORDER_ID`	String	✅	Merchant's order identifier
`OPERATION`	String	✅	Payment method, e.g. `purchase`, `void`, etc.

Payload

Example of Base64-encoded payload

{
  "...": "...",
  "payload": "eyJ0aGlzIGlzIjogInBhc2hhbG9jaGthIn0K"
}

Most of requests have optional payload field. It can contain custom merchant data. Maximum length to be passed is 4,000 symbols.

If you would like to store structured data, like JSON or XML, simply encode it with Base64 to avoid JSON-specific symbols in body.

DCC

In cases of payment with DCC response will contain dcc_rates field with exchange rates for current request.

This is applicable only to purchase method (see primary operations for details) and to currencies other than the UAH.

N.B. The terminal must be pre-configured to return exchange rates. To do this, please contact support at support@e-gates.io.

Field	Type	Example	Description
amount	Number	3.5984	Amount of payment in alternative currency
currency	CURRENCY	"USD"	Alternative currency
rate	Number	27.7905	Conversion rate
commission	Number	0.0	Commission on payment in alternative currency

{
  "dcc_rates": [{
      "amount":     3.5984,
      "rate":       27.7905,
      "commission": 0.0,
      "currency":   "USD"
  }]
}

Split payment

Split payment is a single charge of the whole amount from the payer’s card and payouts for multiple merchants.

Hosted split payment

See more information about hosted payments

HTTP method: POST

Request parameters

Request example:

$ curl -i "https://paygates.e-gates.io/api/v1/split/purchase" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "purchase",
      "amount":           100,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]  
    }'

Successful response with 303 HTTP status has Location header where customer should be redirected to proceed with payment:

HTTP/2 303
# .. other headers
Location: https://checkout.e-gates.io/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`hosted`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`products`	Array[Product]		Array of products to be paid, empty array can be specified
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String	✅	Customer email
`customer_phone`	String	✅	Customer phone
`customer_ip`	String		Customer IP address
`customer_lang`	String		Checkout language. Supported values.
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL
`split`	Array[SplitPayment]	✅	Split payment properties

Direct split payment

See more information about direct payments

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/split/purchase" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           100,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      },
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]      
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`cc_number`	CC_NUMBER	✅	Card number
`exp_month`	Number	✅	Card expiration month field
`exp_year`	Number	✅	Card expiration year field
`card_cvv`	String	✅	Card CVV
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String	✅	Customer email
`customer_phone`	String	✅	Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for merchant custom data. Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
`split`	Array[SplitPayment]	✅	Split payment properties

Response parameters

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               100,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

Parameter	Type	Description
`payment_id`	UUID	Unique E-Gates payment identifier
`order_id`	String(≤256)	Unique identifier of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique E-Gates billing identifier
`transaction_id`	UUID	E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	Payment method (`purchase`)
`amount`	Number	Transaction amount
`currency`	CURRENCY	Transaction currency (ISO_4217)
`description`	String(≤2048)	Payment description
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`user_action_url`	URL	If `user_action_required` is `true` then user should be redirected to this URL
`eci`	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
`mcc`	MCC	MCC for this transaction
`options_3ds`	String	3-D Secure flow option
`cc_mask`	CC_MASK	Card number mask
`cc_token`	CC_TOKEN	E-Gates card token generated for this card
`cc_token_expiration`	String	Token expiration timestamp
`customer_id`	String	Customer identifier in merchant's system
`customer_ip`	String	Customer IP address
`customer_fname`	String	Customer first name
`customer_lname`	String	Customer last name
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_country`	String	Customer country
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String	Field for custom data
`bank_short_name`	String	Bank short name.

Capture split payment

Capture could be called only for authorizations with success status.

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/split/capture" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]        
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`comment`	String		Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL
`split`	Array[SplitPayment]	✅	Split payment properties

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates capture identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`capture`
`amount`	Number	Actual captured amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`fee`	Object	Amount and currency of commission
`comment`	String	Capture comment

Refund split payment

Refund could be called only for transactions with success status (authorizations should be captured).

HTTP method: POST

Request parameters

Request example:

$ curl "https://paygates.e-gates.io/api/v1/split/refund" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]      
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`comment`	String		Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL
`split`	Array[SplitPayment]	✅	Split payment properties

Response parameters

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Parameter	Type	Description
`operation_id`	UUID	Unique E-Gates refund identifier
`payment_id`	UUID	E-Gates payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique E-Gates transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`refund`
`amount`	Number	Actual refund amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	E-Gates payment status code
`status_description`	STATUS_DESCRIPTION	E-Gates payment status code description
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`fee`	Object	Amount and currency of commission
`comment`	String	Refund comment

Split payment properties

Parameter	Type	Required	Description
`amount`	Number	✅	Transaction amount
`sub_merchant_id`	UUID	✅	Unique Sub merchant identifier (to get the identifier, please contact support at support@e-gates.io)

Alternative Payment Methods

Regional

Asia

India

Wallet (Digital Wallet)

Pay In only
Supported currency - INR

Pay In

Request Example:

{
    "pos_id":           "$POS_ID",
    "mode":             "direct",
    "amount":           12,
    "Method":           "purchase",
    "currency":         "INR",
    "payway":           "WL",
    "customer_email":   "name@mail.com",
    "customer_phone":   "7259955534",
    "customet_fname":   "John",
    "customer_lname":   "Doe",
    "customer_ip":      "0.0.0.0",
    "order_3ds_bypass": "supported",
    "description":      "Test description for '$ORDER_ID'# payment",
    "order_id":         "$ORDER_ID",
    "server_url":       "https://callback.blackhole.com/callback",
    "result_url":       "https://example.com/result",
    "properties": {
        "mop_type": "102"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`properties.mop_type`	String	✅	type of wallet
`customer_ip`	String		payer’s IP

NetBanking (Digital Wallet)

Pay In and Pay Out
Supported currency - INR

Pay In

Request Example:

{
    "pos_id":             "’$POS_ID’",
    "mode":               "direct",
    "amount":             12,
    "method":             "purchase",
    "currency":           "INR",
    "payway":             "NB",
    "customer_email":     "name@mail.com",
    "customer_phone":     "7259955534",
    "customet_fname":     "John",
    "customer_lname":     "Doe",
    "customer_birthday":  "1990-04-01",
    "customer_city":      "Kale",
    "order_3ds_bypass":   "supported",
    "description":        "Test description for '$ORDER_ID'# payment",
    "order_id":           "$ORDER_ID",
    "server_url":         "https://callback.blackhole.com/callback",
    "result_url":         "https://example.com/result",
    "properties": {
        "mop_type": "1005",
        "address":   "Kale, Gözcü Sk. No:2",
        "post_code": "01323001"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`properties.mop_type`	String	✅	type of wallet
`customer_city`	String	✅	payer’s city
`customer_birthday`	Date	✅	payer’s birthday (format: yyyy-MM-dd)
`properties.address`	String	✅	payer’s address
`properties.post_code`	String	✅	payer’s postcode

Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "amount":              12,
    "method":             "credit",
    "currency":           "INR",
    "payway":             "NB",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_city":      "Kale",
    "customer_birthday": "1990-04-01"
    "customer_phone":     "7259955534"
    "customer_email":     "name@mail.com",
    "order_3ds_bypass":   "supported",
    "description":        "Test description for '$ORDER_ID'# payment",
    "order_id":           "'$ORDER_ID'",
    "server_url":         "https://callback.blackhole.com/callback",
    "result_url":         "https://example.com/result",
    "properties": {
        "bank_account":         "19721080000000",
        "ifsc":                 "HDFC0000000",
        "recipient_phone":      "7259955534",
        "recipient_email":      "name@mail.com",
        "recipient_first_name": "John Doe",
        "state":                "Chennai",
        "post_code":            "12345"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`customer_email`	String	✅	recipient’s email address
`customer_phone`	String	✅	recipient’s phone number
`customer_city`	String	✅	recipient’s city
`customer_birthday`	Date	✅	recipient’s birthday (format: yyyy-MM-dd)
`properties.state`	String	✅	recipient’s regional features
`properties.recipient_email`	String	✅	recipient’s email address This parameter is the alternative to the `customer_email`
`properties.recipient_phone`	String	✅	recipient’s phone number This parameter is the alternative to the `customer_phone`
`properties.recipient_first_name`	String	✅	recipient's first and last name This parameter is the alternative to the `customer_fname` and `customer_lname`
`properties.bank_account`	String	✅	recipient’s account number
`properties.ifsc`	String	✅	recipient’s Indian Financial System Code

UPI (Digital Wallet)

Pay In and Pay Out
Supported currency - INR

Pay In

Request Example:

{
    "pos_id":          "'$POS_ID'",
    "mode":            "direct",
    "amount":          12,
    "method":          "purchase",
    "currency":        "INR",
    "payway":          "UP",
    "order_3ds_bypass": "supported",
    "customer_fname": "John",
    "customer_lname": "Doe",
    "customer_phone": "7259955534",
    "customer_email": "name@mail.com",
    "customer_ip":    "1.2.3.4",
    "description":    "Test description for '$ORDER_ID'# payment",
    "order_id":       "'$ORDER_ID'",
    "server_url":     "https://callback.blackhole.com/callback",
    "result_url":     "https://example.com/result",
    "properties": {
        "mop_type":   "507",
        "upi_number": "9971100000@hdfcbank",
        "trusted":    true,
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`customer_ip`	String	✅	payer’s IP
`properties.upi_number`	String	✅	UPI address of the payer
`properties.mop_type`	String	✅	type of wallet
`properties.trusted`	Boolean	✅	whether the trusted payer

Pay Out

Request Example:

{
  "pos_id":                     "'$POS_ID'",
  "mode":                       "direct",
  "method":                     "credit",
  "amount":                     1,      
  "payway":                     "upi",
  "currency":                   "INR",
  "order_id":                   "'$ORDER_ID'",
    "description":              "Description",
    "customer_fname":           "John",
    "customer_lname":           "Doe",
    "customer_email":           "name@mail.com",
    "customer_phone":           "380991111111",
    "customer_ip":              "1.2.3.4",
    "order_3ds_bypass":         "supported",
    "properties": {
        "recipient_address":    "Nizamabad",
        "recipient_email":      "name@mail.com",
        "recipient_first_name": "John Doe",
        "recipient_phone":      "380991111111",
        "upi_number":           "name@hdfcbank",
        "trusted":              true
    },
    "server_url":               "http://callback-stub:9000/consume",
    "result_url":               "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	gate.io app identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`customer_email`	String	✅	recipient’s email address
`customer_phone`	String	✅	recipient’s phone number
`customer_ip`	String	✅	recipient’s IP
`properties.recipient_address`	String	✅	recipient’s address
`properties.recipient_email`	String	✅	recipient’s email address This parameter is the alternative to the `customer_email`
`properties.recipient_first_name`	String	✅	recipient's first and last name This parameter is the alternative to the `customer_fname` and `customer_lname`
`properties.recipient_phone`	String	✅	recipient’s phone number <br/< This parameter is the alternative to the `customer_phone`
`properties.upi_number`	String	✅	UPI address of the payer
`properties.trusted`	Boolean	✅	whether the trusted payer

Paytm (Digital Wallet)

Pay In and Pay Out
Supported currency - INR

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "paytm",
    "currency":         "INR",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_email":   "name@mail.com",
    "customer_phone":   "380991111111",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "trusted": true
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`customer_ip`	String	✅	payer’s IP
`properties.trusted`	Boolean	✅	whether the trusted payer

Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "amount":             1,
    "payway":             "paytm",
    "currency":           "INR",
    "order_id":           "'$ORDER_ID'",
    "description":        "Description",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_email":     "name@mail.com",
    "customer_phone":     "380991111111",
    "customer_ip":        "1.2.3.4",
    "order_3ds_bypass":   "supported",
    "properties": {
        "trusted":        true,
        "account_number": "1234567890"
    },
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`customer_email`	String	✅	recipient’s email address
`customer_phone`	String	✅	recipient’s phone number
`customer_ip`	String	✅	recipient’s IP
`properties.account_number`	String	✅	PayTM wallet or phone number (always 10 digits)
`properties.trusted`	Boolean	✅	whether the trusted payer

IMPS (Digital Wallet)

Pay In and Pay Out
Supported currency - INR

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "imps",
    "currency":         "INR",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_email":   "name@mail.com",
    "customer_phone":   "380991111111",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "trusted":      true
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`customer_ip`	String	✅	payer’s IP
`properties.trusted`	Boolean	✅	whether the trusted payer

Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "amount":             1,
    "payway":             "imps",
    "currency":           "INR",
    "order_id":           "'$ORDER_ID'",
    "description":        "Description",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_email":     "name@mail.com",
    "customer_phone":     "380991111111",
    "customer_ip":        "1.2.3.4",
    "order_3ds_bypass":   "supported",
    "properties": {
        "account_number": "1234567890",
        "account_name":   "John Doe",
        "ifsc":           "SHFD0000",
        "bank_name":      "Bank of India",
        "trusted":        true
    },
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`customer_email`	String	✅	recipient’s email address
`customer_phone`	String	✅	recipient’s phone number
`customer_ip`	String	✅	recipient’s IP
`properties.account_name`	String	✅	recipient’s IMPS account name
`properties.account_number`	String	✅	recipient’s IMPS account number
`properties.ifsc`	String	✅	recipient's Indian Financial System Code
`properties.bank_name`	String	✅	bank name
`properties.trusted`	Boolean	✅	whether the trusted payer

PhonePE (Digital Wallet)

Pay In and Pay Out
Supported currency - INR

Pay In

Request Example:

{
    "pos_id":         "'$POS_ID'",
    "mode":           "direct",
    "method":         "purchase",
    "amount":         1000,
    "payway":         "phonepe",
    "currency":       "INR",
    "order_id":       "'$ORDER_ID'",
    "customer_fname": "John",
    "customer_lname": "Doe",
    "description":    "Description",
    "customer_email": "0000000000@mail.com",
    "order_3ds_bypass":"supported",
    "server_url":     "http://callback-stub:9000/consume",
    "result_url":     "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address

GPay (Digital Wallet)

Pay In and Pay Out
Supported currency - INR

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "gpaywallet",
    "currency":         "INR",
    "order_id":         "'$ORDER_ID'",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "description":      "Description",
    "customer_email":   "0000000000@freecharge",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address

Indonesia

Online banking in Indonesia

Pay In and Pay Out
Supported currency - IDR

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "banking",
    "currency":         "IDR",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "pay_method":   "513"
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`properties.pay_method`	String	✅	bank ID
`customer_ip`	String		payer’s IP

Pay Out

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "credit",
    "payway":           "banking",
    "amount":           100,
    "currency":         "IDR",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_ip":      "1.2.3.4",
    "description":      "Test payment",
    "order_id":         "'$ORDER_ID'",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "http://www.google.com/"
    "properties": {
        "payment_type": "onlineBanking",
        "pay_method":   "513",
        "bank_account": "12345678"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		gate.io notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`properties.payment_type`	String	✅	payment type
`properties.pay_method`	String	✅	bank ID
`properties.bank_account`	String	✅	recipient’s bank account number
`customer_ip`	String		recipient’s IP

Malaysia

Online banking in Malaysia

Pay In and Pay Out
Supported currency - MYR

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "banking",
    "currency":         "MYR",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "pay_method":   "513"
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`properties.pay_method`	String	✅	bank ID
`customer_ip`	String		payer’s IP

Pay Out

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "credit",
    "payway":           "banking",
    "amount":           100,
    "currency":         "MYR",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_ip":      "1.2.3.4",
    "description":      "Test payment",
    "order_id":         "'$ORDER_ID'",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "http://www.google.com/",
    "properties": {
        "payment_type": "onlineBanking",
        "pay_method":   "513",
        "bank_account": "12345678"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`properties.payment_type`	String	✅	payment type
`properties.pay_method`	String	✅	bank ID
`properties.bank_account`	String	✅	recipient’s bank account number
`customer_ip`	String		recipient’s IP

Philippines

Online banking in the Philippines

Pay Out only
Supported currency - PHP

Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "payway":             "banking",
    "amount":             100,
    "currency":           "PHP",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_ip":        "1.2.3.4",
    "description":        "Test payment",
    "order_id":           "'$ORDER_ID'",
    "order_3ds_bypass":   "supported",
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "http://www.google.com/"
    "properties": {
        "payment_type":   "philippinesWallet",
        "pay_method":     "coinsph",
        "account_number": "12345678"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		gateio app notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`properties.payment_type`	String	✅	payment type
`properties.pay_method`	String	✅	bank ID
`properties.account_number`	String	✅	recipient’s bank account number
`customer_ip`	String		recipient’s IP

South Korea

P2P in South Korea

Pay In and Pay Out
Supported currency - KRW

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "banking",
    "currency":         "KRW",
    "customer_email":   "name@mail.com",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_ip`	String		payer’s IP

Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "payway":             "banking",
    "amount":             100,
    "currency":           "KRW",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_ip":        "1.2.3.4",
    "description":        "Test payment",
    "order_id":           "'$ORDER_ID'",
    "order_3ds_bypass":   "supported",
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "http://www.google.com/"
    "properties": {
        "pay_method":     "1376",
        "account_number": "1234567890"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`properties.pay_method`	String	✅	bank ID
`properties.account_number`	String	✅	recipient’s account number
`customer_ip`	String		recipient’s IP

Vietnam

Nganluong (Digital Wallet)

Pay In only
Supported currency - VND

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "gpaywallet",
    "currency":         "VND",
    "order_id":         "'$ORDER_ID'",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "description":      "Description",
    "customer_email":   "0000000000@freecharge",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address

Online banking in Vietnam

Pay In and Pay Out
Supported currency - VND

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "banking",
    "currency":         "VND",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "pay_method":   "513"
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`properties.pay_method`	String	✅	bank ID
`customer_ip`	String		payer’s IP

Pay Out

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "credit",
    "payway":           "banking",
    "amount":           100,
    "currency":         "VND",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_ip":      "1.2.3.4",
    "description":      "Test payment",
    "order_id":         "'$ORDER_ID'",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "http://www.google.com/"
    "properties": {
        "payment_type": "onlineBanking",
        "pay_method":   "513",
        "bank_account": "12345678"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`properties.payment_type`	String	✅	payment type
`properties.pay_method`	String	✅	bank ID
`properties.bank_account`	String	✅	recipient’s account number
`customer_ip`	String		recipient’s IP

Vietnamese bank transfers

Pay In and Pay Out
Supported currency - VND

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "wallet",
    "currency":         "VND",
    "order_id":         "'$ORDER_ID'",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "description":      "Description",
    "customer_email":   "0000000000@freecharge",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address

Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "payway":             "wallet",
    "amount":             100,
    "currency":           "VND",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "description":        "Test payment",
    "order_id":           "'$ORDER_ID'",
    "order_3ds_bypass":   "supported",
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "http://www.google.com/"
    "properties": {
        "payment_type":   "onlineBanking",
        "account_number": "12345678"
    }
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`properties.payment_type`	String	✅	payment type
`properties.account_number`	String	✅	recipient’s account number

Latin America

Brazil

PicPay (Digital Wallet)

Pay In only
Supported currency - BRL

Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "amount":           5,
    "method":           "purchase",
    "currency":         "BRL",
    "payway":           "pic",
    "order_3ds_bypass": "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CPF",
        "post_code":     "88040-230"
    },
    "server_url":       "https://callback.blackhole.com/callback",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`properties.document_type`	String		payer’s document type
`properties.document_id`	String		payer’s document ID
`properties.post_code`	String		payer’s postal code

Validation

The "properties.document_type" parameter is not mandatory for creating a payment, since it is not always used in requests for PS. The parameter is informative for the merchant. It needs to be transmitted.

Boleto (Digital Wallet)

Pay In only
Supported currency - BRL

Pay In

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "amount":             5,
    "method":             "purchase",
    "currency":           "BRL",
    "payway":             "boleto",
    "order_3ds_bypass":   "supported",
    "customer_lname":     "Doe",
    "customer_fname":     "John",
    "customer_email":     "name@mail.com",
    "customer_phone":     "1234567890",
    "description":        "Test description",
    "order_id":           "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CNPJ",
        "post_code":     "88040-230"
    },
    "server_url":       "https://callback.blackhole.com/callback",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`properties.document_type`	String	✅	payer’s document type
`properties.document_id`	String	✅	payer’s document ID
`properties.post_code`	String	✅	payer’s postal code

Deposit Express (Digital Wallet)

Pay In and Pay Out
Supported currency - BRL

Pay In

Request Example:

{
    "pos_id":            "'$POS_ID'",
    "mode":              "direct",
    "amount":            5,
    "method":            "purchase",
    "currency":          "BRL",
    "payway":            "deposit",
    "order_3ds_bypass":  "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CNPJ",
        "post_code":     "88040-230",
        "pay_method":    "bradesco"
    },
    "server_url":       "https://callback.blackhole.com/callback",
    "result_url":       "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`properties.document_type`	String	✅	payer’s document type
`properties.document_id`	String	✅	payer’s document ID
`properties.post_code`	String	✅	payer’s postal code
`properties.pay_method`	String	✅	payer’s bank name

Pay Out

Request Example:

{
    "pos_id":                "'$POS_ID'",
    "mode":                  "direct",
    "method":                "credit",
    "amount":                1,
    "currency":              "BRL",
    "order_3ds_bypass":      "supported",
    "order_id":              "'$ORDER_ID'",
    "description":           "Test description",
    "payway":                "banking",
    "customer_lname":        "Doe",
    "customer_fname":        "John",
    "properties": {
        "document_id":       "0000000000",
        "document_type":     "CPF",
        "bank_account_type": "CHECKING",
        "bank_account":      "12345678",
        "bank_account_digit":"2",
        "bank_account_code": "260",
        "branch_code":       "0001"
    },
    "server_url":           "https://callback.blackhole.com/callback",
    "result_url":           "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`properties.document_id`	String	✅	recipient’s document ID
`properties.document_type`	String		recipient’s document type
`properties.bank_account_type`	String	✅	recipient’s account type
`properties.bank_account`	String	✅	recipient’s account number
`properties.bank_account_digit`	String	✅	bank account digit
`properties.bank_account_code`	String	✅	bank account code
`properties.branch_code`	String	✅	bank regional code

Validation

The parameter "properties.document_type" is optional for creating a payment, it is always passed in requests to the "CPF" PS. The parameter is informative for the merchant.

Lotopay (Digital Wallet)

Pay In only
Supported currency - BRL

Pay In

Request Example:

{
    "pos_id":            "'$POS_ID'",
    "mode":              "direct",
    "amount":            5,
    "method":            "purchase",
    "currency":          "BRL",
    "payway":            "lotopay",
    "order_3ds_bypass":  "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CNPJ",
        "post_code":     "88040-230"
    },
    "server_url":        "https://callback.blackhole.com/callback",
    "result_url":        "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`properties.document_type`	String	✅	payer’s document type
`properties.document_id`	String	✅	payer’s document ID
`properties.post_code`	String	✅	payer’s postal code

PIX QR (Digital Wallet)

Pay In and Pay Out
Supported currency - BRL

Pay In

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "amount":             5,
    "method":             "purchase",
    "currency":           "BRL",
    "payway":             "pix",
    "order_3ds_bypass":   "supported",
    "customer_lname":     "Doe",
    "customer_fname":     "John",
    "customer_email":     "name@mail.com",
    "customer_phone":     "1234567890",
    "description":        "Test description",
    "order_id":           "'$ORDER_ID'",
    "properties": {
        "document_id":    "50284414727",
        "document_type":  "CNPJ",
        "post_code":      "88040-230"
    },
    "server_url":         "https://callback.blackhole.com/callback",
    "result_url":         "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`properties.document_type`	String	✅	payer’s document type
`properties.document_id`	String	✅	payer’s document ID
`properties.post_code`	String	✅	payer’s postal code

Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "amount":             5,
    "method":             "credit",
    "currency":           "BRL",
    "payway":             "pix",
    "order_3ds_bypass":   "supported",
    "customer_lname":     "Doe",
    "customer_fname":     "John",
    "customer_email":     "name@mail.com",
    "customer_phone":     "1234567890",
    "description":        "Test description",
    "order_id":           "'$ORDER_ID'",
    "properties": {
        "document_id":    "50284414727",
        "document_type":  "CPF",
        "account_type":   "CPF",
        "account_number": "50284414727"
    },
    "server_url":         "https://callback.blackhole.com/callback",
    "result_url":         "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`properties.document_id`	String	✅	recipient’s document ID
`properties.document_type`	String	✅	recipient’s document type
`properties.account_type`	String	✅	recipient’s account type
`properties.account_number`	String	✅	recipient’s pix key

PIX (Digital Wallet)

Pay In and Pay Out
Supported currency - BRL

Pay In

Request Example:

{
    "pos_id":            "'$POS_ID'",
    "mode":              "direct",
    "amount":            5,
    "method":            "purchase",
    "currency":          "BRL",
    "payway":            "pix",
    "order_3ds_bypass":  "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CPF"
    },
    "server_url":        "https://callback.blackhole.com/callback",
    "result_url":        "https://example.com/result"
}

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`order_3ds_bypass`	String	✅	3-D Secure flow option
`order_id`	String	✅	Unique identifier of order
`description`	String	✅	Payment description
`payway`	String	✅	Payway name
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`customer_fname`	String	✅	payer’s first name
`customer_lname`	String	✅	payer’s last name
`customer_email`	String	✅	payer’s email address
`customer_phone`	String	✅	payer’s phone number
`properties.document_type`	String	✅	payer’s document type
`properties.document_id`	String	✅	payer’s document ID

Pay Out

Request Example:

{
    "pos_id":            "'$POS_ID'",
    "mode":              "direct",
    "amount":            5,
    "method":            "credit",
    "currency":          "BRL",
    "payway":            "pix",
    "order_3ds_bypass":  "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CPF"
    },
    "server_url":        "https://callback.blackhole.com/callback",
    "result_url":        "https://example.com/result"
}

Parameter	Type	Required	Description
`customer_fname`	String	✅	recipient’s first name
`customer_lname`	String	✅	recipient’s last name
`customer_email`	String	✅	recipient’s email address
`customer_phone`	String	✅	recipient’s phone number
`properties.document_id`	String	✅	recipient’s document ID
`properties.document_type`	String	✅	recipient’s document type

Preflight requests

Preflight request - is a special requests that is sent right before primary transaction processing. For example, it could be used to ensure that goods are available on payment submission.

Format of Preflight request is the same as in webhooks.

Typical flow:

Merchant creates hosted payment
User is redirected to Checkout page
User submits card data
E-Gates sends Preflight request to validation_url if it was defined
If endpoint responses with 200 OK and content is PROCEED, then E-Gates starts the transaction. Otherwise, payment is cancelled and webhook with failure status is sent to server_url

Preflight requests are sent only in hosted mode.

Webhooks

E-Gates has an option to notify merchant with every payment status update.

Webhook structure

Example of webhook

data=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A
signature=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A

Webhook is sent with POST HTTP method with Content-Type: application/x-www-form-urlencoded (form data)

Form parameters:

Parameter	Type	Description
`data`	String	Base64Url-encoded JSON
`signature`	String	`data` signed with `${SECRET_KEY}`

Webhook source IP

E-Gates sends webhooks to merchant from the following IP addresses:

35.187.74.148
217.182.91.143

Webhook verification

Signature calculation example:

raw_data='{"name":"Joe","age":20}'       # {"name":"Joe","age":20}
data='eyJuYW1lIjoiSm9lIiwiYWdlIjoyMH0='  # base64url_encode(raw_data)
secret='changeme'                        # should be changed to ${API_SECRET}

signature='Bcj3hb-h00HrEMIoJ5nPW5ZHlVQ=' # base64url_encode(sha1($secret + $data + secret))

# Bash one-liner:
#   1. calculate sha1 as raw bytes
#   2. encode raw bytes with base64
#   3. replace [+]->[-],[/]->[_]
echo -n 'changemeeyJuYW1lIjoiSm9lIiwiYWdlIjoyMH0=changeme' | \
      openssl dgst -binary -sha1 | \
      base64 | \
      tr '/+' '_-'

Signature calculation algorithm: signature=base64url_encode(sha1($API_SECRET + base64url_encode($data) + $API_SECRET))

sha1 function should produce raw bytes rather than hex-encoded string.

Signature length: 28 characters

Primary operation webhook parameters

Primary operation webhook structure

{
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "111999991",
  "gateway_order_id":    "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
  "billing_order_id":    "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "auth",
  "amount":              0.28,
  "currency":            "UAH",
  "payway":              "privat24",
  "eci":                 "7",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "cc_mask":             "424242******4242",
  "cc_token":            "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
  "cc_token_expiration": "2020-10-10T10:10:22",
  "customer_id":         "123",
  "customer_phone":      "+380999999999",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:22.100",
  "payload":             ""
}

Parameter	Type	Required	Description
`payment_id`	String	✅	Unique E-Gates payment identifier
`order_id`	String	✅	Unique identifier of order
`gateway_order_id`	String		Unique order identifier in bank acquirer system.
`billing_order_id`	String		Unique E-Gates billing identifier
`transaction_id`	String		Unique E-Gates transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	Payment mode
`method`	String	✅	Payment method
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency
`payway`	String		Optional payway
`eci`	String		Electronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure
`status`	String	✅	Transaction status
`status_code`	String		E-Gates payment status code
`status_description`	String		E-Gates payment status code description
`cc_mask`	String		Card number mask
`cc_token`	String		E-Gates card token
`cc_token_expiration`	String		Token expiration timestamp
`customer_id`	String		Customer identifier in merchant's system
`customer_phone`	String		Customer phone
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time
`payload`	String		Payment request payload

Secondary operation webhook parameters

Capture webhook

Capture webhook structure:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

Capture webhook parameters:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique E-Gates capture identifier
`payment_id`	String	✅	E-Gates payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique E-Gates transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`capture`
`amount`	Number	✅	Actual capture amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		E-Gates payment status code
`status_description`	String		E-Gates payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time

Void webhook

Void webhook structure:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "void",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

Void webhook parameters:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique E-Gates void identifier
`payment_id`	String	✅	E-Gates payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique E-Gates transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`void`
`amount`	Number	✅	Actual void amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		E-Gates payment status code
`status_description`	String		E-Gates payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time

Refund webhook

Refund webhook structure:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",    
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

Refund webhook parameters:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique E-Gates refund identifier
`payment_id`	String	✅	E-Gates payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique E-Gates transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`refund`
`amount`	Number	✅	Actual refund amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		E-Gates payment status code
`status_description`	String		E-Gates payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time

Resend webhook for operation

Request example:

$ curl "https://paygates.e-gates.io/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/${OPERATION}?callback=true" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Returns specific operation for this ${ORDER_ID} and sends webhook to server_url specified in request.

HTTP method: GET

Parameter	Type	Required	Description
`POS_ID`	UUID	✅	Merchant's identifier (`POS_ID`)
`ORDER_ID`	String	✅	Merchant's order identifier
`OPERATION`	String	✅	Payment method, e.g. `purchase`, `void`, etc.

Query parameters

Parameter	Type	Required	Description
`callback`	Boolean	✅	`true`

E-Gates card tokens

E-Gates card token - is a special random string that could be used in card payments. Mostly used for recurring payments. Merchant is not required to be PCI-DSS compliant in order to use E-Gates card tokens.

Use tokens to implement recurring payments.

Status codes

E-Gates uses special codes in order to unify gateway transaction statuses.

Successful codes

Code	Status	Description
0	success	Test transaction
1000	success	Transaction successful
1001	success	Transaction is successful, it will be transferred in daily settlement
1002	success	Protected transaction. Charging is successful, waiting for receipt of goods confirmation
1003	success	Funds are reserved to make a refund according to a refund request
1004	success	Refund successful
1005	success	Subscription successful
1006	success	Unsubscribed successfully
1007	success	Amount was successfully blocked on the sender's account
1009	success	Reverse successful

Pending codes

Code	Status	Description
1008	pending	Amount is charged successfully but the store is still not verified. Store need to be activated within 90 days, otherwise transaction will be automatically cancelled.
2000	pending	Pending
2001	pending	Pending
2002	pending	Pending
2010	pending	Capture required
2012	pending	Transaction is on anti-fraud check
2100	pending	3DS verification is required to finish the transaction.
2101	pending	CVV is required
2102	pending	OTP confirmation is required. OTP is sent to a customer phone number.
2103	pending	Receiver info required
2104	pending	Sender info required
2105	pending	Missed payout method data
2106	pending	Waiting for verification via captcha
2107	pending	Waiting for verification via IVR call
2108	pending	Waiting for verification via Privat24
2109	pending	Waiting for customer's phone number verification
2110	pending	Waiting for customer's pin-code verification
2111	pending	Waiting for verification via SENDER app
2112	pending	Waiting for verification via QR code
2113	pending	Waiting for transaction verification via Privat24/SENDER application
2114	pending	Waiting for transaction complete in Privat24
2115	pending	Waiting for transaction complete in MasterPass
2116	pending	Waiting for cash transaction at Self-Service Machine
2119	pending	Transaction is processing
2120	pending	Authorization required
2122	pending	3DS verification is required
2123	pending	Waiting for redirect to the checkout page
2124	pending	Waiting for redirect to continue payment
2201	pending	Waiting for clarification
4018	pending	PIN tries exceeded. Capture is required.
4019	pending	Card expired
4100	pending	User not found
4101	pending	Failed to send sms
4102	pending	Wrong sms password
6000	pending	Transaction is on antifraud check
9000	pending	Unknown error. Please, contact technical support.

Failure codes

Code	Status	Description
2003	failure	Wrong PIN
2004	failure	Wrong amount
2005	failure	Wrong authorization code
2006	failure	Wrong CAVV
2007	failure	Wrong CVV2
2008	failure	Internal error. Please try again.
2009	failure	Wrong account number
2121	failure	Card verification is required.
4000	failure	Invalid data. Missed required input fields
4001	failure	Payment card expired
4002	failure	Incorrect refund sum or currency
4003	failure	Payment card has invalid status
4004	failure	Wrong data used at `Info` input.
4005	failure	Internal error
4006	failure	Internal error
4007	failure	Internal error. Please try again.
4008	failure	Wrong card number
4009	failure	Insufficient funds
4010	failure	Transaction limit exceeded. Try another card.
4011	failure	Internal error
4012	failure	Transaction amount limit exceeded. Try another card.
4013	failure	Internal error
4014	failure	Internal error
4015	failure	Internal error
4016	failure	Internal error
4017	failure	Internal error
4020	failure	Payment card has constraints
4103	failure	Card not found in wallet for receiving payments.
4104	failure	This card payment system is not supported. Please enter another card.
4105	failure	Invalid card type.
4106	failure	This country is not supported. Please enter another card.
4107	failure	Amount of transaction is more or less than the limit.
4108	failure	Amount of transaction is more or less than the limit.
4109	failure	Transaction amount limit is exceeded.
4110	failure	Please, enter sender's another card.
4111	failure	No discount found for the transaction.
4112	failure	Failed to load the wallet.
4113	failure	Invalid verification code.
4114	failure	Additional information is pending. Please, try later.
4115	failure	Split amount is not equal to transaction amount.
4116	failure	Transaction is not recurring.
4117	failure	Transaction currency does not match with debit currency.
4118	failure	Capture amount cannot be more than the transaction amount.
4119	failure	Such `order_id` already exists in the system.
4120	failure	Parameter is empty.
4121	failure	`Phone` parameter is empty.
4122	failure	Parameter is not transferred.
4123	failure	Invalid parameter.
4124	failure	Invalid currency. Please use: USD, UAH, EUR.
4125	failure	Invalid phone number.
4126	failure	Invalid card number.
4127	failure	Card bin is not found.
4128	failure	Currency exchange rate is not found.
4129	failure	Invalid recipient name.
4130	failure	Daily card usage limit reached.
4131	failure	Such `order_id` already exists in the system.
4132	failure	Transaction for this country are forbidden.
4133	failure	Expired card.
4134	failure	Invalid card number
4135	failure	Card does not support such transaction type.
4136	failure	Card does not support such transaction type.
4137	failure	Insufficient funds.
4138	failure	Transaction amount limit is exceeded.
4139	failure	Invalid transaction amount.
4140	failure	Transaction is declined. Please check if the card details are correct.
4141	failure	OTP confirmation timeout
4142	failure	Transaction amount limit is exceeded.
4143	failure	Transaction amount limit is exceeded.
4144	failure	Invalid card data
4145	failure	Privat24 confirmation timeout
4146	failure	SenderApp confirmation timeout
4147	failure	3-D Secure verification timeout
4148	failure	Timeout
4149	failure	Session expired
4150	failure	Invalid operation
4151	failure	Invalid input fields
4152	failure	Invalid configuration. Please, contact technical support.
4153	failure	Transaction rejected
4154	failure	Transaction is rejected by anti-fraud
4155	failure	Transaction was declined by blacklist
4156	failure	Card not supported
4160	failure	Failed to create transaction
5000	failure	Invalid operation
5001	failure	The transaction has incorrect attributes or this operation is prohibited.
5002	failure	Payment rejected. Please contact support.
5003	failure	Internal error
5004	failure	Transaction is not supported by provider
5005	failure	Internal error
5009	failure	Internal error
5010	failure	Internal error
5014	failure	Authorization error. Please contact support.
5015	failure	Internal error
5019	failure	Internal error
5020	failure	Internal error
5021	failure	Authorization error. Contact issuer bank
5022	failure	This card type is not supported
5023	failure	Timeout
5024	failure	Internal error
5025	failure	Internal error
5026	failure	Internal error
5027	failure	Internal error
5028	failure	Internal error
5029	failure	Transaction is not supported. Please contact customer support service
5030	failure	Internal error
5102	failure	Transaction cache data timeout
5103	failure	Store is blocked
5104	failure	Store is not active
5105	failure	Wrong request signature
5106	failure	Order_id is empty
5107	failure	You are not the agent of the specified store
5108	failure	User doesn't have a card with such token.
5109	failure	Invalid request url.
5110	failure	Transaction cannot be processed
5111	failure	Receiver didn't set the card to receive transactions.
5112	failure	Invalid transaction status.
5113	failure	`Public_key` is not found.
5114	failure	Transaction is not found.
5115	failure	Access error
5116	failure	Access to account is blocked.
5117	failure	Terminal is not found.
5118	failure	Fee is not found.
5119	failure	Failed to create transaction.
5120	failure	Failed to verify a card.
5121	failure	Currency is prohibited.
5122	failure	Failed to finish the transaction.
5123	failure	Failed to finish the transaction
5124	failure	Invalid transaction type.
5125	failure	Transaction currency is prohibited.
5126	failure	Invalid transaction request signature.
5127	failure	`Action` parameter is not sent in request.
5128	failure	`Callback` parameter is not transferred.
5129	failure	This merchant is restricted to call API from this IP.
5130	failure	Card does not support 3-D Secure.
5131	failure	General error during processing.
5132	failure	Token doesn't belong to this merchant.
5133	failure	Received token is inactive.
5134	failure	Token reached the maximum purchase amount.
5135	failure	Token transactions' limit exceeded.
5136	failure	Card not supported.
5137	failure	Merchant is not allowed preauth.
5138	failure	Acquirer does not support 3-D Secure.
5139	failure	This token does not exist.
5140	failure	Reached the limit of attempts for this IP.
5141	failure	Session expired.
5142	failure	Card branch is blocked.
5143	failure	Card branch daily limit reached.
5144	failure	Temporarily closed the P2P transactions from PB cards to foreign banks' cards.
5145	failure	Completion limit reached.
5146	failure	Transaction is declined. Please, try again later.
5147	failure	Transaction is declined. Bank did not approve the transaction. Please, contact the bank.
5148	failure	Bank did not approve the transaction. Please, contact the bank.
5149	failure	Invalid parameters or transaction is not allowed.
5150	failure	Merchant is not allowed for making recurring transactions.
5151	failure	Transaction is canceled by payer.
5152	failure	Authorization error. Contact issuer bank.
5156	failure	ACS Service Unavailable.
6003	failure	The transaction is declined by bank's anti-fraud system.
6001	failure	The limit for the amount or number of customer payments has been exceeded. Amount or transaction limit has been exceeded.
6002	failure	The transaction is rejected by bank's anti-fraud rules.
6004	failure	Payment card is lost or stolen
6005	failure	Transaction was declined by internal blacklist.

Init codes

Code	Status	Description
2117	init	Invoice is created successfully, waiting for a transaction.
2118	init	Transaction is created successfully, waiting for sender to complete.

Error handling

HTTP statuses

Status	Description	Hint
400	Bad Request	Request is invalid.
401	Unauthorized	Either `POS_ID`, `API_KEY`, `API_SECRET` or `ENDPOINTS_KEY` is invalid.
404	Not Found	Payment or endpoint not found.
405	Method Not Allowed	Usage of request HTTP method is not allowed.
406	Not Acceptable	All `POST` requests should have `application/json` content type.
429	Too Many Requests	Too high request rate.
500	Internal Server Error	Internal error occurred on E-Gates side. Please, contact technical support with specified request and response.
503	Service Unavailable	E-Gates server was unreachable. Please, contact technical support with specified request and response.

Client-side errors (4XX HTTP statuses)

Example of response body returned in case of unsuccessful HTTP status:

{
  "message": "Invalid pos_id field or credentials",
  "args": {
    "code": "S-403"
  }
}

Example of response body for unsuccessful requests due to technical or configuration issues.

Field	Type	Required
`message`	String(512)	✅
`args`	JSON	✅
`args.code`	String(16)

Server-side errors (5XX HTTP statuses)

For 5XX statuses there is an extra "error_id" field:

{
  "message": "Internal error occurred",
  "args": {
    "error_id": "NYdKYdA4Zv3iOJSw"
  }
}

If you faced 5XX error, please contact E-Gates technical support.

Field	Type	Required
`message`	String(512)	✅
`args`	Object	✅
`args.error_id`	String(16)

FAQ on errors returned from E-Gates API:

Error message	Hints
API key not valid. Please pass a valid API key.	Check `ENDPOINTS_KEY` value
Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.	Check if header `X-API-KEY` was passed

Contact maintainers

If you found a type or some information is missing in this documentation feel free to contact API maintainers

Enrichment API

Enrichment API is used to obtain information about BIN and IP address location.

BIN info

Request example:

$ curl "https://paygates.e-gates.io/api/v1/enrichments/${POS_ID}/bins/${BIN}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Obtain information about BIN.

HTTP method: GET

Parameter	Type	Required	Description
`POS_ID`	UUID	✅	Merchant's identifier (`POS_ID`)
`BIN`	Number	✅	`BIN` identifier

Response example:

{
  "card": {
    "bin": 424242,
    "payment_system": "VISA",
    "card_type": "CREDIT",
    "card_variant": "UNDEFINED"
  },
  "country": {
    "country": "UNITED KINGDOM",
    "country_digit_code": "826",
    "iso_a2_code": "GB",
    "iso_a3_code": "GBR",
    "region": "Europe"
  },
  "bank": {
    "bank": "UNDEFINED",
    "bank_website": "UNDEFINED",
    "bank_phone": "UNDEFINED"
  },
  "risk_level": "UNDEFINED"
}

Return status 404 if no BIN information.

IP info

Request example:

$ curl "https://paygates.e-gates.io/api/v1/enrichments/${POS_ID}/ips/${IP}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Obtain information about IPv4/IPv6 address location.

HTTP method: GET

Parameter	Type	Required	Description
`POS_ID`	UUID	✅	Merchant's identifier (`POS_ID`)
`IP`	String	✅	`IP` address

Response example:

{
    "continent": "Asia",
    "country": "China",
    "stateprov": "Guangdong province",
    "city": "Guangzhou",
    "latitude": "23.1291",
    "longitude": "113.2644"
}

Return status 400 if IP address has invalid format.

Return status 404 if no IP address location information.