Introduction

Welcome to the EvoPay 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

EvoPay defines two options for processing payments, a.k.a. modes:

hosted - the most popular way to integrate EvoPay. 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 EvoPay.

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.

API

API URL

In order to test whether host is reachable use https://api.evopay.com/health endpoint:

$ curl https://api.evopay.com.ua/health

OK # Expected response

All requests to evopay API should be sent to https://api.evopay.com.ua host in JSON format.

Authentication

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

$ curl "https://api.evopay.com.ua/api/v1/pos/${POS_ID}/orders/0" \
       -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
       -H "X-API-KEY: ${ENDPOINTS_KEY}"

Expected response

[]

EvoPay 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`

EvoPay 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 EvoPay 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}

Rate limits

EvoPay applies rate limit for a number of APIs (Primary operations, Secondary operations, Payment operation info).

API client should handle rate limiting gracefully. It is recommended to watch for 429 status codes and build in a retry mechanism with an exponential backoff schedule. Some randomness could be added into the backoff to avoid a thundering herd effect.
X-RATELIMIT-RESET header (time in seconds, after which requests are allowed again) could be used as a basis for retry mechanism.

Example of headers for 1000 requests/second rate limit (after first request):

Header field name	Description	Example
`X-RATELIMIT-LIMIT`	`Allowed request per second`	`X-RATELIMIT-LIMIT: 1000`
`X-RATELIMIT-RESET`	`Time to reset in seconds`	`X-RATELIMIT-RESET: 0`
`X-RATELIMIT-REMAINING`	`Number of left requests`	`X-RATELIMIT-REMAINING: 999`

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"`, `"RUB"`
`STATUS`	String(≤32)		`"success"` (Transaction status)
`STATUS_CODE`	String(4)		`"1000"` (Evopay payment status code)
`STATUS_DESCRIPTION`	String(≤1024)		`"Transaction is successful."` (EvoPay 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"` (EvoPay 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,
  "price_type": "VAT",
  "vat": 6600,
  "qty": 1,
  "payload": "ref_no=1231; discount=false",
  "metadata": {
    "type": "yookassa",
    "tax_system_code": 2,
    "vat_code": 1,
    "customer_phone": "123456",
    "customer_email": "@gmail.com" 
  }
}

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
`category_id`	String	Product category ID
`name`	String	Product name
`description`	String	Product description
`amount`	Number	Product price (does not influence total payment amount)
`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.
`metadata`	String	Custom metadata in Json format

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://api.evopay.com.ua/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",
      "properties": {
        "custom_data": "custom_value",
        "custom_data_number" : "100",
        "custom_data_boolean" : "true"
      },
      "recipient_cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv"
    }'

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://api.evopay.com.ua/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 identified 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_patronym`	String		Customer patronymic
`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
`customer_city`	String		Customer city
`customer_postal_code`	String		Customer postal code
`customer_address`	String		Customer address
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`recipient_fname`	String		Recipient first name
`recipient_lname`	String		Recipient last name
`recipient_patronym`	String		Recipient patronym
`recipient_city`	String		Recipient city
`recipient_postal_code`	String		Recipient postal code
`recipient_address`	String		Recipient address
`recipient_phone`	String		Recipient phone
`recipient_email`	String		Recipient email
`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.
`properties`	JSON (flat)		A flat json object for arbitrary additional values (with String values only)
`recipient_cc_token`	String		Recipient card token. For p2p-payments either this parameter or recipient_cc_number is mandatory
`recipient_cc_number`	String		Recipient card number. For p2p-payments either this parameter or recipient_cc_token is mandatory

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://api.evopay.com.ua/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",
      "properties": {
        "custom_data": "custom_value",
        "custom_data_number" : "100",
        "custom_data_boolean" : "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"
      },
      "recipient_cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv"
    }'

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 identified 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_patronym`	String		Customer patronymic
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`customer_postal_code`	String		Customer postal code
`customer_address`	String		Customer address
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`recipient_fname`	String		Recipient first name
`recipient_lname`	String		Recipient last name
`recipient_patronym`	String		Recipient patronym
`recipient_city`	String		Recipient city
`recipient_postal_code`	String		Recipient postal code
`recipient_address`	String		Recipient address
`recipient_phone`	String		Recipient phone
`recipient_email`	String		Recipient email
`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.
`properties`	Json (flat)		A flat json object for arbitrary additional values (with String values only)
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
`recipient_cc_token`	String		Recipient card token. For p2p-payments either this parameter or recipient_cc_number is mandatory
`recipient_cc_number`	String		Recipient card number. For p2p-payments either this parameter or recipient_cc_token is mandatory

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":       "[email protected]",
  "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",
  "cc_type":              "Business"
}

Parameter	Type	Description
`payment_id`	UUID	Unique EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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	EvoPay 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.
`cc_type`	String	Type of the credit card: "Business", "Private", "Government"

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

Direct payments using Privat24

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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 identified 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_patronym`	String		Customer patronymic
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.

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":       "[email protected]",
  "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 EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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://api.evopay.com.ua/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 identified 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_patronym`	String		Customer patronymic
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.
`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":       "[email protected]",
  "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 EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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 Evo tokens

HTTP method: POST

Request example:

$ curl "https://api.evopay.com.ua/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",
      "recipient_cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv"
    }'

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 identified of order
`cc_token`	CC_TOKEN	✅	EvoPay 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_patronym`	String		Customer patronymic
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.
`properties`	JSON (flat)		A flat json object for arbitrary additional values (with String values only)
`recipient_cc_token`	String		Recipient card token. For p2p-payments either this parameter or recipient_cc_number is mandatory
`recipient_cc_number`	String		Recipient card number. For p2p-payments either this parameter or recipient_cc_token is mandatory

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":       "[email protected]",
  "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",
  "cc_token": "Business"
}

Response parameters

