Navbar
curl

Introduction

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

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

Primary operations

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

Secondary operations

Secondary operations are bound to primary.

Controlling 3D-Secure flow

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

API

API URL

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

$ curl https://api.paygames.net/health

OK # Expected response

All requests to PayGames API should be sent to https://api.paygames.net host in JSON format.

Authentication

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

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

Expected response

[]

PayGames 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

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

Request signing

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

OpenSSL HMAC-SHA1 signing example:

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

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

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

SHA1

OpenSSL SHA1 signing example:

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

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

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

Data types

Type name Represented as Values Example
UUID String(36) "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9"
TIMESTAMP String(23) "2020-10-10T10:10:22.100"
MODE String(≤32) direct, hosted Payment modes
METHOD String(≤255) purchase, capture, auth, void Payment methods
URL String(≤2048) https://examle.com/some/path?with=query
IP String(7-45) "8.8.8.8" (IPv4), "FE80::0202:B3FF:FE1E:8329" (IPv6)
GW_ID String(≤1024) 4212523:GssqUUQa
BILLING_ID String(≤1024) 123125124
CURRENCY String(3) "UAH", "USD", "EUR", "RUB"
STATUS String(≤32) "success" (Transaction status)
STATUS_CODE String(4) "1000" (PayGames payment status code)
STATUS_DESCRIPTION String(≤1024) "Transaction is successful." (PayGames 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" (PayGames tokens)

Products

Example of product entity:

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

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

Parameter definitions (all parameters are optional):

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

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.paygames.net/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

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

HTTP/2 303
# .. other headers
Location: https://checkout.paygames.net/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_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_lang String Checkout language. Supported values.
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL

Direct payments with card data

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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",
      "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
order_3ds_bypass String ✅ 3-D Secure flow option
cc_number CC_NUMBER ✅ Card number
exp_month Number ✅ Card expiration month field
exp_year Number ✅ Card expiration year field
card_cvv String ✅ Card CVV
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.
validation_url String Preflight request will be sent to this URL
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
properties JSON Additional specific parameters for integrations

Response parameters:

Response example:

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

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

HTTP method: POST

Request example:

$ curl "https://api.paygames.net/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"
    }'

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 ✅ PayGames card token, obtained from previous payments
order_3ds_bypass String ✅ 3-D Secure flow option
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url String Preflight request will be sent to this URL

Response example:

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

Response parameters

Parameter Type Description
payment_id UUID Unique PayGames 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 PayGames billing identifier
transaction_id UUID PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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 PayGames card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip IP Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.
rnn String Transaction unique bank identifier
authcode String Transaction authentication code
bank_short_name String Bank short name

P2P payments

HTTP method: POST

Request example:

$ curl "https://api.paygames.net/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_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

Response example:

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

Response parameters

Parameter Type Description
payment_id UUID Unique PayGames 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 PayGames billing identifier
transaction_id UUID PayGames 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 PayGames payment status code
status_description String PayGames 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 PayGames 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.

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

HTTP method: POST

Request example:

$ curl "https://api.paygames.net/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 ✅ PayGames 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_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL

Response example:

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

Response parameters

Parameter Type Description
payment_id UUID Unique PayGames 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 PayGames billing identifier
transaction_id UUID PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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 PayGames card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url String Customer will be redirected to this URL after payment.
created_at String Timestamp when transaction was created
processing_time String Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.

Lookup

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.
validation_url String Preflight request will be sent to this URL

Response parameters:

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "lookup",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}
Parameter Type Description
payment_id UUID Unique PayGames 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 PayGames billing identifier
transaction_id UUID PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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 PayGames card token generated for this card
cc_token_expiration String Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String Field for custom data.

Credit payments

HTTP method: POST

Request example:

$ curl "https://api.paygames.net/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_email String Customer's email
customer_phone String Customer's phone
customer_ip String Customer's IP address
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL
properties JSON Additional specific parameters for integrations

Response example:

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

Response parameters

Parameter Type Description
payment_id UUID Unique PayGames 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 PayGames billing identifier
transaction_id UUID PayGames 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 PayGames payment status code
status_description String PayGames 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 PayGames card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer's identifier in merchant's system
customer_ip IP Customer's IP address
customer_fname String Customer's first name
customer_lname String Customer's last name
customer_email String Customer's email
customer_phone String Customer's phone
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.
properties JSON Additional specific parameters for integrations

Allowed properties for credit payment request/response

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

Credit payments using PayGames tokens

HTTP method: POST

Request example:

$ curl "https://api.paygames.net/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 ✅ PayGames card token, obtained from previous payments
order_3ds_bypass String ✅ 3-D Secure flow option
customer_id String Customer's identifier in merchant's system
customer_fname String Customer's first name
customer_lname String Customer's last name
customer_email String Customer's email
customer_phone String Customer's phone
customer_ip String Customer's IP address
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL
properties JSON Additional specific parameters for integrations

Response example:

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

Response parameters

Parameter Type Description
payment_id UUID Unique PayGames 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 PayGames billing identifier
transaction_id UUID PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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 PayGames card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer's identifier in merchant's system
customer_ip String Customer's IP address
customer_fname String Customer's first name
customer_lname String Customer's last name
customer_email String Customer's email
customer_phone String Customer's phone
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday
result_url String Customer will be redirected to this URL after payment.
created_at String Timestamp when transaction was created
processing_time String Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.
properties JSON Additional specific parameters for integrations

