API hutkoВерсия 1.0

(Ця версія застаріла. Використовуйте актуальну версію version 2.0)

Створення платіжної сторінки з індивідуальним дизайном

  1. Базовий приклад дизайну. Оплата карткою, ApplePay, GooglePay.
  2. Приклад стилізації 1
  3. Приклад стилізації 2
  4. Приклад з додатковими полями введення: Номер договору, адреса, ПІБ
  5. Приклад з календарем платежів 1
  6. Приклад з календарем платежів 2
  7. Приклад з розширеним набором методів оплати
  8. Приклад з відправкою форми з платіжними даними за власною подією
  9. Приклад з отриманням JavaScript колбеків
  10. Приклад окремої кнопки ApplePay/GooglePay
  11. Приклад платежу з завчасно створеним ордером
Проект на GitHub: https://github.com/cloudipsp/checkout-vue

Дизайн платіжної сторінки можна стилізувати як звичайний HTML + CSS

Для цього за основу можна взяти вже готовий приклад, вихідний код якого (HTML/CSS/JavaScript) необхідно розмістити на своєму сайті:

Базовий приклад дизайну. Оплата карткою, ApplePay, GooglePay.

 

 

При цьому необхідно підключити JavaScript SDK:

https://pay.hutko.org/latest/checkout.js

https://pay.hutko.org/latest/i18n/ru.js

А також стилі CSS:

https://pay.hutko.org/latest/checkout.css

Конфігурація платіжної сторінки здійснюється параметрами JavaScript коду:

 

var Options = {
	options: {
		methods: ['card', 'banklinks_eu','wallets'],
		cardIcons: ['mastercard', 'visa', 'mir', 'diners-club', 'american-express'],
		fields: false,
		title: 'my_title',
		link: 'https://shop.com',
		fullScreen: true,
		button: true,
		locales: ['en', 'uk'],
		email: true,
		tooltip: true,
		fee: true,
	},
	params: {
		merchant_id: 1396424,
		required_rectoken: 'y',
		currency: 'USD',
		amount: 500,
		order_desc: 'my_order_desc',
		response_url: 'http://shop.com/thankyoupage',
		email: '',
		lang: 'uk'
	},
	messages: {
		uk: {
			card_number: 'Номер картки',
			my_title: 'Призначення платежу',
			my_order_desc: 'Тестовий платіж'
		},
		en: {
			card_number: 'Card number',
			my_title: 'Order description',
			my_order_desc: 'Test order'
		}
	}
}

 

JavaScript конфігурація має таку структуру:

{
  options: {},
  regular: {},
  recurring: {},
  params: {},
  messages: {},
  validate: {}
}

 

options - параметри налаштування візуальної частини платіжної сторінки

 

Назва параметра Тип параметра Значення за замовчуванням Опис
methods  Array  [‘card’, ‘banklinks_eu’,’wallets’]

 Набір груп платіжних методів, такі як: картки, інтернет-банкінг, Apple Pay, Google Pay, локальні платіжні методи, direct debit.

 Підтримувані значення: ‘card’ – банківські картки Visa/MasterCard, ‘banklinks_eu’ – інтернет-банкінги та локальні платіжні методи (iDEAL, Giropay, MyBank, Blick та ін.), ‘wallets’ – Google і Apple Pay..

 Який вигляд має платіжна сторінка з увімкненим максимальним набором платіжних методів можна подивитися в прикладі: Приклад з розширеним набором платіжних методів
fast  Array    
cardIcons  Array  [‘mastercard’, ‘visa’]

 Набір відображуваних логотипів платіжних систем. 

 Підтримувані значення: `mastercard`, `visa`, `prostir`, `diners-club`, `american-express`.
fields  Boolean  false  Включає використання додаткових полів на платіжній сторінці, як показано в Прикладі з додатковими параметрами
title  String    
link  String    
fullScreen  Boolean  true  Визначає, який вигляд матиме платіжна сторінка – компактний, всередині невеликої області сторінки (false) або на всю сторінку (true)
button  Boolean  true Визначає, чи показувати стандартну кнопку оплати , чи використовувати власну. Як використовувати власну кнопку показано в Прикладі з відправленням форми з платіжними даними за власною подією
locales  Array  

 Вибір доступних локалізацій платіжної сторінки.

 Підтримувані значення: `uk`, `en`, `pl`, `lv`, `fr`, `cs`, `sk`.
email  Boolean  false  Визначає, запитувати чи ні email платника.
tooltip  Boolean  true  
apiDomain  String  ‘api.hutko.org’  
fee  Boolean  true  Відображає клієнтську комісію.
css  String    Підтримувані значення: `bootstrap3`, `bootstrap4`, `foundation6`.

 

regular - включає використання календаря платежів на платіжній сторінці, як показано 
в Прикладі з календарем платежів і в Прикладі з календарем платежів 2

 

