API інтеграція

Direct-інтеграція

Direct-інтеграція дозволить вам створювати підписку на регулярні платежі, використовуючи власну платіжну сторінку.

Формат взаємодії:

Використання direct-інтеграції потребує проходження сертифікації PCI DSS. У якості альтернативи ви можете скористатися нашим токенізаційним віджетом.

Створення підписки на регулярні платежі передбачає необхідність дотримання стандартних вимог, що зазначено для одностадійних платежів, а також передачу спеціальних параметрів:

Parameter	Type	Required	Description
interval_unit	String	✅	A type of time interval (day, week, month, quarter, year)
interval_count	Integer	✅	A number of time intervals between charges. For example, if the charge should take place once per 3 weeks, the following parameters should be passed: interval_unit: week and interval_count: 3 The max number is 30.
retry_attempts	Integer		A number of retries after unsuccessful charge. The default value is 3. The max number is 7.
retry_interval_hours	Integer		A number of hours between retries. The default values are: IF interval_unit = day retry_interval_hours = 2 ELSE retry_interval_hours = 24 The max values are: IF interval_unit = day retry_interval_hours = 23 ELSE retry_interval_hours = 72
start_date	Date		The date of the first scheduled charge (format: YYYY-MM-DD)
expiry_date	Date		The date of the last scheduled charge (format: YYYY-MM-DD)
time	Time		Time of each recurring charge in UTC. If not provided, the time of the recurring payment creation will be used. (format: HH:MM:SS)
notification_url	URL		The URL to receive notification for recurring payments. If not provided, the server_url value from the initial transaction will be used.
amount	Number		The recurring payment amount if it is different from the one of the initial transaction. If not specified, it will default to the initial transaction amount. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)

Приклад запиту на створення підписки на регулярні платежі:

{
  "pos_id":"'$POS_ID'",
  "mode":"direct",
  "method":"purchase",
  "amount":10,
  "currency":"USD",
  "cc_number":"4111111111111111",
  "exp_month":4,
  "exp_year":42,
  "card_cvv":"123",
  "payway":"pgi_stub",
  "order_id":"'$ORDER_ID'",
  "description":"Testing of recurring",
  "customer_lang":"en",
  "customer_fname":"name",
  "customer_email":"[email protected]",
  "server_url":"https://webhook.site/ab720654-db8a-4d51-9750-8446c295dbd0",
  "order_3ds_bypass":"always",
  "init_recurring":{
    "interval_unit":"day",
    "interval_count":1,
    "retry_attempts":3,
    "retry_interval_hours":1,
    "start_date":"2022-12-13",
    "expiry_date":"2022-12-20",
    "time":"18:42:00",
    "notification_url":"https://webhook.site/ab720654-db8a-4d51-9750-8446c295dbd0"
  }
}

Відповідь, окрім стандартних параметрів одностадійних платежів, також містить низку додаткових параметрів, що стосуються регулярних платежів:

Parameter	Type	Description
recurring.id	String	A unique identifier for all transactions within one recurring payment config
recurring.status	String	The status of the specific recurring payment config (init/active/canceled)

Приклад відповіді на запит на створення підписки на регулярні платежі:

{
  "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",
  "recurring": {
    "id": "r7dAMIRmS~3nCiHVFpSC8",
    "status": "init"
  },
  "result_url":           "https://example.com/result",
  "created_at":           "2023-09-14T14:08:13.509",
  "processed_at":         "2023-09-14T14:08:16.112",
  "payload":              "sale=true",
  "bank_short_name":      "Bank name",
 "receipt_url": "https://cpay.tranzzo.com/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

Окрім того, в запиті обов’язково мають передаватися такі дані щодо фінгерпринту браузера платника:

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

Приклад фінгерпринту браузера платника:

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

Hosted-інтеграція

Hosted-інтеграція дозволить вам при створенні підписки на регулярні платежі прийняти оплату від клієнта з платіжної сторінки Tranzzo.

Формат взаємодії:

Створення підписки на регулярні платежі передбачає необхідність дотримання стандартних вимог, що зазначено для одностадійних платежів, а також передачу спеціальних параметрів:

Parameter	Type	Required	Description
interval_unit	String	✅	A type of time interval (day, week, month, quarter, year)
interval_count	Integer	✅	A number of time intervals between charges. For example, if the charge should take place once per 3 weeks, the following parameters should be passed: interval_unit: week and interval_count: 3 The max number is 30.
retry_attempts	Integer	✅	A number of retries after unsuccessful charge. The default value is 3. The max number is 7.
retry_interval_hours	Integer	✅	A number of hours between retries. The default values are: IF interval_unit = day retry_interval_hours = 2 ELSE retry_interval_hours = 24 The max values are: IF interval_unit = day retry_interval_hours = 23 ELSE retry_interval_hours = 72
start_date	Date		The date of the first scheduled charge (format: YYYY-MM-DD)
expiry_date	Date		The date of the last scheduled charge (format: YYYY-MM-DD)
time	Time		Time of each recurring charge in UTC. If not provided, the time of the recurring payment creation will be used. (format: HH:MM:SS)
notification_url	URL		The URL to receive notification for recurring payments. If not provided, the server_url value from the initial transaction will be used.
amount	Number		The recurring payment amount if it is different from the one of the initial transaction. If not specified, it will default to the initial transaction amount. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)

Приклад запиту на створення підписки на регулярні платежі:

$ curl -i "https://cpay.tranzzo.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}",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      // -----validation fields------
      "mode":             "hosted",
      "method":           "purchase",
      "order_3ds_bypass": "always",
      "init_recurring":   {
            "interval_unit": "month",
            "interval_count": 1,
            "retry_attempts": 3,
            "retry_interval_hours": 24,
            "start_date": "2022-10-03",
            "expiry_date": "2022-10-10",
            "time": "10:00:00",
            "notification_url": "https://webhook.site/ab720654-db8a-4d51-9750-8446c295dbd0"
            "amount": 20
      }
    }'

Відповідь зі статусом 303 HTTP на успішний запит містить заголовок Location, в який клієнт повинен бути перенаправлений для продовження оплати.

Приклад відповіді:

HTTP/2 303
# .. other headers
Location: https://cpay.tranzzo.com/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form

Наступні кроки

Тестування процесу створення підписки:

• Створіть обліковий запис у Мерчант-порталі.
• Використовуйте автентифікаційні дані тестового проєкту.
• Налаштуйте вебхуки.
• Скористайтеся даними для тестування для отримання різних кодів результатів операцій
• Опрацьовуйте отримані помилки.

Більше деталей — у контрольному списку інтеграції.

Вихід в онлайн:

1. Створіть робочий проєкт у мерчант-порталі.
2. При direct-інтеграції: пройдіть сертифікацію PCI DSS або підключіть імплементувати токенізаційний віджет.
3. Коли наша команда Комплаєнсу активує робочий проєкт, замініть автентифікаційні дані тестового проєкту на дані робочого.

Дивіться також:

• Скасування регулярних платежів
• Повернення за регулярними платежами
• Отримання відомостей про підписки на регулярні платежі
• Платіжний віджет
• Токенізаційний віджет
• Hosted-чекаут