Parameter	Type	Description
`payment_id`	UUID	Unique EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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	EvoPay 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
`cc_type`	String	Type of the credit card: "Business", "Private", "Government"

Credit payments via EvoCredit

This payment method allow making credit payment via EvoCredit or Alfa bank credit system

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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",
      "merchant_order_id":"1111111111",
      "order_3ds_bypass": "always",
      "payway":           "credit_pay",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties":       {
          "another_recipient": "false",
          "acc_change_date": "15.09.2021",  
          "last_captcha_date": "15.09.2021",  
          "delivery_method_id": "1234",                     
          "delivery_service_id": "1234",                     
          "delivery_point_id": "1234",                     
          "delivery_city": "Київ",
          "delivery_street": "Хрещатик",
          "delivery_house": "1",
          "delivery_flat": "42",
          "delivery_datetime": "15.09.2021 16:00-21:00",  
          "recipient_fname": "Іванов",
          "recipient_lname": "Іван",
          "recipient_patronym": "Іванович",
          "recipient_phone": "+380639379992",
          "loan_term" : "12"
      },
      "products":         [
        {
          "name"       : "Apple",
          "amount"     : 100,
          "qty"        : 2,
          "category"   : "Комплекти для хлопчиків",
          "category_id": "4668289"
        },
        {
          "name"       : "Pineapple",
          "amount"     : 100,
          "qty"        : 1,
          "category"   : "Комплекти для дівчаток",
          "category_id": "4668288"
        }
      ],
      "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 (must be > 300 UAH)
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identified of order
`merchant_order_id`	String		merchant identified of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`payway`	String	✅	Optional payway. Use "credit_pay" for processing direct payments through Evo CreditPay
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_patronym`	String		Customer patronym
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.
`properties`	JSON		A flat JSON with information about delivery and recipient (with String values only)
`products`	Array[Product]		Array of products to be paid
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

Properties parameters description

Parameter	Type	Description
`another_recipient`	String	Recipient is another person, allowed values are "true" or "false" (in quotes)
`acc_change_date`	String	Customer data change date
`last_captcha_date`	String	Last date of temporary password generation
`hash_code`	String	Some hashCode
`delivery_method_id`	String	Delivery method id
`delivery_service_id`	String	Delivery service id
`delivery_point_id`	String	Delivery point id
`delivery_city`	String	Delivery city
`delivery_street`	String	Delivery street
`delivery_house`	String	Delivery house
`delivery_flat`	String	Delivery flat
`city_mdm_id`	String	Delivery city code
`street_mdm_id`	String	Delivery street code
`place_mdm_id`	String	Delivery place code
`delivery_datetime`	String	Delivery date and time
`recipient_fname`	String	Recipient first name, if recipient differ from payer
`recipient_lname`	String	Recipient last name, if recipient differ from payer
`recipient_patronym`	String	Recipient patronym, if recipient differ from payer
`recipient_phone`	String	Recipient phone, if recipient differ from payer
`loan_term`	String	Loan term

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://alfabank.ua/onbording_start/12312312312",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "credit_pay",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "[email protected]",
  "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",
  "gateway_properties": {
    "credit_register_id": "123456789"
  }
}

Parameter	Type	Description
`payment_id`	UUID	Unique EvoPay payment identifier
`order_id`	String	Unique identifier of order
`merchant_order_id`	String	merchant identified of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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 "credit_pay" for processing direct payments through Evo CreditPay
`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_patronym`	String	Customer customer patronym
`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.
`gateway_properties`	String	Additional properties provided by credit gateway (with String values only)

Gateway properties parameters description

Parameter	Type	Description
`credit_register_id`	String	Register ID

Payments via Przelewy24

This payment method allow making payments via Przelewy24 system

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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",
      "merchant_order_id":"1111111111",
      "order_3ds_bypass": "always",
      "payway":           "przelewy24",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "products":         [
        {
          "name"       : "Apple",
          "amount"     : 100,
          "qty"        : 2,
          "category"   : "Комплекти для хлопчиків",
          "category_id": "4668289"
        },
        {
          "name"       : "Pineapple",
          "amount"     : 100,
          "qty"        : 1,
          "category"   : "Комплекти для дівчаток",
          "category_id": "4668288"
        }
      ],
      "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 identified of order
`merchant_order_id`	String		merchant identified of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`payway`	String	✅	Use "przelewy24" for processing direct payments through Przelewy24
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_patronym`	String		Customer patronym
`customer_email`	String	✅	Customer email (length must be <= 50)
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_postal_code`	String		Customer postal code (length must be <= 6)
`customer_address`	String		Customer address (length must be <= 50)
`customer_country`	String	✅	Customer country
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.
`products`	Array[Product]		Array of products to be paid
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

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://przelewy24.ua/onbording_start/12312312312",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "przelewy24",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "[email protected]",
  "customer_phone":       "+380999999999",
  "customer_address":     "Nova str. 25",
  "customer_postal_code": "35-785",
  "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 EvoPay payment identifier
`order_id`	String	Unique identifier of order
`merchant_order_id`	String	merchant identified of order
`gateway_order_id`	GW_ID	Unique order identifier in bank acquirer system.
`billing_order_id`	BILLING_ID	Unique EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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	Use "przelewy24" for processing direct payments through Przelewy24
`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_patronym`	String	Customer customer patronym
`customer_email`	String	Customer email
`customer_phone`	String	Customer phone
`customer_postal_code`	String	Customer postal code
`customer_address`	String	Customer address
`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.
`cc_type`	String	Type of the credit card: "Business", "Private", "Government"

P2P payments

HTTP method: POST

Request example:

$ curl "https://api.evopay.com.ua/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",
      "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 identified 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_patronym`	String		Customer patronymic
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
`recipient_fname`	String		Recipient first name
`recipient_lname`	String		Recipient last name
`recipient_patronym`	String		Recipient patronymic
`recipient_email`	String		Recipient email
`recipient_phone`	String		Recipient phone

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":       "[email protected]",
  "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",
  "cc_type":              "Business"
}

