Navbar
curl

Introduction

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

RozetkaPay 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://deprecated-api.rozetkapay.com/health endpoint:

$ curl https://deprecated-api.rozetkapay.com/health

OK # Expected response

All requests to RozetkaPay API should be sent to https://deprecated-api.rozetkapay.com host in JSON format.

Authentication

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

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

Expected response

[]

RozetkaPay 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

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

Request signing

Requests to RozetkaPay 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}

Rate limits

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

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

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

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

Data types

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

Products

Example of product entity:

{
  "id": "1",
  "url": "https://example.com/products/tv",
  "category": "TV",
  "name": "Brand new TV",
  "description": "Brand new TV with awesome screen",
  "amount": 6600,
  "price_type": "VAT",
  "vat": 6600,
  "qty": 1,
  "payload": "ref_no=1231; discount=false",
  "metadata": {
    "type": "rozetka",
    "tax_system_code": 2,
    "vat_code": 1,
    "customer_phone": "123456",
    "customer_email": "@gmail.com" 
  }
}

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

Parameter definitions (all parameters are optional):

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

API statuses

status field can contain the following values:

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

Create hosted payment

HTTP method: POST

Request parameters:

Request example:

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

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

HTTP/2 303
# .. other headers
Location: https://deprecated-api.rozetkapay.com/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE hosted
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
order_3ds_bypass String 3-D Secure flow option
products Array[Product] Array of products to be paid, empty array can be specified
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronymic
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_lang String Checkout language. Supported values.
customer_country String Customer country
customer_city String Customer city
customer_postal_code String Customer postal code
customer_address String Customer address
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
recipient_fname String Recipient first name
recipient_lname String Recipient last name
recipient_patronym String Recipient patronym
recipient_city String Recipient city
recipient_postal_code String Recipient postal code
recipient_address String Recipient address
recipient_phone String Recipient phone
recipient_email String Recipient email
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
properties JSON (flat) A flat json object for arbitrary additional values (with String values only)
recipient_cc_token String Recipient card token. For p2p-payments either this parameter or recipient_cc_number is mandatory
recipient_cc_number String Recipient card number. For p2p-payments either this parameter or recipient_cc_token is mandatory

Direct payments with card data

HTTP method: POST

Request parameters:

Request example:

$ curl "https://deprecated-api.rozetkapay.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties": {
        "custom_data": "custom_value",
        "custom_data_number" : "100",
        "custom_data_boolean" : "true"
      },
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      },
      "recipient_cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
order_3ds_bypass String 3-D Secure flow option
cc_number CC_NUMBER Card number
exp_month Number Card expiration month field
exp_year Number Card expiration year field
card_cvv String Card CVV
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronymic
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
customer_postal_code String Customer postal code
customer_address String Customer address
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
recipient_fname String Recipient first name
recipient_lname String Recipient last name
recipient_patronym String Recipient patronym
recipient_city String Recipient city
recipient_postal_code String Recipient postal code
recipient_address String Recipient address
recipient_phone String Recipient phone
recipient_email String Recipient email
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.
properties Json (flat) A flat json object for arbitrary additional values (with String values only)
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
recipient_cc_token String Recipient card token. For p2p-payments either this parameter or recipient_cc_number is mandatory
recipient_cc_number String Recipient card number. For p2p-payments either this parameter or recipient_cc_token is mandatory

Response parameters:

Response example:

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

Allowed properties for browser fingerprint

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

Direct payments using Privat24

HTTP method: POST

Request parameters:

Request example:

$ curl "https://deprecated-api.rozetkapay.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat24",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
order_3ds_bypass String 3-D Secure flow option
payway String Optional payway. Use "privat24" for processing direct payments through Privat24
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronymic
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.

Response parameters:

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "privat24",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "[email protected]",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}
Parameter Type Description
payment_id UUID Unique RozetkaPay payment identifier
order_id String Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique RozetkaPay billing identifier
transaction_id UUID RozetkaPay transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
status STATUS Transaction status
status_code STATUS_CODE RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
payway String Optional payway. Use "privat24" for processing direct payments through Privat24
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data
bank_short_name String Bank short name.

