Перейти до основного вмісту

Тестові сценарії

Загальна інформація​

Пропонуємо перед початком обробки реальних оплат пройти тестові кейси. У цьому розділі наведено детальний опис сценаріїв, які дозволяють:

  • перевірити правильність та стабільність роботи вашої інтеграції
  • імітувати різні ситуації здійснення платежів, забезпечуючи готовність системи до обробки реальних транзакцій та запобігаючи можливим помилкам у роботі

Вимоги:​

  1. Створений обліковий запис в Мерчант-порталі та наявний тестовий проєкт з API-ключами.
  2. Налаштований тестовий проєкт командою технічної підтримки.
  3. Здійснена інтеграція.

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

Передумови для початку тесту:

  1. У вас налаштована direct-інтеграція
  2. Створений і активний тестовий проект з API-ключами
  3. Налаштовано опрацювання вебхуків та статус-кодів.
Тест-кейсДія
Одностадійні платежі (Purchase)Одностадійна оплата - платіжний процес, за яким вся сума списується з платника в межах однієї транзакції безпосередньо під час здійснення покупки.
Особливості:
  1. Списання можна виконати з картковими даними (cc_number, exp_month, exp_year, card_cvv), токеном (cc_token) та A/Gpay.
  2. Керування 3ds верифікацією.
  3. Доступна функція повернення коштів після оплати покупки.
  4. Можливість отримання квитанції.
  5. Фіскалізація оплати.
інформація

Якщо сертифікація PCIDSS пройдена в запиті можна передавати карткові дані.
​Якщо сертифікація PCIDSS не пройдена, то в платежах можливо використовувати токени, отримані за допомогою Токенізаційного віджету.

  • Оплата карткою Visa, Mastercard
  1. Cтворіть запит на оплату з передачею cc_number, exp_month, exp_year, card_cvv.
  2. Використовуйте тестові картки відповідно до бренду.
    Як приклад,
    для оплати Visa - 4242 4242 4242 4242
    для оплати Mastercard - 5454 5454 5454 5454
    Платіж може отримати одразу фінальний статус Успіх, або необхідно буде пройти 3ds/otp перевірку. У випадку, якщо "status_description": "3DS verification is required", то відкрити посилання в user_action_url. Підтвердити ACS-перевірку натиснувши CONFIRM.
  3. Отримайте вебхук на вашому сервері. Він містить статус платежу.
  • Оплата гаманцем GPay
  1. Отримайте свій Merchant ID та інтегруйтесь з API Google Pay™, дотримуючись інтеграційної процедури від Google Pay™.
  2. Сформуйте запит на отримання токену, використовуючи наступні значення:
    • параметр gateway у скрипті повинен мати постійне значення finline;
    • значення параметра gatewayMerchantId має відповідати ідентифікатору вашого тестового проєкту (pos_id).
  3. Отримайте у відповіді від Google параметр PaymentData, що містить надійно зашифрований Google Pay™ токен у параметрі paymentMethodData.tokenizationData.token.
  4. Cтворіть запит на оплату з використанням отриманого токена. Для цього у стандартному запиті використайте наступні значення:
    • mode: direct
    • cc_token: gpay:${base64_google_encrypted_token}
    • currency: XCD
    • description: rejected (для неуспішної оплати)
    інформація

    В даному випадку 3ds підтвердження не буде, операція одразу отримає фінальний статус.

  5. Отримайте вебхук на вашому сервері. Він містить статус платежу.
  • Оплата гаманцем Apple Pay
  1. Створіть обліковий запис Apple-розробника, що пов’язаний з однією з таких програм: Apple Developer Program або Apple Developer Enterprise Program.
  2. Отримайте персональний ідентифікатор мерчанта від Apple.
  3. Створіть сертифікати Apple Pay. Для цього надішліть ваш Merchant ID на адресу support@finline.io, вказавши у темі листа «Підключення Applepay».
  4. Зареєструйте та підтвердіть домен, на якому відображатиметься кнопка Apple Pay.
  5. Ініціалізуйте платіжну сесію та сформуйте запит на отримання токену.
  6. Отримайте у відповіді зашифрований Apple Pay™ токен.
  7. Створіть запит на оплату з використанням отриманого токена. Для цього у стандартному запиті використайте наступні значення:
    • mode: direct
    • cc_token: applepay:${base64_applepay_encrypted_token}
    • currency: XCD
    • description: rejected (для неуспішної оплати)
    інформація

    В даному випадку 3ds підтвердження не буде, операція одразу отримає фінальний статус.

  8. Отримайте вебхук на вашому сервері. Він містить статус платежу.
  • Оплата карткою з 3ds/ non 3ds
  1. Cтворіть запит на оплату з передачею карткових даних та передачею параметру order_3ds_bypass
    Використовуйте:
    Для 3DS: order_3ds_bypass=always, тестова картка - 4242 4242 4242 4242
    Без 3DS: order_3ds_bypass=never, тестова картка - 5555 5555 5555 4444
  2. Отримайте вебхук на вашому сервері. Він містить статус платежу.
  • Оплата з блоком продуктів (для фіскалізації платежу)
  1. Cтворіть запит на оплату з передачею даних про продукти
    products - масив продуктів, який необхідно фіскалізувати, може бути декілька товарів в продуктах, але загальна сума price*qty має дорівнювати сумі продуктів amount.
  2. Отримайте вебхук на вашому сервері. Він містить статус платежу.