Response parameters

Parameter	Type	Description
`payment_id`	UUID	Unique EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	String	EvoPay 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	EvoPay 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.
`cc_type`	String	Type of the credit card: "Business", "Private", "Government"

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

P2P payments using Evo tokens

HTTP method: POST

Request example:

$ curl "https://api.evopay.com.ua/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"
    }'

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 identified of transfer
`cc_token`	CC_TOKEN	✅	EvoPay card token, obtained from previous payments
`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_patronym`	String		Customer patronymic
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.
`recipient_fname`	String		Recipient first name
`recipient_lname`	String		Recipient last name
`recipient_patronym`	String		Recipient patronymic
`recipient_email`	String		Recipient email
`recipient_phone`	String		Recipient phone
`properties`	JSON (flat)		A flat json object for arbitrary additional values (with String values only)

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":       "[email protected]",
  "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",
  "cc_type":              "Business"
}

Response parameters

Parameter	Type	Description
`payment_id`	UUID	Unique EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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	EvoPay 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.
`cc_type`	String	Type of the credit card: "Business", "Private", "Government"

Lookup

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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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`
`method`	METHOD	✅	Payment method (`lookup`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identified 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_patronym`	String		Customer patronymic
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String		Customer IP address
`customer_country`	String		Customer country
`customer_city`	String		Customer city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.

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":       "[email protected]",
  "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",
  "cc_type":              "Business"
}

Parameter	Type	Description
`payment_id`	UUID	Unique EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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	EvoPay 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.
`cc_type`	String	Type of the credit card: "Business", "Private", "Government"

Credit payments

HTTP method: POST

Request example:

$ curl "https://api.evopay.com.ua/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 identified 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_patronym`	String		Customer patronymic
`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)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.
`properties`	JSON (flat)		Additional specific parameters for integrations (with String values only)

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":       "[email protected]",
  "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 EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	String	EvoPay 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	EvoPay 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 (format: yyyy-MM-dd)
`customer_user_agent`	String
`customer_referrer`	String
`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 (flat)	Additional specific parameters for integrations (with String values only)

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 Evo tokens

HTTP method: POST

Request example:

$ curl "https://api.evopay.com.ua/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 identified of transfer
`cc_token`	CC_TOKEN	✅	EvoPay 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_patronym`	String		Customer patronymic
`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)
`customer_user_agent`	String		Customer user agent
`customer_referrer`	String		Customer referrer
`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.
`properties`	JSON (flat)		A flat json object for arbitrary additional values (with String values only)

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":       "[email protected]",
  "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 EvoPay 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 EvoPay billing identifier
`transaction_id`	UUID	EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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	EvoPay 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 (format: yyyy-MM-dd)
`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 (flat)	A flat json object for arbitrary additional values (with String values only)

Allowed properties for credit payment using Evo 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://api.evopay.com.ua/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",
      "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
`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
}

Parameter	Type	Description
`operation_id`	UUID	Unique EvoPay capture identifier
`payment_id`	UUID	EvoPay payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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

Partial capture

Capture could be called only for authorizations with success status.

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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,
      "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
`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
}

Parameter	Type	Description
`operation_id`	UUID	Unique EvoPay capture identifier
`payment_id`	UUID	EvoPay payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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

Void

Void could be called only for authorizations with success status.

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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",
      "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
`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
}

Parameter	Type	Description
`operation_id`	UUID	Unique EvoPay void identifier
`payment_id`	UUID	EvoPay payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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

Refund

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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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",
      "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
`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
}

Parameter	Type	Description
`operation_id`	UUID	Unique EvoPay refund identifier
`payment_id`	UUID	EvoPay payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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

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://api.evopay.com.ua/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,
      "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
`refund_amount`	Number	✅	Amount to be refunded
`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
}

Parameter	Type	Description
`operation_id`	UUID	Unique EvoPay refund identifier
`payment_id`	UUID	EvoPay payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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

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://api.evopay.com.ua/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",
      "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 captured (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`description`	CURRENCY		Currency of original order
`cc_number`	CC_NUMBER	✅	Card number
`server_url`	URL		Webhook notification will be sent to this URL
`recipient_fname`	String		Recipient first name
`recipient_lname`	String		Recipient last name
`recipient_patronym`	String		Recipient patronymic
`recipient_email`	String		Recipient email
`recipient_phone`	String		Recipient phone

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
}

Parameter	Type	Description
`operation_id`	UUID	Unique EvoPay refund identifier
`payment_id`	UUID	EvoPay payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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

P2P Credit using EvoPay tokens

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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",
      "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 captured (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`description`	CURRENCY		Currency of original order
`cc_token`	CC_TOKEN	✅	EvoPay card token generated for this card
`server_url`	URL		Webhook notification will be sent to this URL
`recipient_fname`	String		Recipient first name
`recipient_lname`	String		Recipient last name
`recipient_patronym`	String		Recipient patronymic
`recipient_email`	String		Recipient email
`recipient_phone`	String		Recipient phone

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
}

Parameter	Type	Description
`operation_id`	UUID	Unique EvoPay refund identifier
`payment_id`	UUID	EvoPay payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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

Partial P2P Credit

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.evopay.com.ua/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",
      "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 captured (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
`server_url`	URL		Webhook notification will be sent to this URL
`recipient_fname`	String		Recipient first name
`recipient_lname`	String		Recipient last name
`recipient_patronym`	String		Recipient patronymic
`recipient_email`	String		Recipient email
`recipient_phone`	String		Recipient phone

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
}

Parameter	Type	Description
`operation_id`	UUID	Unique EvoPay refund identifier
`payment_id`	UUID	EvoPay payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique EvoPay 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	EvoPay payment status code
`status_description`	STATUS_DESCRIPTION	EvoPay 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

Get order transactions

Request example:

$ curl "https://api.evopay.com.ua/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://api.evopay.com.ua/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.

Payment operation info

$ curl "https://api.evopay.com.ua/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.

Resend webhook for operation

Request example:

$ curl "https://api.evopay.com.ua/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`

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.