Direct payments using Privat Payment by Parts

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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://deprecated-api.rozetkapay.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           300,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat_payparts",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties":       {
        "part_counts": "2"
      },
      "products":         [
        {
          "name"    : "Apple",
          "amount"  : 100,
          "currency": UAH,
          "qty"     : 2
        },
        {
          "name"    : "Pineapple",
          "amount"  : 100,
          "currency": UAH,
          "qty"     : 1
        }
      ]
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount (must be > 300 UAH)
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
order_3ds_bypass String 3-D Secure flow option
payway String Optional payway. Use "privat_payparts" for processing direct payments through Privat Payment by Parts
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronymic
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.
properties.parts_count String The number of parts into which the payment amount is divided (must be > 1 and <= 25)

Response parameters:

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               300,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "privat_payparts",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "[email protected]",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}
Parameter Type Description
payment_id UUID Unique RozetkaPay payment identifier
order_id String Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique RozetkaPay billing identifier
transaction_id UUID RozetkaPay transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
status STATUS Transaction status
status_code STATUS_CODE RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
payway String Optional payway. Use "privat_payparts" for processing direct payments through Privat Payment by Parts
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data
bank_short_name String Bank short name.

Direct payments using RozetkaPay tokens

HTTP method: POST

Request example:

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

Request parameters:

Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
cc_token CC_TOKEN RozetkaPay card token, obtained from previous payments
order_3ds_bypass String 3-D Secure flow option
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronymic
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
properties JSON (flat) A flat json object for arbitrary additional values (with String values only)
recipient_cc_token String Recipient card token. For p2p-payments either this parameter or recipient_cc_number is mandatory
recipient_cc_number String Recipient card number. For p2p-payments either this parameter or recipient_cc_token is mandatory

Response example:

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

Response parameters

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

Credit payments via EvoCredit

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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://deprecated-api.rozetkapay.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           300,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "merchant_order_id":"1111111111",
      "order_3ds_bypass": "always",
      "payway":           "credit_pay",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties":       {
          "another_recipient": "false",
          "acc_change_date": "15.09.2021",  
          "last_captcha_date": "15.09.2021",  
          "delivery_method_id": "1234",                     
          "delivery_service_id": "1234",                     
          "delivery_point_id": "1234",                     
          "delivery_city": "Київ",
          "delivery_street": "Хрещатик",
          "delivery_house": "1",
          "delivery_flat": "42",
          "delivery_datetime": "15.09.2021 16:00-21:00",  
          "recipient_fname": "Іванов",
          "recipient_lname": "Іван",
          "recipient_patronym": "Іванович",
          "recipient_phone": "+380639379992",
          "loan_term" : "12"
      },
      "products":         [
        {
          "name"       : "Apple",
          "amount"     : 100,
          "qty"        : 2,
          "category"   : "Комплекти для хлопчиків",
          "category_id": "4668289"
        },
        {
          "name"       : "Pineapple",
          "amount"     : 100,
          "qty"        : 1,
          "category"   : "Комплекти для дівчаток",
          "category_id": "4668288"
        }
      ],
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount (must be > 300 UAH)
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
merchant_order_id String merchant identified of order
order_3ds_bypass String 3-D Secure flow option
payway String Optional payway. Use "credit_pay" for processing direct payments through RPay CreditPay
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronym
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.
properties JSON A flat JSON with information about delivery and recipient (with String values only)
products Array[Product] Array of products to be paid
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

Properties parameters description

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

Response parameters:

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               300,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://sensebank.ua/onbording_start/12312312312",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "credit_pay",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "[email protected]",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name",
  "gateway_properties": {
    "credit_register_id": "123456789"
  }
}
Parameter Type Description
payment_id UUID Unique RozetkaPay payment identifier
order_id String Unique identifier of order
merchant_order_id String merchant identified of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique RozetkaPay billing identifier
transaction_id UUID RozetkaPay transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
status STATUS Transaction status
status_code STATUS_CODE RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
payway String Optional payway. Use "credit_pay" for processing direct payments through EvoCredit
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer customer patronym
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data
bank_short_name String Bank short name.
gateway_properties String Additional properties provided by credit gateway (with String values only)