Allowed properties for credit payment using PayGames 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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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 PayGames capture identifier
payment_id UUID PayGames payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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 PayGames capture identifier
payment_id UUID PayGames payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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 PayGames void identifier
payment_id UUID PayGames payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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 PayGames refund identifier
payment_id UUID PayGames payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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 PayGames refund identifier
payment_id UUID PayGames payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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

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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://api.paygames.net/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 ✅ PayGames card token generated for this card
server_url URL Webhook notification will be sent to this URL

Response parameters:

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "credit",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:15.200",
  "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b"
  "fee":                 null
}
Parameter Type Description
operation_id UUID Unique PayGames refund identifier
payment_id UUID PayGames payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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.paygames.net/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

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 PayGames refund identifier
payment_id UUID PayGames payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique PayGames 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 PayGames payment status code
status_description STATUS_DESCRIPTION PayGames 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.paygames.net/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.paygames.net/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.paygames.net/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.paygames.net/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

HOSTED METHOD

DIRECT METHOD

CALLBACKS/WEBHOOKS

DCC

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

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

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

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

Preflight requests

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

Format of Preflight request is the same as in webhooks.

Typical flow:

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

Webhooks

PayGames 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

PayGames sends webhooks to merchant from the following IP addresses:

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))

Signature length: 28 characters

Primary operation webhook parameters

Primary operation webhook structure

{
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "111999991",
  "gateway_order_id":    "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
  "billing_order_id":    "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "auth",
  "amount":              0.28,
  "currency":            "UAH",
  "payway":              "privat24",
  "eci":                 "7",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "cc_mask":             "424242******4242",
  "cc_token":            "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
  "cc_token_expiration": "2020-10-10T10:10:22",
  "customer_id":         "123",
  "customer_phone":      "+380999999999",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:22.100",
  "payload":             ""
}
Parameter Type Required Description
payment_id String ✅ Unique PayGames 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 PayGames billing identifier
transaction_id String Unique PayGames 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 PayGames payment status code
status_description String PayGames payment status code description
cc_mask String Card number mask
cc_token String PayGames card token
cc_token_expiration String Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_phone String Customer phone
fee Object Amount and currency of commission
created_at String ✅ Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time
payload String Payment request payload

Secondary operation webhook parameters

Capture webhook

Capture webhook structure:

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

Capture webhook parameters:

Parameter Type Required Description
operation_id String ✅ Unique PayGames capture identifier
payment_id String ✅ PayGames payment identifier of primary operation
order_id String ✅ Merchant's order_id of primary operation
transaction_id String Unique PayGames 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 PayGames payment status code
status_description String PayGames payment status code description
fee Object Amount and currency of commission
created_at String ✅ Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time

Void webhook

Void webhook structure:

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

Void webhook parameters:

Parameter Type Required Description
operation_id String ✅ Unique PayGames void identifier
payment_id String ✅ PayGames payment identifier of primary operation
order_id String ✅ Merchant's order_id of primary operation
transaction_id String Unique PayGames 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 PayGames payment status code
status_description String PayGames payment status code description
fee Object Amount and currency of commission
created_at String ✅ Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time

Refund webhook

Refund webhook structure:

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

Refund webhook parameters:

Parameter Type Required Description
operation_id String ✅ Unique PayGames refund identifier
payment_id String ✅ PayGames payment identifier of primary operation
order_id String ✅ Merchant's order_id of primary operation
transaction_id String Unique PayGames 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 PayGames payment status code
status_description String PayGames 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

PayGames card tokens

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

Use tokens to implement recurring payments.

Status codes

PayGames uses special codes in order to unify gateway transaction statuses.

Successful codes

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

Pending codes

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

Failure codes

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

Init codes

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

Error handling

HTTP statuses

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

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

FAQ on errors returned from PayGames API:

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

Contact maintainers

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

Enrichment API

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

BIN info

Request example:

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

Obtain information about BIN.

HTTP method: GET

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

Response example:

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

Return status 404 if no BIN information.

IP info

Request example:

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

Obtain information about IPv4/IPv6 address location.

HTTP method: GET

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

Response example:

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

Return status 400 if IP address has invalid format.

Return status 404 if no IP address location information.

Receipts

Request example:

$ curl -i "https://https://api.paygames.net/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/report/receipt?format=${FORMAT}" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Response: Raw HTML

PayGames provides an endpoint to render a receipt for a specific payment in HTML or PDF formats.

Parameter definitions

Parameter Type Required Description
POS_ID String ✅ Merchant's identifier (POS_ID)
ORDER_ID String ✅ Merchant's order identifier
FORMAT String ✅ Receipt format (html, pdf)

Request example:

$ curl -i "https://api.paygames.net/api/v1/pos/${POS_ID}/date/${DATE}/report/receipt?format=${FORMAT}" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Response: A zip file with all receipts for the given date.

Also, it is possible to render receipts for all payments for a specific day.

Parameter definitions

Parameter Type Required Description
POS_ID String ✅ Merchant's identifier (POS_ID)
DATE String ✅ Date in yyyy-MM-dd format
FORMAT String ✅ Receipt format (html, pdf)
curl