Integration Checklist

GENERAL

Implement secondary operations
Ensure that all EvoPay transactions go through your regular risk input validation and checks, just like any other transaction that you handle
iframe-based Checkout Pages. Even though EvoPay’s checkout page has HTTPS, end users would see the merchant's website address in the browser URL. If you use HTTP, end users may think they are entering the credit card on an insecure page. Though not mandatory from the compliance point of view, we strongly recommend using HTTPS for iframe-based checkout pages to ensure better checkout experience for end users
Provide copy of successful request and response for all operations (test a successful transaction for each of the payment flows where Checkout is implemented)
Checkout button is properly placed on all required pages e.g., Shopping cart, Payment page, etc. (Per Branding Requirements)
- You are using Production credentials
- Provide EvoPay team with your SVG logo that can be placed in Partner's page

HOSTED METHOD

Integrate a payment widget. It should be accessible on your website/application
Customer details must be persistent and unique per user account

DIRECT METHOD

Payment page must be served via HTTPS
Client-side tokenization using widget.js
Customer details must be persistent and unique per user
The following parameters should be passed in TRZ API requests:
- fingerprint
- customer_ip
- customer_fname
- customer_lname
Your servers must not persist customer's credit card data
Recurring billing
- Website clearly shows recurring billing conditions
- Cancellation and refund policy is clearly accessible and visible in the website

CALLBACKS/WEBHOOKS

Set up a webhook endpoint in your server
Webhook Testing
- If webhook was processed successfully your server should response with 200 OK
- Callback system properly rejects duplicates
- Webhook with wrong signature are rejected
Confirm that the webhooks are being handled

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 [email protected].

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"
  }]
}

Webhooks

EvoPay 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

EvoPay sends webhooks to merchant from the following IP address:

34.107.108.72

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":               "",
    "registry_ref_no":        "9e62565c-ef89-4b7e-bcbd-a96f76af303b",
    "terminal_name":          "Name",
    "rrn":                    "014681438245",
    "recipient_cc_token":     "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
    "recipient_cc_mask":      "424242******4242",
    "dcc_rates":              [
                                                            {
                                                                "amount": 0.0,
                                                                "rate": 0.0,
                                                                "comission": 0.0,
                                                                "currency": "UAH"
                                                            }
                                                        ],
    "traffic_source":         {
                                                            "utm_source": "",
                                                            "utm_mediuum": "",
                                                            "utm_campaign": "",
                                                            "browser": "",
                                                            "device": "",
                                                            "custom": ""
                                                        },
    "auth_code":              "12121212",
    "gateway":                "cc",
    "bank_short_name":        "Name",
    "payment_system":         "VISA",
    "entity_id":              "b20e51e8-278d-408c-9a63-c74e9f4e003a",
    "fc_entity_id":           "ed6a3c74-9dc3-4639-bfe6-ad347d81271b",
    "external_terminal_name": "Terminal Name",
    "customer_patronym":      "Name",
    "recipient_email":        "[email protected]",
    "recipient_phone":        "380123456789",
    "recipient_fname":        "Name",
    "recipient_lname":        "Name",
    "recipient_patronym":     "Name",
    "merchant_order_id":      "b20e51e8-278d-408c-9a63-c74e9f4e003a",
    "receipt_url":            "https://example.url/path/00000000-00000000-00000000-00000000",
    "bank_acq_name":          "Bank Acq Name"
}

Parameter	Type	Required	Description
`payment_id`	String	✅	Unique EvoPay 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 EvoPay billing identifier
`transaction_id`	String		Unique EvoPay 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		EvoPay payment status code
`status_description`	String		EvoPay payment status code description
`cc_mask`	String		Card number mask
`cc_token`	String		EvoPay 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
`registry_ref_no`	String		Gateway transaction identifier
`terminal_name`	String		Terminal name
`rrn`	String		Transaction unique bank identifier
`recipient_cc_token`	String		EvoPay recipient card token
`recipient_cc_mask`	String		Recipient card number mask
`dcc_rates`	Array?		Dcc rates
`traffic_source`	Object		Description of the traffic source
`auth_code`	String		Approval code for UPC integration <!-- TODO Ask about this one-->
`gateway`	String		Payment gateway name
`bank_short_name`	String		Bank short name
`payment_system`	String		Payment system
`entity_id`	String		Identifier of the entity
`fc_entity_id`	String		Identifier of the financial entity
`external_terminal_name`	String		Terminal name
`customer_patronym`	String		Customer patronym
`recipient_email`	String		Recipient email
`recipient_phone`	String		Recipient phone
`recipient_fname`	String		Recipient first name
`recipient_lname`	String		Recipient last name
`recipient_patronym`	String		Recipient patronym
`merchant_order_id`	String		Order id provided by merchant
`receipt_url`	String		Url to reciept in pdf format
`bank_acq_name`	String		Bank aquier name

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",
    "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b",
  "payload":             "",
  "terminal_name":       "Terminal name",
  "auth_code":           "12121212",
  "rrn":                 "014681438245",
  "cc_mask":             "424242******4242",
  "comment":             ""
}

Capture webhook parameters:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique EvoPay capture identifier
`payment_id`	String	✅	EvoPay payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique EvoPay 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		EvoPay payment status code
`status_description`	String		EvoPay 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
`registry_ref_no`	String		Gateway transaction identifier
`payload`	String		Field for merchant custom data
`terminal_name`	String		Terminal name
`auth_code`	String		Approval code for UPC integration
`rrn`	String		Transaction unique bank identifier
`cc_mask`	String		Card number mask
`comment`	String		Transaction comment

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",
    "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b",
  "payload":             "",
  "terminal_name":       "Terminal name",
  "auth_code":           "12121212",
  "rrn":                 "014681438245",
  "cc_mask":             "424242******4242",
  "comment":             ""
}