Назва параметра Тип параметра Значення за замовчуванням Опис
insert Boolean false  Включає календар платежів
open Boolean false  Відобразити та розгорнути параметри вибору регулярності та частоти платежів платнику
hide Boolean false  Приховати можливість платнику змінювати параметри календаря
period Array [‘day’, ‘week’, ‘month’, ‘year’]

 Допустимі параметри регулярності платежу, які може змінити платник

 Підтримувані значення: `day`, `week`, `month`, `year`.

 

recurring - параметризує календар платежів: задає регулярність, частоту, дату старту першого списання, 
дата завершення, суму регулярного списання

 

Назва параметра Тип параметра Значення за замовчуванням Опис
every Integer 1  Частота списань
period String ‘month’

 Регулярність списань

 Підтримувані значення: `day`, `week`, `month`, `year`.
amount Integer 100  Сума регулярних списань, якщо відрізняється від суми основного платежу
start_time String  

 Дата першого списання.

 format YYYY-MM-DD
end_time String  

 Дата завершення списань.

 format YYYY-MM-DD

 

params - параметри замовлення, описані детально в основній документації API

 

Назва параметра Тип параметра Значення за замовчуванням Опис
merchant_id Integer 1396424  
order_desc String    Опис/призначення покупки
amount Integer 100  
currency String    
response_url String    Адреса сторінки мерчанта, на яку буде перенаправлено платника після оплати
lang String  ‘en’

 Мова платіжної сторінки. Підтримувані значення: 

ru – Русский
en – English
uk – Українською
lv – Latviešu
fr – Français
cs – Čeština
sk – Slovenský
ro – Română
es – Español
pl – Polski
it – Italiano
required_rectoken String    Підтримувані значення: `Y`, `N`, `y`, `n`.
verification String    Підтримувані значення: `Y`, `N`, `y`, `n`.
verification_type String    Підтримувані значення: `amount`, `code` 
email String    format email
token String    
offer Boolean  false  
custom Object    

 

messages - локалізація повідомлень і підписів до елементів платіжної сторінки

 

{
  messages: {
    {en}: {
      {id}: {value},
      ...
    },
    ...
  },
}

 

validate - локалізація помилок валідації полів форми введення даних

 

{
  validate: {
    {en}: {
      {id}: {value},
      ...
    },
    ...
  },
}

 

Також за допомогою цієї реалізації є можливість отримання JavaScript колбеків з результатом платежу і кодом відмови. У цьому випадку додасться така конструкція:

var app = fondy("#app", Options)
  .$on("success", function(model) {
    console.log("success event handled");
    
    var order_status = model.data.order.order_data.order_status;

    if (order_status == "approved") {
      console.log("Order is approved. Do somethng on approve...");
    } 
  })
  .$on("error", function(model) {    
    console.log("error event handled");
    var order_status = model.data.order.order_data.order_status;
    var response_code = model.data.error.code;
    var response_description = model.data.error.message;
    if (order_status == "declined") {
      console.log(
        "Order is declined. Do somethng on decline... Last response code is: " +
          response_code +
          ", description: " +
          response_description
      );
    } else if (order_status == "processing") {
      console.log(
        "Order is in processing. Last response code is: " +
          response_code +
          ", description: " +
          response_description
      );
    }
    
  });

Приклад з отриманням JavaScript колбеків

 

 

Нижче представлені приклади готових дизайнів платіжних сторінок у різній стилізації.

Приклад 1

 

 

 

Приклад 2

 

 

 

Приклад із додатковими параметрами

 

 

 

Приклад із календарем платежів

Після першої успішної оплати на стороні hutko буде створено календар із запланованими регулярними платежами. Регулярність і частота задаються в параметрах платіжної сторінки.

 

 

 

Приклад із календарем платежів 2

 

 

 

Приклад із розширеним набором платіжних методів

 

 

 

Приклад з відправленням форми з платіжними даними за власною подією

 

 

 

Приклад з отриманням JavaScript колбеків

 

 

 

Приклад окремої кнопки ApplePay/GooglePay

 

 

 

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

Створюємо order на бекенді:

curl -i -X POST \
 -H "Content-Type:application/json" \
 -d \
'{
  "request": {
    "server_callback_url": "http://myshop/callback/",
    "order_id": "TestOrder_JSSDK_v2",
    "currency": "USD",
    "merchant_id": 1396424,
    "order_desc": "Test payment",
    "lifetime" : 999999
    "amount": 1000,
    "signature": "91ea7da493a8367410fe3d7f877fb5e0ed666490"
  }
}' \
 'https://pay.hutko.org/api/checkout/token'

Отримуємо токен платежу:

{
  "response":{
    "response_status":"success",
    "token":"b40624e6c97306667a46bc4a9439eefd5c142a4e"
  }
}

 

 

Завантажуємо платіжну сторінку, вказуючи token як параметр.

 

Хочу приймати платежі з Hutko!