Повернення (Refund)Повернення (Refund) - це повернення коштів від продавця (або платіжного сервісу) покупцю після того, як платіж уже був проведений.
Повернути кошти можна тільки за платежем, який має статус “Успішний” (success)
Може бути повний (full refund) або частковий (partial refund). Часткових повернень може бути декілька в рамках суми первинної операції.
  • Успішне повне повернення (full refund)
Після успішної оплати (Purchase):
  1. Виконайте повернення (full refund) на всю суму 10 XCD.
    Використовуйте order_id операції, на яку виконується refund (це order_id успішного Purchase)
  2. Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
  • Успішне часткове повернення (partial refund)
Після успішної оплати (Purchase):
  1. Виконайте часткове повернення (partial refund) на суму менше 10 XCD (як, приклад на суму 5, 8 XCD).
    Використовуйте order_id операції, на яку виконується refund (це order_id успішного Purchase)
  2. Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
  • Успішне повне повернення (full refund) за фіскалізованою оплатою.
Після успішної оплати (Purchase):
  1. Виконайте повернення (full refund) на всю суму 10 XCD.
    Для проведення повернення коштів запит також повинен містити відомості про продукт, повернення якого здійснюється.
  2. Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
Отримання квитанціїКвитанція — це документ для вашого клієнта, який підтверджує факт успішної оплати/операції. Може бути у двох форматах: PDF-файл чи raw HTML.
Для отримання квитанції скористайтесь запитом.
Тест повного циклу Одностадійної оплати (Purchase):
Оплата (карткою, A/Gpay) з повним або частковим поверненням.
  1. Ініціюйте запит на оплату на 10 XCD з cc_token або картковими даними.

    Приклад запиту з cc_token:

    $ curl "https://api.finline.io/api/v1/payment"
    -H "Content-Type: application/json"
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"
    -X POST -d '{
    "pos_id": "${POS_ID}",
    "mode": "direct",
    "method": "purchase",
    "amount": 10,
    "currency": "XCD",
    "description": "Order 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",
    "customer_referrer": "https://example.com",
    "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"
    }
    }'
  2. Отримайте відповідь і переконайтесь, що статус платежу Success.
    Приклад відповіді:
    {
    "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": 10,
    "currency": "XCD",
    "description": "Order description",
    "status": "pending",
    "status_code": "2122",
    "status_description": "3DS verification is required to finish the transaction.",
    "user_action_required": true,
    "user_action_url": "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
    "eci": "7",
    "mcc": "4900",
    "options_3ds": "supported",
    "cc_mask": "424242******4242",
    "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
    "cc_token_expiration": "2020-10-10T10:10:22",
    "customer_id": "123",
    "customer_ip": "194.183.171.239",
    "customer_fname": "Tom",
    "customer_lname": "Hanks",
    "customer_email": "tom.hanks@example.com",
    "customer_phone": "+380999999999",
    "customer_country": "UA",
    "result_url": "https://example.com/result",
    "created_at": "2018-10-10T10:10:22.100",
    "processed_at": "2018-10-10T10:10:23.300",
    "fee": {
    "amount": 0,
    "currency": "XCD"
    },
    "percent_fee": {
    "amount": 0,
    "currency": "XCD"
    },
    "fixed_fee": {
    "amount": 0,
    "currency": "XCD"
    },
    "payload": "sale=true",
    "bank_short_name": "Bank name",
    "receipt_url": "https://api.finline.io/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
    }
  3. Опрацюйте вебхук та переконайтесь, що отримані усі обов'язкові параметри, які необхідні для подальшого опрацювання оплати. (Як приклад, status, amount, order_id,fee)
  4. Відправте відповідь 200 OK із свого сервера, що вебхук успішно отриманий.
  5. Створіть запит на повне (10 XCD) або часткове (як, приклад на суму 5 або 8 XCD) повернення.

    Приклад запиту:

    $ curl "https://api.finline.io/api/v1/refund"
    -H "Content-Type: application/json"
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"
    -X POST -d '{
    "pos_id": "${POS_ID}",
    "order_id": "123",
    "order_currency": "XCD",
    "refund_amount": 8,
    "comment": "10101",
    "server_url": "https://callback.blackhole.com/callback/"
    }'
  6. Перевірте статус, що повернення Success.