Void webhook parameters:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique EvoPay void identifier
`payment_id`	String	✅	EvoPay payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique EvoPay 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		EvoPay payment status code
`status_description`	String		EvoPay 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
`registry_ref_no`	String		Gateway transaction identifier
`payload`	String		Field for merchant custom data
`terminal_name`	String		Terminal name
`auth_code`	String		Approval code for UPC integration
`rrn`	String		Transaction unique bank identifier
`cc_mask`	String		Card number mask
`comment`	String		Transaction comment

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",
    "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b",
  "payload":             "",
  "terminal_name":       "Terminal name",
  "auth_code":           "12121212",
  "rrn":                 "014681438245",
  "cc_mask":             "424242******4242",
  "comment":             ""
}

Refund webhook parameters:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique EvoPay refund identifier
`payment_id`	String	✅	EvoPay payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique EvoPay 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		EvoPay payment status code
`status_description`	String		EvoPay 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
`registry_ref_no`	String		Gateway transaction identifier
`payload`	String		Field for merchant custom data
`terminal_name`	String		Terminal name
`auth_code`	String		Approval code for UPC integration
`rrn`	String		Transaction unique bank identifier
`cc_mask`	String		Card number mask
`comment`	String		Transaction comment

EvoPay card tokens

EvoPay 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 EvoPay card tokens.

Use tokens to implement recurring payments.

Status codes

EvoPay 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
2011	pending	Confirming OTP for the payment.
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
4021	failure	Number of PIN tries exceeded.
4022	failure	PIN data required.
4023	failure	Insufficient funds on account for refund.
4024	failure	CVV was not provided.
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, RUB, 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
4157	failure	Authorization failed. Please, contact issuer bank.
4158	failure	Transaction rejected. Please, contact issuer bank.
4159	failure	Wrong OTP code. Please try again.
4160	failure	Failed to create transaction
4161	failure	Terminal configuration error.
4162	failure	Terminal limit exceeded.
4163	failure	Payer card error. Try another one.
4164	failure	Receiver card error. Try another one.
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
5031	failure	Invalid PARes Sign.
5050	failure	Transaction failed due to acquirer 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.
5153	failure	Failed to verify the card for participation in 3DSecure.
5154	failure	Payment was refunded.
5155	failure	Cannot process request.
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.
6006	failure	Order has expired.
6007	failure	Payment has cancelled.
6008	failure	Transaction was declined because of balances limitation.
6010	failure	Finmon validation failed.
6011	failure	Transaction is suspended by finmon.

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. See Rate limit.
500	Internal Server Error	Internal error occurred on EvoPay side. Please, contact technical support with specified request and response.
503	Service Unavailable	EvoPay 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 EvoPay technical support.

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

FAQ on errors returned from EvoPay 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

Google Pay

Google Pay™ Integration Guide

About Google Pay

Google Pay is a fast and simple payment method that allows you to make card payments without entering card details for each payment. The card data is safely stored by Google. This payment method is available for all devices (mobile phones and computers), regardless of the operating system and web browser.

EvoPay gives you a way to easily add it on your checkout page, making it more convenient for your clients to pay on your website.

As a merchant, you can use one of two ways, available at EvoPay, to incorporate Google Pay into your payment page:

via EvoPay checkout page
via Google Pay API

Integration

Integration via EvoPay checkout page

Before you start

Please make sure you are registered with EvoPay as a merchant.
Adhere to Google Pay API Acceptable Use Policy and Terms of service

Instruction

This is the easiest way to add Google Pay payment to your payment options - you don’t have to make significant changes to your website or use heavy coding to process payments. Also, you as a merchant don’t have to be PCI DSS compliant - we at EvoPay have got you covered on this.

You just need to use hosted payment option EvoPay offers, in order to redirect your clients to EvoPay payment page. Instruction on configuring correct request for this method is specified at EvoPay documentation page. In this case Google Pay button will be displayed at EvoPay checkout.

Connection with Google Pay API

Before you start

You should register with Google Pay API to proceed with this integration option
Your website should use HTTPS and support TLS protocol
You should be registered with EvoPay as a merchant

Instruction

const posId = '9ff7fa91-9823-4087-874d-a27fdb96c51a'

const paymentsClient = new google.payments.api.PaymentsClient({environment: 'PRODUCTION'});

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'evopay',
    'gatewayMerchantId': posId
  }
};

const allowedCardNetworks = ['MASTERCARD', 'VISA'];
const allowedCardAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS'];

You should register with Google Pay API to proceed with this integration option
Your website should use HTTPS and support TLS protocol
You should be registered with EvoPay as a merchant

Instruction

Token example:

{
    "signature": "MEUCIQDY3wBQyHB4sZcktRoJXKxm+OLcjHzCvdDeGn23oX0kkwIgKznRFZZL+sDMv1b5cuD+YurXMZraYBsr9hbravVY5Ro\u003d",
    "protocolVersion": "ECv1",
    "signedMessage": "{\"encryptedMessage\":\"cI87tLqzqTGyCFnMMCVWcTHw3xhYIK+CEnuQ74K+nlLpCgOlfpScib9jds4sxDtN6CunCqCSMfd/3yHeeRy6aCx1yyqcT4ey6NueeBznprJpkmVVgI1JHWLQt4hzAXMUAcYASYLOabKP9fUZvHkOBDytD531jpzNXa+Spc/zrpGzFKx2C4VU9sC95q9i+ey+kr7ZMNVCOFJPWXu7lKZ105IOOqozJ6/70MKmxP3jM89eeq+/19QnyHjQLXfnQPvQjiUJKGCcRKDLlrb3XoY5ZUUzGfN5eZCLzCVg0hWEbwU+6J7KWYJyW+Wr1r8bagN9zWsrMKhDpsQbHfyzb+yBzFUoxeUgL4a7FeVvEllIcHtqsvTCf6FENV20aF5VLDv5qzUkV+PzTAIbFEuabA0God9UbVCVVv7nM8QFzvRPhzYYFVFTn4JHvL2qZ4pAR9lE+w\\u003d\\u003d\",\"ephemeralPublicKey\":\"BPHLC4sBHpenY1M0ixmiDMuWJTaTJOqggRUwtgBJMcBp28VsxHD7zPI7985x4F5EjMP5y8j/cuUzbe/cGPjOKGk\\u003d\",\"tag\":\"RaXrPOUuc5iw3oxDa0C2MOjaKxgxIRQvwOspmtFV0zU\\u003d\"}"
}

Firstly please review the following documentation in order to get familiar with the integration process:

API documentation for mobile application and for website
Brand guidelines for mobile application and for website

The gateway parameter in the script should have the constant value of evopay.

The value of the gatewayMerchantId parameter should be the identifier of the payment point (pos_id) where the order is made.

In response, Google shall return the PaymentData item, and the field paymentMethodData.tokenizationData.token shall contain a safely encrypted Google Pay Token (a string of characters).

Charging

Google pay request example:

$ curl "https://api.evopay.com.ua/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",
      "payway":           "gpay",
      "cc_token":         "gpay:${base64_google_encrypted_token}",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

To charge the payment card stored under Google Pay, in the direct method request fill in payway and cc_token with the following values:

"payway": "gpay"
"cc_token": "gpay:${base64_google_encrypted_token}"

Further processing of the request is subject to the standard payment process.

Please note that it may be necessary to handle a redirect of the request to the 3D Secure authentication page.

Sandbox

Sandbox client code example:

const posId = '9ff7fa91-9823-4087-874d-a27fdb96c51a'

const paymentsClient = new google.payments.api.PaymentsClient({environment: 'TEST'});

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'evopay',
    'gatewayMerchantId': posId
  }
};

The Google Pay payment method is available also under the Sandbox environment. To get credentials for test environment, please contact support at [email protected].

The gateway parameter in the script should have the constant value of evopay.

The value of the gatewayMerchantId parameter should be the identifier of the payment point (pos_id) where the order is made.

Apple Pay

Apple Pay™ Integration Guide

About Apple Pay

Apple Pay is a mobile payment and digital wallet service by Apple Inc. that allows users to make payments in iOS apps, and on the web without having to enter their payment details each time. It is supported on the iPhone, Apple Watch, iPad and Mac.

As a merchant you can use one of two ways, available at EvoPay to integrate Apple Pay into your payment page:

via EvoPay checkout page
via Apple Pay API

Before you start

Please make sure you are registered with EvoPay as a merchant.
Follow the Acceptable Use Guidelines for Apple Pay on the web
Your website should use HTTPS and support TLS protocol

Integration

Integration via EvoPay checkout page

Request example:

API_KEY=fill_me
API_SECRET=fill_me
POS_ID=fill_me
ENDPOINTS_KEY=fill_me
ORDER_ID="$RANDOM$RANDOM"

$ curl -v 'https://api.evopay.com/api/v1/payment' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H "X-API-Auth:CPAY $API_KEY:$API_SECRET" \
    -H "X-API-Key:$ENDPOINTS_KEY" \
    -H 'X-Requested-With: *' \
    --data-raw '{
      "pos_id":           "'$POS_ID'",
      "order_id":         "'$ORDER_ID'",
      "description":      "Goods '$ORDER_ID'",
      "payway":           "applepay",
      "mode":             "hosted",
      "method":           "auth",
      "amount":           1.5,
      "currency":         "UAH",
      "order_3ds_bypass": "never",
      "products":         []
    }'

With this method, there is no need for additional integrations. To redirect your clients to the EvoPay payment page, use hosted payment option we offer. The instruction on configuring a correct request is specified at the EvoPay documentation page. In this case Apple Pay button will be rendered at the EvoPay checkout.

Connection with Apple Pay API

To add the Apple Pay entitlement to your website or mobile application, you need to have:

An Apple Developer account that is associated with either the Apple Developer Program, or the Apple Developer Enterprise Program.
An individual Merchant ID that identifies you to Apple Pay as a merchant who is able to accept payments.
Brand guidelines reviewed and accepted.

Step 1: Create your merchant identifier

Log in to your Apple Developer account
Go to «Certificates, Identifiers & Profiles» tab
At the section «Identifiers» choose «Merchant IDs»
Add a new Merchant ID by clicking “+” at the top right corner of the page
Fill the requested fields and click «Continue»
Tap «Register» to confirm the data.

Step 2: Create a merchant identity certificate

In «Certificates, Identifiers & Profiles», select Identifiers from the sidebar, then select Merchant IDs from the pop-up menu on the top right.
On the right, select your merchant identifier.
Under Apple Pay Merchant Identity Certificate, click Create Certificate.
Create a certificate signing request on your Mac, and click Continue.
Click Choose File.
In the dialog that appears, select the certificate request file (a file with a .certSigningRequest file extension), then click Choose.
Click Continue.
Click Download.
The certificate file (a file with a .cer file extension) appears in your Downloads folder.

Step 3: Register your merchant domain

This step is only required when you want to enable Apple Pay on the web.

Log in to your Apple Developer account.
In «Certificates, Identifiers & Profiles», select Identifiers from the sidebar, then select Merchant IDs from the pop-up menu on the top right (make sure you select the merchant identifier you created in Step 1).
On the right, select your merchant identifier.
Under Merchant Domains, click Add Domain.
Enter the fully qualified domain name, then click Save.
Click Download, place the downloaded file in the specified location, then click Verify.
Click Done.

