Overview
RozetkaPay payment API specification ()
Section titled “RozetkaPay payment API specification ()”Introduction
RozetkaPay API enables you to integrate online payments into your platform, providing a seamless and secure transaction experience for your users.
Basic information
Authorization
Main type of authorization is BasicAuth which is always required.
To perform payment requests on behalf of another login, you have to provide it in onBehalfOf header.
If you would like to receive customer’s information with RID auth token - add customerAuth to your request.
Rate Limits
RozetkaPay applies rate limit for its APIs.
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 requests 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 |
Callbacks
A callback is considered successful when the receiving endpoint returns an HTTP 200 status code. All other status codes are treated as a failure. If a status code other than 200 is received, the system will attempt to resend the callback at predefined intervals.
Source verification
Each callback sent by RozetkaPay is signed using the merchant’s password used for the payment operation.
The signature is included with the callback and can be found in the X-ROZETKAPAY-SIGNATURE header.
This header allows you to verify that the callback is from RozetkaPay.
Calculation algorithm:
signature=base64url_encode(sha1($password + base64url_encode($json_body) + $password))Example of signature calculation in python
import base64
import hashlib
def webhook_signature(password: str, data: str, encoding: str = 'UTF-8') -> str:
"""
Generate a webhook signature for verification.
Args:
password (str): Password used for the payment operation.
data (str): String representation of the callback content.
encoding (str, optional): Encoding to be used. Defaults to 'UTF-8'.
Returns:
str: Generated signature.
"""
base64_data = base64.urlsafe_b64encode(data.encode(encoding)).decode(encoding)
signature_data = password + base64_data + password
signature = base64.urlsafe_b64encode(
hashlib.sha1(signature_data.encode(encoding)).digest()
).decode(encoding)
return signature
# Body received from callback
callback_body = '{"name": "john", "age": 21}'
# Result signature
print(webhook_signature('your_password', callback_body))Note: Do not remove the = padding during base64 URL-safe encoding, or the signature will be incorrectly calculated.
Apple Pay & Google Pay
If you wish to provide your customers a better experience, we support online payments with Apple Pay & Google Pay. You have two options to integrate those payment methods:
- Via our checkout (this way you only have to ask for the feature, and the buttons will appear to customers). Refer to Create payment operation for details.
- Embedding button into your website or mobile application - this requires some additional steps from you to generate Apple/Google Pay tokens and pass it to us via Create payment operation.
Apple Pay
To add the Apple Pay entitlement to your website or mobile application, you need to have:
- An Apple Developer account that is associated with either the Apple Developer Program, or the Apple Developer Enterprise Program.
- An individual Merchant ID that identifies you to Apple Pay as a merchant who is able to accept payments.
- Brand guidelines reviewed and accepted.
To integrate Apple Pay to your mobile application, follow the instruction.
To integrate Apple Pay to your website, follow the instruction.
After you completed the integration with Apple Pay for any of your environment (mobile or web), you should receive the following kind of JSON object as a result of Apple Pay call:
{
"version": "EC_v1",
"data": "zTMZDPumdE7h8oY/+31VMZd60dMaxB...",
"signature": "MIAGCSqGSIb3DQEHA...",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj0C...",
"publicKeyHash": "3AKqH/wPWdQIBpGIv1PC4uDTbGouPgWbmUlFGiHopig=",
"transactionId": "d6e63976191fdf051f7cb95e0e5da70a19c99a5576ececbfc0fd65ad2a7f2f74"
}
}This payload should be encoded to Base64 and passed
in customer.payment_method.apple_pay.token field on Create payment operation.
Google Pay
Firstly please review the following documentation in order to get familiar with the integration process:
- API documentation for mobile application and for website
- Brand guidelines for mobile application and for website
The gateway parameter in the script should have the constant value of evopay.
The value of the gatewayMerchantId parameter should be a unique identifier which can be provided via our Support team.
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).
This string should be encoded to Base64 and passed
in customer.payment_method.google_pay.token field on Create payment operation.
Widget
In order to smoothly collect customer’s card details, you have to use our Widget Checkout. It might be embedded into your web page and should provide smooth and secure credit card tokenization flow.
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 = {
/* Widget key 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: 'evo',
/* 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: 'tom.hanks@example.com',
/* 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 | ✅ | Widget key 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 | Object | Optional object to set text for widget elements. |
locale object example
{
"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.
Testing your integrations
Test cards for Aquiring flow
| Card number | Expiration date | CVV | 3D Secure | Result |
|---|---|---|---|---|
| 4242 4242 4242 4242 | any | any | yes | success |
| 5454 5454 5454 5454 | any | any | yes | success |
| 4111 1111 1111 1111 | any | any | no | success |
| 5555 5555 5555 4444 | any | any | no | success |
| 4200 0000 0000 0000 | any | any | yes | rejected |
| 5105 1051 0510 5100 | any | any | yes | rejected |
| 4444 3333 2222 1111 | any | any | no | rejected |
| 5100 0000 2000 2000 | any | any | no | rejected |
| 4000 0000 0000 0044 | any | any | no | insufficient-funds |
Test order details for the PayParts flow. This works only with the ‘stub’ bank and exclusively on the development environment.
| Phone number | Confirmation | Result |
|---|---|---|
| +380930000001 | Webpage | success |
| +380930000002 | Webpage | success |
| +380930000003 | None | success |
| +380930000004 | None | success |
| +380930000007 | Webpage | rejected |
| +380930000008 | Webpage | rejected |
| +380930000009 | None | rejected |
| +380930000010 | None | rejected |
- OpenAPI version: 3.0.3
Authentication
Section titled “ Authentication ”BasicAuth
Section titled “BasicAuth ”Basic Auth consists of login and password combined into a header field in the following form:
Authorization: Basic <credentials>where <credentials> is the Base64 encoding of login and password joined by a single colon :.
You should be provided with login and password by our support team.
Otherwise, if you have already been using other RozetkaPay online payments API,
you can reuse previously provided API_KEY and API_SECRET for X-API-AUTH header
as login and password respectively to authorize into API Gateway.
Security scheme type: basic
customerAuth
Section titled “customerAuth ”User’s personal access token allows to find or/and authorize user in
- customer’s wallet
- subscriptions
- other parts of the API Gateway
You can also see the X-CUSTOMER-RID header. Is a DEPRECATED way to use endpoints with a raw rid for not user-initiated actions like calls from admin panel or background processing. Please, use X-CUSTOMER-AUTH with a special type of access token (authorization_flow = processing) instead.
If you need additional details about “processing” access token, please ask details in RozetkaPay ID Team.
Security scheme type: apiKey
Header parameter name: X-CUSTOMER-AUTH
onBehalfOf
Section titled “onBehalfOf ”Used for partnership mode, when one core account operates with several children
Security scheme type: apiKey
Header parameter name: X-ON-BEHALF-OF