Очікуваний результат: Кошти повернені на рахунок клієнта.

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

Передумови для початку тесту:

  1. У вас налаштована hosted-інтеграція
  2. Створений і активний тестовий проект з API-ключами
  3. Налаштовано опрацювання вебхуків та статус-кодів.
Тест-кейсДія
Одностадійні платежі (Purchase)
  1. Створіть запит на оплату на суму 10 XCD
    Відповідь зі статусом 303 HTTP на успішний запит містить заголовок location, в який клієнт повинен бути перенаправлений для продовження оплати.
    Приклад відповіді:
    HTTP/2 303
    # .. other headers
    location: https://api.finline.io/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form
  2. Перейдіть за посиланням на чекаут та заповніть усі необхідні поля та натисніть “Сплатити”
    Вигляд платіжної сторінки:
  3. Платіж може отримати одразу фінальний статус Успіх, або необхідно буде пройти 3ds/otp перевірку. У випадку, якщо "status_description": "3DS verification is required", то відкрити посилання в user_action_url. Підтвердити ACS-перевірку натиснувши CONFIRM.
  4. Отримайте вебхук на вашому сервері. Він містить статус платежу.
  • Оплата карткою Visa, Mastercard
  1. Cтворіть запит на оплату
  2. Використовуйте тестові картки відповідно до карткового бренду.
    Як приклад,
    для оплати Visa - 4242 4242 4242 4242
    для оплати Mastercard - 5454 5454 5454 5454
  3. Отримайте вебхук на вашому сервері. Він містить статус платежу.
  • Оплата гаманцями A/Gpay
  1. Cтворіть запит на оплату, використовуючи наступні значення:
    • mode: hosted
    • currency: XCD
    • description: rejected (для неуспішної оплати)
  2. Перейдіть за посиланням — має відкритися чекаут, що міститиме доступні методи оплати.
  3. Оберіть один з методів для оплати: Apple Pay або GPay.
  4. Отримайте вебхук на вашому сервері. Він містить статус платежу.
  • Оплата карткою з 3ds/ non 3ds
  1. Cтворіть запит на оплату з введенням карткових даних та передачею параметру order_3ds_bypass
    Використовуйте:
    Для 3DS: order_3ds_bypass=always, тестова картка - 4242 4242 4242 4242
    Без 3DS: order_3ds_bypass=never, тестова картка - 5555 5555 5555 4444
    Деталі по використанню протоколу 3ds
  2. Отримайте вебхук на вашому сервері. Він містить статус платежу.
  • Оплата з блоком продуктів (для фіскалізації платежу)
  1. Cтворіть запит на оплату з передачею даних про продукти

    products - масив продуктів, який необхідно фіскалізувати, може бути декілька товарів в продуктах, але загальна сума price*qty має дорівнювати сумі продуктів amount.

    Приклад:

    {
    "amount": 6,
    "products": [
    {
    "name": "Apple",
    "amount": 2,
    "currency": "UAH",
    "qty": 3,
    "id": "1",
    "unit": "kg"
    }
    ]
    }
  2. Отримайте вебхук на вашому сервері. Він містить статус платежу.