Step 4: Verify your merchant domain

Log in to your Apple Developer account.
In «Certificates, Identifiers & Profiles», select Identifiers from the sidebar, then select Merchant IDs from the pop-up menu on the top right (make sure you select the merchant identifier you created in Step 1).
On the right, select your merchant identifier.
Under Merchant Domains, click Verify next to the domain, then follow the instructions.

For information about server requirements for Apple Pay on the web, refer to the Apple Developer portal.

Technical integration to mobile application

1. Technical integration via Apple Pay API To integrate Apple Pay to your mobile application, follow the instruction

2. Technical integration via EvoPay API Send the payment data to EvoPay API. Use the request parameters from EvoPay documentation

"payway": "applepay",
"mode": "direct",
"cc_token": "applepay:${base64_applepay_encrypted_token}"

Technical integration to web

Technical integration via Apple Pay API

Verify your device or browser supports Apple Pay:

if (window.ApplePaySession) {
  console.log("The Apple Pay JS API is available.");

  const canMakePayments = ApplePaySession.canMakePayments();
  console.log("canMakePayments: " + JSON.stringify(canMakePayments));

  const merchantIdentifier = {MERCHANT_IDENTIFIER};
  ApplePaySession
    .canMakePaymentsWithActiveCard(merchantIdentifier);
    .then(canMakePayments => {
      console.log("canMakePayments: " + canMakePayments);
      if (canMakePayments) {...}
    }
}

To integrate Apple Pay to your website, follow the instruction Check your payment ability with Apple Pay.

1. Verify your device or browser supports Apple Pay.

Make a payment structure for the session:

document.getElementById("apple-pay-button").onclick = event => {
  var paymentRequest = {
    currencyCode: 'UAH',
    countryCode: 'UA',
    total: {
      label: {PRODUCT_NAME},
      amount: {PAYMENT_AMOUNT}
    },
    merchantCapabilities: ['supports3DS'],
    supportedNetworks: ['masterCard', 'visa']
  }

var applePaySession = new ApplePaySession(3, paymentRequest);

2. Make a payment structure for the session.

Validate the merchant:

session.onvalidatemerchant = event => {
  validateMerchant(event.validationURL);
    .then(merchantSession => session.completeMerchantValidation(merchantSession));
}

const validateMerchant = validationURL => {
  const headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  };

  var options = = {
    'POST',
    headers,
    body: JSON.stringify({validation_url: validationURL}),
    credentials: 'same-origin'
  };
  return fetch("https://{MERCHANT_VALIDATION_ENDPOINT}", options)
    .then(resp => resp.json())
};

3. Validate the merchant.

Start the session and process your payment:

applePaySession.onpaymentauthorized = event => {
  const token = JSON.stringify(event.payment.token.paymentData);
  console.log("ApplePayPayment token: " + token);
  // submit token to EvoPay API
  session.completePayment(ApplePaySession.STATUS_SUCCESS);
}

applePaySession.begin();

4. Start the session and process your payment.

An example of a dataset returned from Apple Pay:

{
  "version":              "EC_v1",
  "data":                 "zTMZDPumdE7h8oY/+31VMZd60dMaxB...",
  "signature":            "MIAGCSqGSIb3DQEHA...",
  "header": {
    "ephemeralPublicKey": "MFkwEwYHKoZIzj0C...",
    "publicKeyHash":      "3AKqH/wPWdQIBpGIv1PC4uDTbGouPgWbmUlFGiHopig=",
    "transactionId":      "d6e63976191fdf051f7cb95e0e5da70a19c99a5576ececbfc0fd65ad2a7f2f74"
  }
}

5. Send the payment data to EvoPay API. (chapter “Charging”).

Charging

Request example:

API_KEY=fill_me
API_SECRET=fill_me
POS_ID=fill_me
ENDPOINTS_KEY=fill_me
ORDER_ID="$RANDOM$RANDOM"

curl -v 'https://api.evopay.com/api/v1/payment' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-API-Auth:CPAY $API_KEY:$API_SECRET" \
-H "X-API-Key:$ENDPOINTS_KEY" \
-H 'X-Requested-With: *' \
--data-raw '{
     "pos_id":           "'$POS_ID'",
     "order_id":         "'$ORDER_ID'",
     "description":      "Goods '$ORDER_ID'",
     "method":           "auth",
     "amount":           1.50,
     "currency":         "UAH",
     "mode":             "direct",
     "payway":           "applepay",
     "cc_token":         "applepay:eyJ2ZXJzaW9uIjoiRUNfdjEiLC...",
     "order_3ds_bypass": "supported",
     "products":         []
    }'

To charge the payment card stored under Apple Pay, in the direct method request fill in payway and cc_token with the following values:

"payway": "applepay",
"mode": "direct",
"cc_token": "applepay:${base64_applepay_encrypted_token}"

Further processing of the request is subject to the standard payment process. You can find the request parameters by the link.

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",
  "payway":               "applepay",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "success",
  "status_code":          "1000",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "applepay:eyJ2ZXJzaW9uIjoiRUNfdjEiLC...",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "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"
}

Invalid Applepay token response example:

{
  "message":  "Invalid ApplePay token",
  "args":{    
              "code":     "A-400",
              "error_id": "KcJYneJ1owLPeRL5"
  }
}

Widget checkout is used for smooth integration with merchant's websites.

Integration

Include script tag into your website: <script src="https://cdn.evopay.com.ua/widget.js" async></script>

The script is loaded asynchronously.

init() method receive parameters:

let initParams = {
 /* API token issued by EvoPay */
 key: 'hQ8aqcm/RG1RF7MaImmzZUsThYhAVDG6R7kazf9+r7zuoWo6',
 /* Optional amount */
 amount: 350.5,
 /* Currently, only 'inline' mode is supported */
 mode: 'inline',
 /* Optional user language */
 lang: 'uk',
 /* Optional predefined custom style */
 style: 'dark',
 /* Optional widget type */
 type: 'full_card',
 /* Optional customer ip */
 customer_ip: '127.0.0.1',
 /* Optional customer id */
 customer_id: '123',
 /* Optional customer email */
 customer_email: '[email protected]',
 /* Optional customer country */
 customer_country: 'UA',
 /* Optional customer city */
 customer_city: 'Kyiv',
 /* Identifier of HTML element (for 'inline' mode only) */
 selector: 'widget-checkout',
 /* Handler for receiving token data */
 onToken: function(tokenData) {
   /*
     It is guaranteed that`tokenData` will have the following fields:
     {
       "token": "String(<=128)",
       "expires_at": "ISO-8601 DateTime",
       "card_mask": "String(13-19)"
     }
   */
 }
};

let widget = Tranzzo.init(initParams)

Tranzzo#init parameters:

Parameter	Type	Required	Description
`key`	String	✅	API token issued by EvoPay.
`mode`	String	✅	Should be equal to `inline`.
`selector`	String	✅	Identifier of HTML element (e.g. `div id={payform-holder}`) where the widget will be mounted (for `inline` mode).
`onToken`	Function	✅	Callback to invoke when the checkout process is complete.
`amount`	Number		Optional amount to be shown in widget for UX purposes.
`locale`	Object		Locale customization
`lang`	String		Preferred widget localization. Currently supported languages: `ru`, `en`, `uk`.
`style`	String		Optional predefined custom style
`type`	String		Optional widget type. Available options: `full_card`(default) - collect all card credentials (payments), `pan_only` - tokenize only card number (payouts).
`template`	String		Optional custom template. Currently supported templates: `line`
`customer_ip`	String		Optional customer IP address.
`customer_id`	String		Optional customer identifier in merchant's system (required in case of External tokenization).
`customer_email`	String		Optional customer email (required in case of External tokenization).
`customer_country`	String		Optional customer country.
`customer_city`	String		Optional customer city.

locale :

{
  "ru": {
    "cardNumber": "Номер карты",
    "expiryDate": "Срок действия",
    "cvv": "CVV",
    "submit": "Оплатить",
    "yy": "ГГ",
    "mm": "ММ",
    "hints": {
      "cvvHint": "Код расположен на обратной стороне карты"
    },
    "errors": {
      "cardnumber": "Неверный номер карты",
      "expiryDate": "Cрок карты истек",
      "cvv": "Некорректний CVV/CVC2 код"
    }
  }
}

#onToken parameters:

Parameter	Type	Required	Description
`token`	String(≤128)	✅	Token issued by EvoPay. Acceptable for payments via `direct` mode.
`expires_at`	String(26)	✅	ISO-8601 timestamp (`yyyy-mm-ddThh:mm:ss`). End of token life. Example: `2099-12-31T00:00:00`.
`card_mask`	String(13-19)	✅	Mask of tokenized card. Example: `424242******4242`.

Tranzzo#init return special control object with the following API methods:

Method	Parameter	Description
`widget.open()`	none	Render widget
`widget.close()`	none	Force close widget

Integration examples

Eager widget loading:

// Eagerly initialize widget
function __onWidgetReady() {
  let widget = Tranzzo.init({
                    key: 'hQ8aqcm/RG1RF7MaImmzZUsThYhAVDG6R7kazf9+r7zuoWo6',
                    amount: 350.5,
                    mode: 'inline',
                    lang: 'uk',
                    selector: 'widget-checkout',
                    /* Handler for receiving token data */
                    onToken: function(tokenData) {
                      /* Handle token data. For example, create direct payment or add card to wallet */
                      backend.submitPayment(orderId, tokenData);
                    }
                  });
}

const payButton = document.getElementById('btn-pay');

// Open widget on action
payButton.addEventListener('click', function(e) {
  e.preventDefault();

  widget.open();
});

After internal form submission, EvoPay token token will be sent in response to onToken function.

If script was loaded asynchronously, you should wrap init() method in function wrapper: __onWidgetReady

Lazy widget loading

// Create widget entity on button click (for example, radio button option)
function __onWidgetReady() {
  document
    .getElementById('btn-pay')
    .addEventListener('click', function(e) {
        e.preventDefault();
        Tranzzo
          .init({
            key: 'hQ8aqcm/RG1RF7MaImmzZUsThYhAVDG6R7kazf9+r7zuoWo6',
            amount: 350.5,
            mode: 'inline',
            lang: 'uk',
            selector: 'widget-checkout',
            /* Handler for receiving token data */
            onToken: function(tokenData) {
              // Handle token data. For example, create direct payment or add card to wallet.
              backend.submitToken(orderId, tokenData);
            }
          })
          .open();
      }
    );
}

Initialize and open widget instantly

  function __onWidgetReady() {
    Tranzzo.init({ ... }).open();
  }

Example usage:

    document.addEventListener('widget-init-ready', () => {
      widget.open();
    })
    document.addEventListener('widget-init-error', (e) => {
      console.error('error', e.detail.id, e.detail.message)
    });

After widget is successfully initiated, widget-init-ready event is dispatched. Otherwise, in case of error, widget will dispatch widget-init-error error. You can add event listener to this events.

Example of custom style:

/* Change widget style */
.trz-widget .card {
  max-width: 320px;
  box-shadow: 0 8px 50px -6px rgba(84, 84, 120, .26);
  border-radius: 5px;
  padding: 10px 8px;
  border: 1px solid #eee;
  margin: 10px 20px;
}

/* Change submit button background */
.trz-widget .btn-submit {
  background: #3572b0
}

There is an option to customize widget style. You can provide your own CSS style for widget and it will be available for usage as style option.

Receipts

Receipt url is being sent in webhooks. See Webhooks section.