Gateway properties parameters description

Parameter Type Description
credit_register_id String Register ID

Payments via Przelewy24

This payment method allow making payments via Przelewy24 system

HTTP method: POST

Request parameters:

Request example:

$ curl "https://deprecated-api.rozetkapay.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           300,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "merchant_order_id":"1111111111",
      "order_3ds_bypass": "always",
      "payway":           "przelewy24",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "products":         [
        {
          "name"       : "Apple",
          "amount"     : 100,
          "qty"        : 2,
          "category"   : "Комплекти для хлопчиків",
          "category_id": "4668289"
        },
        {
          "name"       : "Pineapple",
          "amount"     : 100,
          "qty"        : 1,
          "category"   : "Комплекти для дівчаток",
          "category_id": "4668288"
        }
      ],
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
merchant_order_id String merchant identified of order
order_3ds_bypass String 3-D Secure flow option
payway String Use "przelewy24" for processing direct payments through Przelewy24
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronym
customer_email String Customer email (length must be <= 50)
customer_phone String Customer phone
customer_ip String Customer IP address
customer_postal_code String Customer postal code (length must be <= 6)
customer_address String Customer address (length must be <= 50)
customer_country String Customer country
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.
products Array[Product] Array of products to be paid
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

Response parameters:

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               300,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://przelewy24.ua/onbording_start/12312312312",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "przelewy24",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "[email protected]",
  "customer_phone":       "+380999999999",
  "customer_address":     "Nova str. 25",
  "customer_postal_code": "35-785",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}
Parameter Type Description
payment_id UUID Unique RozetkaPay payment identifier
order_id String Unique identifier of order
merchant_order_id String merchant identified of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique RozetkaPay billing identifier
transaction_id UUID RozetkaPay transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
status STATUS Transaction status
status_code STATUS_CODE RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
payway String Use "przelewy24" for processing direct payments through Przelewy24
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer customer patronym
customer_email String Customer email
customer_phone String Customer phone
customer_postal_code String Customer postal code
customer_address String Customer address
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data
bank_short_name String Bank short name.
cc_type String Type of the credit card: "Business", "Private", "Government"

P2P payments

HTTP method: POST

Request example:

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

Request parameters:

Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD p2p
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of transfer
cc_number CC_NUMBER Card number
exp_month Number Card expiration month field
exp_year Number Card expiration year field
card_cvv String Card CVV
recipient_cc_number String Recipient's card number
order_3ds_bypass String 3-D Secure flow option
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronymic
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
recipient_fname String Recipient first name
recipient_lname String Recipient last name
recipient_patronym String Recipient patronymic
recipient_email String Recipient email
recipient_phone String Recipient phone

Response example:

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

Response parameters

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

Allowed properties for browser fingerprint

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

P2P payments using RozetkaPay tokens

HTTP method: POST

Request example:

$ curl "https://deprecated-api.rozetkapay.com/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 RozetkaPay card token, obtained from previous payments
recipient_cc_number String Recipient's card number
order_3ds_bypass String 3-D Secure flow option
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronymic
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
recipient_fname String Recipient first name
recipient_lname String Recipient last name
recipient_patronym String Recipient patronymic
recipient_email String Recipient email
recipient_phone String Recipient phone
properties JSON (flat) A flat json object for arbitrary additional values (with String values only)

Response example:

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

Response parameters

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

Lookup

HTTP method: POST

Request parameters:

Request example:

$ curl "https://deprecated-api.rozetkapay.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "lookup",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (lookup)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
order_3ds_bypass String 3-D Secure flow option
cc_number CC_NUMBER Card number
exp_month Number Card expiration month field
exp_year Number Card expiration year field
card_cvv String Card CVV
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_patronym String Customer patronymic
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
customer_city String Customer city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.

Response parameters:

Response example:

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

Credit payments

HTTP method: POST

Request example:

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

Request parameters:

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

Response example:

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

Response parameters

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

Allowed properties for credit payment request/response

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

Credit payments using RozetkaPay tokens

HTTP method: POST

Request example:

