| Одностадійні платежі (Purchase) | Одностадійна оплата - платіжний процес, за яким вся сума списується з платника в межах однієї транзакції безпосередньо під час здійснення покупки. Особливості:- Списання можна виконати з картковими даними (cc_number, exp_month, exp_year, card_cvv), токеном (cc_token) та A/Gpay.
- Керування 3ds верифікацією.
- Доступна функція повернення коштів після оплати покупки.
- Можливість отримання квитанції.
- Фіскалізація оплати.
Якщо сертифікація PCIDSS пройдена в запиті можна передавати карткові дані. Якщо сертифікація PCIDSS не пройдена, то в платежах можливо використовувати токени, отримані за допомогою Токенізаційного віджету. |
- Оплата карткою Visa, Mastercard
| - Cтворіть запит на оплату з передачею cc_number, exp_month, exp_year, card_cvv.
- Використовуйте тестові картки відповідно до бренду.
Як приклад, для оплати Visa - 4242 4242 4242 4242 для оплати Mastercard - 5454 5454 5454 5454 Платіж може отримати одразу фінальний статус Успіх, або необхідно буде пройти 3ds/otp перевірку. У випадку, якщо "status_description": "3DS verification is required", то відкрити посилання в user_action_url. Підтвердити ACS-перевірку натиснувши CONFIRM. - Отримайте вебхук на вашому сервері. Він містить статус платежу.
|
| - Отримайте свій Merchant ID та інтегруйтесь з API Google Pay™, дотримуючись інтеграційної процедури від Google Pay™.
- Сформуйте запит на отримання токену, використовуючи наступні значення:
- параметр
gateway у скрипті повинен мати постійне значення finline; - значення параметра
gatewayMerchantId має відповідати ідентифікатору вашого тестового проєкту (pos_id).
- Отримайте у відповіді від Google параметр
PaymentData, що містить надійно зашифрований Google Pay™ токен у параметрі paymentMethodData.tokenizationData.token. - Cтворіть запит на оплату з використанням отриманого токена. Для цього у стандартному запиті використайте наступні значення:
mode: directcc_token: gpay:${base64_google_encrypted_token}currency: XCDdescription: rejected (для неуспішної оплати)
В даному випадку 3ds підтвердження не буде, операція одразу отримає фінальний статус. - Отримайте вебхук на вашому сервері. Він містить статус платежу.
|
- Оплата гаманцем Apple Pay
| - Створіть обліковий запис Apple-розробника, що пов’язаний з однією з таких програм: Apple Developer Program або Apple Developer Enterprise Program.
- Отримайте персональний ідентифікатор мерчанта від Apple.
- Створіть сертифікати Apple Pay. Для цього надішліть ваш Merchant ID на адресу support@finline.io, вказавши у темі листа «Підключення Applepay».
- Зареєструйте та підтвердіть домен, на якому відображатиметься кнопка Apple Pay.
- Ініціалізуйте платіжну сесію та сформуйте запит на отримання токену.
- Отримайте у відповіді зашифрований Apple Pay™ токен.
- Створіть запит на оплату з використанням отриманого токена. Для цього у стандартному запиті використайте наступні значення:
mode: directcc_token: applepay:${base64_applepay_encrypted_token}currency: XCDdescription: rejected (для неуспішної оплати)
В даному випадку 3ds підтвердження не буде, операція одразу отримає фінальний статус. - Отримайте вебхук на вашому сервері. Він містить статус платежу.
|
- Оплата карткою з 3ds/ non 3ds
| - Cтворіть запит на оплату з передачею карткових даних та передачею параметру
order_3ds_bypass Використовуйте: Для 3DS: order_3ds_bypass=always, тестова картка - 4242 4242 4242 4242 Без 3DS: order_3ds_bypass=never, тестова картка - 5555 5555 5555 4444 - Отримайте вебхук на вашому сервері. Він містить статус платежу.
|
- Оплата з блоком продуктів (для фіскалізації платежу)
| - Cтворіть запит на оплату з передачею даних про продукти
products - масив продуктів, який необхідно фіскалізувати, може бути декілька товарів в продуктах, але загальна сума price*qty має дорівнювати сумі продуктів amount. - Отримайте вебхук на вашому сервері. Він містить статус платежу.
|
| Повернення (Refund) | Повернення (Refund) - це повернення коштів від продавця (або платіжного сервісу) покупцю після того, як платіж уже був проведений. Повернути кошти можна тільки за платежем, який має статус “Успішний” (success) Може бути повний (full refund) або частковий (partial refund). Часткових повернень може бути декілька в рамках суми первинної операції. |
- Успішне повне повернення (full refund)
| Після успішної оплати (Purchase):- Виконайте повернення (full refund) на всю суму 10 XCD.
Використовуйте order_id операції, на яку виконується refund (це order_id успішного Purchase) - Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
|
- Успішне часткове повернення (partial refund)
| Після успішної оплати (Purchase):- Виконайте часткове повернення (partial refund) на суму менше 10 XCD (як, приклад на суму 5, 8 XCD).
Використовуйте order_id операції, на яку виконується refund (це order_id успішного Purchase) - Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
|
- Успішне повне повернення (full refund) за фіскалізованою оплатою.
| Після успішної оплати (Purchase):- Виконайте повернення (full refund) на всю суму 10 XCD.
Для проведення повернення коштів запит також повинен містити відомості про продукт, повернення якого здійснюється. - Отримайте вебхук повернення (refund) на вашому сервері. Він містить статус платежу.
|
| Отримання квитанції | Квитанція — це документ для вашого клієнта, який підтверджує факт успішної оплати/операції. Може бути у двох форматах: PDF-файл чи raw HTML. Для отримання квитанції скористайтесь запитом. |
Тест повного циклу Одностадійної оплати (Purchase): Оплата (карткою, A/Gpay) з повним або частковим поверненням. | Ініціюйте запит на оплату на 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" } }'
- Отримайте відповідь і переконайтесь, що статус платежу
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" }
- Опрацюйте вебхук та переконайтесь, що отримані усі обов'язкові параметри, які необхідні для подальшого опрацювання оплати. (Як приклад,
status, amount, order_id,fee) - Відправте відповідь 200 OK із свого сервера, що вебхук успішно отриманий.
Створіть запит на повне (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/" }'
- Перевірте статус, що повернення
Success. Очікуваний результат: Кошти повернені на рахунок клієнта. |