RozetkaPay payment API specification

RozetkaPay API enables you to integrate online payments into your platform, providing a seamless and secure transaction experience for your users.

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.

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

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.

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:

1. 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.
2. 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.

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.

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.

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.

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: '[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:

locale object example

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

#onToken parameters:

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

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();
  }

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.

Accept online payments using this methods