$ curl "https://deprecated-api.rozetkapay.com/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 RozetkaPay card token, obtained from previous payments
order_3ds_bypass String 3-D Secure flow option
customer_id String Customer's identifier in merchant's system
customer_fname String Customer's first name
customer_lname String Customer's last name
customer_patronym String Customer patronymic
customer_email String Customer's email
customer_phone String Customer's phone
customer_ip String Customer's IP address
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
customer_user_agent String Customer user agent
customer_referrer String Customer referrer
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
properties JSON (flat) A flat json object for arbitrary additional values (with String values only)

Response example:

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

Response parameters

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

Allowed properties for credit payment using RozetkaPay 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://deprecated-api.rozetkapay.com/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 RozetkaPay capture identifier
payment_id UUID RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique RozetkaPay 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 RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay 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://deprecated-api.rozetkapay.com/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 RozetkaPay capture identifier
payment_id UUID RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique RozetkaPay 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 RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay 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://deprecated-api.rozetkapay.com/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 RozetkaPay void identifier
payment_id UUID RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique RozetkaPay 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 RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay 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://deprecated-api.rozetkapay.com/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 RozetkaPay refund identifier
payment_id UUID RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique RozetkaPay 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 RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay 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://deprecated-api.rozetkapay.com/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 RozetkaPay refund identifier
payment_id UUID RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique RozetkaPay 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 RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay 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://deprecated-api.rozetkapay.com/api/v1/p2p-credit" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "description":    "description_1",
      "cc_number":      "4242424242424242",
      "server_url":     "https://callback.blackhole.com/callback/p2p-credit"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be captured (max length is 32 characters)
order_currency CURRENCY Currency of original order
description CURRENCY Currency of original order
cc_number CC_NUMBER Card number
server_url URL Webhook notification will be sent to this URL
recipient_fname String Recipient first name
recipient_lname String Recipient last name
recipient_patronym String Recipient patronymic
recipient_email String Recipient email
recipient_phone String Recipient phone

Response parameters:

Response example:

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

HTTP method: POST

Request parameters:

Request example:

$ curl "https://deprecated-api.rozetkapay.com/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 RozetkaPay card token generated for this card
server_url URL Webhook notification will be sent to this URL
recipient_fname String Recipient first name
recipient_lname String Recipient last name
recipient_patronym String Recipient patronymic
recipient_email String Recipient email
recipient_phone String Recipient phone

Response parameters:

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "credit",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:15.200",
  "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b"
  "fee":                 null
}
Parameter Type Description
operation_id UUID Unique RozetkaPay refund identifier
payment_id UUID RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique RozetkaPay 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 RozetkaPay payment status code
status_description STATUS_DESCRIPTION RozetkaPay 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://deprecated-api.rozetkapay.com/api/v1/p2p-credit" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "credit_amount":  25,
      "description":    "description_1",
      "cc_number":      "4242424242424242",
      "server_url":     "https://callback.blackhole.com/callback/p2p-credit"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be captured (max length is 32 characters)
order_currency CURRENCY Currency of original order
credit_amount Number Amount to be credited
description CURRENCY Currency of original order
cc_number CC_NUMBER Card number
server_url URL Webhook notification will be sent to this URL
recipient_fname String Recipient first name
recipient_lname String Recipient last name
recipient_patronym String Recipient patronymic
recipient_email String Recipient email
recipient_phone String Recipient phone

Response parameters:

Response example:

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

Field Type Example Description
amount Number 3.5984 Amount of payment in alternative currency
currency CURRENCY "USD" Alternative currency
rate Number 27.7905 Conversion rate
commission Number 0.0 Commission on payment in alternative currency
{
  "dcc_rates": [{
      "amount":     3.5984,
      "rate":       27.7905,
      "commission": 0.0,
      "currency":   "USD"
  }]
}

Webhooks

RozetkaPay 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