Повернення (Refund)Повернення (Refund) - це повернення коштів від продавця (або платіжного сервісу) покупцю після того, як платіж уже був проведений.
Повернути кошти можна тільки за платежем, який має статус “Успішний” (success)
Може бути повний (full refund) або частковий (partial refund). Часткових повернень може бути декілька в рамках суми первинної операції.
  • Успішне повне повернення (full refund)
Після успішної оплати (Purchase):
  1. Виконайте повернення (full refund) на всю суму 10 XCD.
    Використовуйте order_id операції, на яку виконується refund (це order_id успішного Purchase)
  2. Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
  • Успішне часткове повернення (partial refund)
Після успішної оплати (Purchase):
  1. Виконайте часткове повернення (partial refund) на суму менше 10 XCD (як, приклад на суму 5, 8 XCD).
    Використовуйте order_id операції, на яку виконується refund (це order_id успішного Purchase)
  2. Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
  • Успішне повне повернення (full refund) за фіскалізованою оплатою.
Після успішної оплати (Purchase):
  1. Виконайте повернення (full refund) на всю суму 10 XCD.
    Для проведення повернення коштів запит також повинен містити відомості про продукт, повернення якого здійснюється.
  2. Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
Отримання квитанціїКвитанція — це документ для вашого клієнта, який підтверджує факт успішної оплати/операції.
Може бути у двох форматах: PDF-файл чи raw HTML.
Способи отримання квитанції:
  1. Після оплати на платіжній сторінці: завантаження PDF-файлу або відправка на Email.
  2. Запит до API
  3. В особистому кабінеті Мерчант-портал
Тест повного циклу Одностадійної оплати (Purchase):
Оплата (карткою, A/Gpay) з повним або частковим поверненням.
  1. Ініціюйте запит на оплату на 10 XCD з тестовою карткою 4242 4242 4242 4242

    Приклад запиту:

    $ curl -i "https://api.finline.io/api/v1/payment"
    -H "Content-Type: application/json"
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"
    -X POST -d '{
    "pos_id": "${POS_ID}",
    "mode": "hosted",
    "method": "purchase",
    "amount": 1,
    "currency": "XCD",
    "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"
    }'
  2. Перейдіть за посиланням на чекаут та заповніть усі необхідні поля та натисніть “Сплатити”
    Приклад платіжної сторінки:
  3. Отримайте відповідь і переконайтесь, що статус платежу Success.
    Вигляд платіжної сторінки:
  4. Створіть запит на повне (10 XCD) або часткове (як, приклад на суму 5 або 8 XCD) повернення.

    Приклад запиту:

    $ curl "https://api.finline.io/api/v1/refund"
    -H "Content-Type: application/json"
    -H "X-API-AUTH: CPAY-HMAC-SHA256 ${API_KEY}:${SIGNATURE}"
    -X POST -d '{
    "pos_id": "${POS_ID}",
    "order_id": "123",
    "order_currency": "XCD",
    "refund_amount": 8,
    "comment": "10101",
    "server_url": "https://callback.blackhole.com/callback/"
    }'
  5. Перевірте статус, що повернення Success.
  6. Отримайте вебхук повернення (refund) на вашому сервері. Перевірте статус, що повернення Success.
Очікуваний результат: Кошти повернені на рахунок клієнта.