RozetkaPay sends webhooks to merchant from the following IP address:

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":               "",
    "registry_ref_no":        "9e62565c-ef89-4b7e-bcbd-a96f76af303b",
    "terminal_name":          "Name",
    "rrn":                    "014681438245",
    "recipient_cc_token":     "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
    "recipient_cc_mask":      "424242******4242",
    "dcc_rates":              [
                                                            {
                                                                "amount": 0.0,
                                                                "rate": 0.0,
                                                                "comission": 0.0,
                                                                "currency": "UAH"
                                                            }
                                                        ],
    "traffic_source":         {
                                                            "utm_source": "",
                                                            "utm_mediuum": "",
                                                            "utm_campaign": "",
                                                            "browser": "",
                                                            "device": "",
                                                            "custom": ""
                                                        },
    "auth_code":              "12121212",
    "gateway":                "cc",
    "bank_short_name":        "Name",
    "payment_system":         "VISA",
    "entity_id":              "b20e51e8-278d-408c-9a63-c74e9f4e003a",
    "fc_entity_id":           "ed6a3c74-9dc3-4639-bfe6-ad347d81271b",
    "external_terminal_name": "Terminal Name",
    "customer_patronym":      "Name",
    "recipient_email":        "[email protected]",
    "recipient_phone":        "380123456789",
    "recipient_fname":        "Name",
    "recipient_lname":        "Name",
    "recipient_patronym":     "Name",
    "merchant_order_id":      "b20e51e8-278d-408c-9a63-c74e9f4e003a",
    "receipt_url":            "https://example.url/path/00000000-00000000-00000000-00000000",
    "bank_acq_name":          "Bank Acq Name"
}
Parameter Type Required Description
payment_id String Unique RozetkaPay 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 RozetkaPay billing identifier
transaction_id String Unique RozetkaPay 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 RozetkaPay payment status code
status_description String RozetkaPay payment status code description
cc_mask String Card number mask
cc_token String RozetkaPay card token
cc_token_expiration String Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_phone String Customer phone
fee Object Amount and currency of commission
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time
payload String Payment request payload
registry_ref_no String Gateway transaction identifier
terminal_name String Terminal name
rrn String Transaction unique bank identifier
recipient_cc_token String RozetkaPay recipient card token
recipient_cc_mask String Recipient card number mask
dcc_rates Array? Dcc rates
traffic_source Object Description of the traffic source
auth_code String Approval code for UPC integration <!-- TODO Ask about this one-->
gateway String Payment gateway name
bank_short_name String Bank short name
payment_system String Payment system
entity_id String Identifier of the entity
fc_entity_id String Identifier of the financial entity
external_terminal_name String Terminal name
customer_patronym String Customer patronym
recipient_email String Recipient email
recipient_phone String Recipient phone
recipient_fname String Recipient first name
recipient_lname String Recipient last name
recipient_patronym String Recipient patronym
merchant_order_id String Order id provided by merchant
receipt_url String Url to reciept in pdf format
bank_acq_name String Bank aquier name

Secondary operation webhook parameters

Capture webhook

Capture webhook structure:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000",
    "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b",
  "payload":             "",
  "terminal_name":       "Terminal name",
  "auth_code":           "12121212",
  "rrn":                 "014681438245",
  "cc_mask":             "424242******4242",
  "comment":             ""
}

Capture webhook parameters:

Parameter Type Required Description
operation_id String Unique RozetkaPay capture identifier
payment_id String RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation
transaction_id String Unique RozetkaPay 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 RozetkaPay payment status code
status_description String RozetkaPay payment status code description
fee Object Amount and currency of commission
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time
registry_ref_no String Gateway transaction identifier
payload String Field for merchant custom data
terminal_name String Terminal name
auth_code String Approval code for UPC integration
rrn String Transaction unique bank identifier
cc_mask String Card number mask
comment String Transaction comment

Void webhook

Void webhook structure:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":            "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "void",
  "amount":              100,
  "currency":            "UAH",
  "status":                  "success",
  "status_code":           "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000",
    "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b",
  "payload":             "",
  "terminal_name":       "Terminal name",
  "auth_code":           "12121212",
  "rrn":                 "014681438245",
  "cc_mask":             "424242******4242",
  "comment":             ""
}

Void webhook parameters:

Parameter Type Required Description
operation_id String Unique RozetkaPay void identifier
payment_id String RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation
transaction_id String Unique RozetkaPay 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 RozetkaPay payment status code
status_description String RozetkaPay payment status code description
fee Object Amount and currency of commission
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time
registry_ref_no String Gateway transaction identifier
payload String Field for merchant custom data
terminal_name String Terminal name
auth_code String Approval code for UPC integration
rrn String Transaction unique bank identifier
cc_mask String Card number mask
comment String Transaction comment

Refund webhook

Refund webhook structure:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":            "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":                  "success",    
  "status_code":           "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000",
    "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b",
  "payload":             "",
  "terminal_name":       "Terminal name",
  "auth_code":           "12121212",
  "rrn":                 "014681438245",
  "cc_mask":             "424242******4242",
  "comment":             ""
}

Refund webhook parameters:

Parameter Type Required Description
operation_id String Unique RozetkaPay refund identifier
payment_id String RozetkaPay payment identifier of primary operation
order_id String Merchant's order_id of primary operation
transaction_id String Unique RozetkaPay 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 RozetkaPay payment status code
status_description String RozetkaPay payment status code description
fee Object Amount and currency of commission
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time
registry_ref_no String Gateway transaction identifier
payload String Field for merchant custom data
terminal_name String Terminal name
auth_code String Approval code for UPC integration
rrn String Transaction unique bank identifier
cc_mask String Card number mask
comment String Transaction comment

RozetkaPay card tokens

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

Use tokens to implement recurring payments.

Status codes

RozetkaPay 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
1010 success Contract was signed on client side.

Pending codes

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

Failure codes

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

Init codes

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

Error handling

HTTP statuses

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

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

FAQ on errors returned from RozetkaPay API:

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

Google Pay

Google Pay™ Integration Guide

About Google Pay

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

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

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

Integration

Integration via RozetkaPay checkout page

Before you start

Instruction

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

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

Connection with Google Pay API

Before you start

Instruction

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

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

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

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

Instruction

Token example:

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

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

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

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

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

Charging

Google pay request example:

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

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

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

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

Sandbox

Sandbox client code example:

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

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

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

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

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

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

Apple Pay

Apple Pay™ Integration Guide

About Apple Pay

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

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

Before you start

Integration

Integration via RozetkaPay checkout page

Request example:

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

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

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

Connection with Apple Pay API

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

Step 1: Create your merchant identifier

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

Step 2: Create a merchant identity certificate

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

Step 3: Register your merchant domain

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

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

Step 4: Verify your merchant domain

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

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

Technical integration to mobile application

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

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

Technical integration to web

Technical integration via Apple Pay API

Verify your device or browser supports Apple Pay:

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

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

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

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

1. Verify your device or browser supports Apple Pay.

Make a payment structure for the session:

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

var applePaySession = new ApplePaySession(3, paymentRequest);

2. Make a payment structure for the session.

Validate the merchant:

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

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

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

3. Validate the merchant.

Start the session and process your payment:

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

applePaySession.begin();

4. Start the session and process your payment.

An example of a dataset returned from Apple Pay:

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

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

Charging

Request example:

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

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

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

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

Response example:

 {
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "payway":               "applepay",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "success",
  "status_code":          "1000",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "applepay:eyJ2ZXJzaW9uIjoiRUNfdjEiLC...",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

Invalid Applepay token response example:

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

Widget Checkout

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

Integration

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

The script is loaded asynchronously.

init() method receive parameters:

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

let widget = RPayCardWidget.init(initParams)

RPayCardWidget#init parameters:

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

locale :

{
  "uk": {
    "cardNumber": "Номер карти",
    "expiryDate": "Строк дії",
    "cvv": "CVV",
    "submit": "Сплатити",
    "yy": "ГГ",
    "mm": "ММ",
    "hints": {
      "cvvHint": "Код міститься на зворотній стороні карти"
    },
    "errors": {
      "cardnumber": "Неправильний номер карти",
      "expiryDate": "Строк дії карти закінчився",
      "cvv": "Некорректний CVV/CVC2 код"
    }
  }
}

#onToken parameters:

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

Widget API

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

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

Integration examples

Eager widget loading:

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

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

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

  widget.open();
});

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

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

Lazy widget loading

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

Initialize and open widget instantly

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

Widget Events

Example usage:

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

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

Widget style

Example of custom style:

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

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

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

Receipts

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