Покупка Частинами
АПІ здійснення угоди з Покупки Частинами
Схема взаємодії під час оплати в магазині:
- Клієнт вибирає товар, який хоче придбати
- Продавець формує кошик платежів клієнта
- Касир оформлює Покупку Частинами для Клієнта
- Магазин надсилає запит до банку, використовуючи сервіс Подання заявки на оплату частинами
- Банк приймає заявку на створення платежу за програмою Покупка Частинами
- Банк ухвалює рішення на оформлення розстрочки протягом 20 секунд і надсилає в мобільний застосунок Push клієнту з інформацією про розстрочку за програмою Покупка Частинами для підтвердження
- Клієнт ознайомлюється з умовами розстрочки та підтверджує відкриття
- Банк надсилає Магазину відповідь(Callback) з результатом оформлення клієнтом Покупки Частинами
- Касир друкує чек
- Магазин завершує замовлення
- Магазин інформує банк про результат завершення операції
Діаграма послідовності::
Схема взаємодії::
Поширені запитання
-
Коли магазин передає товар клієнтові?
- Після набуття статусу WAITING_FOR_STORE_CONFIRM
-
Чи є готові модулі сервісу Покупка Частинами?
- Так, ми знаємо про кілька готових модулів, але звертаємо увагу, що модулі розроблені сторонніми розробниками та не підтримуються Банком. Встановлення та використання на ваш страх та ризик. opencard
Авторизація (підпис запитів / відповідей)
Усі запити та відповіді до АПІ мають бути підписані.
Підпис передається в header параметрі signature
Формула підпису:
encodeBase64(
HmacSHA256(
getBytesUTF-8(
request_body
)
)
)
- encodeBase64 — функція перетворення бінарних даних у Base64 формат wiki,
- HmacSHA256 — функція обчислення хешу підпису даних wiki,
- getBytesUTF-8 — функція переведення рядка в бінарний вигляд (у кодуванні UTF-8) wiki,
- request_body — тіло запиту (або відповіді)
Приклад підпису мовою java:
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
class Main {
public static void main(String[] args) throws Exception {
String key = "the shared secret key here";
String message = "the message to hash here";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(key.getBytes(), "HmacSHA256"));
byte[] hash = hasher.doFinal(message.getBytes());
// to base64
DatatypeConverter.printBase64Binary(hash);
}
}
Приклад підпису на bash
readonly PRIVATE_KEY='the shared secret key here'
readonly REQUEST='the message to hash here'
SIGNATURE=$(echo -n "$REQUEST" | openssl dgst -sha256 -hmac "$PRIVATE_KEY" -binary | base64)
echo "$SIGNATURE"
Приклад підпису на php
<?php
$url = 'https://u2-demo-ext.mono.st4g3.com/api/order/create';
$request_string = '{ "store_order_id": "test_101",
"client_phone": "+380000000001",
"total_sum": 1234.56,
"invoice": {
"date": "2018-10-22",
"number": "1234-1234",
"point_id": 1234,
"source": "INTERNET"
},
"available_programs": [
{
"available_parts_count": [
3,
4,
6,
9
],
"type": "payment_installments"
}
],
"products": [
{
"name": "Телевизор",
"count": 3,
"sum": 9999.99
}
],
"result_callback": "https://store-domain/handle/pay-part/result"
}';
$signature = base64_encode(hash_hmac("sha256", $request_string, "secret_98765432--123-123", true));
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request_string);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'store-id: test_store_with_confirm',
'signature: '.$signature,
'Content-Type: application/json',
'my-header: a66b0275-9872-4fa2-9489-d91b085495a4',
'Accept: application/json'
));
$server_output = curl_exec ($ch);
echo $ch;
echo $server_output;
curl_close ($ch);
?>
Повний приклад мовою java виклику сервісу:
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
public class Main {
private static final String STORE_ID = "test_store_with_confirm";
private static final String STORE_SECRET = "secret_98765432--123-123";
public static void main(String[] args) throws Exception {
new Main().signAndMakeRequest();
}
private void signAndMakeRequest() throws Exception {
final String request = "{\"phone\": \"+380000000001\"}";
String sign = signRequest(request);
final String serviceUrl = "https://u2-demo-ext.mono.st4g3.com/api/client/validate";
URL url = new URL(serviceUrl);
HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
try {
urlConnection.addRequestProperty("store-id", STORE_ID);
urlConnection.addRequestProperty("signature", sign);
urlConnection.addRequestProperty("Content-Type", "application/json");
urlConnection.addRequestProperty("Accept", "application/json");
urlConnection.setDoOutput(true);
try (OutputStream outputStream = urlConnection.getOutputStream()) {
outputStream.write(request.getBytes(StandardCharsets.UTF_8));
}
int responseCode = urlConnection.getResponseCode();
String responseBody = readResponseBody(urlConnection);
System.out.println("Service response code: " + responseCode + ". Response body: " + responseBody);
} finally {
urlConnection.disconnect();
}
}
private String signRequest(String request) throws NoSuchAlgorithmException, InvalidKeyException {
final String ALGORITHM = "HmacSHA256";
Mac mac = Mac.getInstance(ALGORITHM);
mac.init(new SecretKeySpec(STORE_SECRET.getBytes(StandardCharsets.UTF_8), ALGORITHM));
byte[] hash = mac.doFinal(request.getBytes(StandardCharsets.UTF_8));
Base64.Encoder encoder = Base64.getEncoder();
byte[] base64Hash = encoder.encode(hash);
return new String(base64Hash, StandardCharsets.UTF_8);
}
private String readResponseBody(HttpURLConnection urlConnection) throws IOException {
try (InputStream inputStream = urlConnection.getInputStream();
InputStreamReader reader = new InputStreamReader(inputStream, StandardCharsets.UTF_8);
StringWriter sw = new StringWriter()) {
char[] buffer = new char[256];
int n = 0;
while (-1 != (n = reader.read(buffer))) {
sw.write(buffer, 0, n);
}
return sw.toString();
}
}
}
Тестова платформа
Тестова платформа містить тільки 1 магазин і віддає тільки заздалегідь підготовлені ситуації.
store-id: test_store_with_confirm
ключ: secret_98765432--123-123
link: https://u2-demo-ext.mono.st4g3.com
Можливі ситуації:
- Успішне підтвердження заявки. Для цієї ситуації потрібно передати номер телефону клієнта, що закінчується на 1. У цьому випадку через 5 секунд буде кинуто callback про успішне затвердження заявки.
- Заявка, що очікує підтвердження від клієнта. Для цієї ситуації необхідно передати номер телефону клієнта, що закінчується на 2.
- Помилка підтвердження заявки через недостатній ліміт у клієнта. Для цієї ситуації потрібно передати номер телефону клієнта, що закінчується на 3. У цьому випадку через 5 секунд буде кинуто callback про відхилення заявки.
- Заявка підтверджена клієнтом та очікує на підтвердження від магазину (тільки для магазину з двотактовим підтвердженням). Для цієї ситуації необхідно передати номер телефону клієнта, що закінчується на 4.
Предпрод
Тестування на передпроді включає в себе взаємодію API та мобільного застосунку монобанк. Рекомендується після налаштування запитів на пісочниці.
Для тестування на передпроді використовуйте:
store-id: COMFY
ключ: sign_key
link: https://u2-ext.mono.st4g3.com
Увага: умови для заявки:
номер телефону покупця +380951000001
кількість частин - 10
перед тестуванням попередити Сироткіна Олексія у телеграмі
Production
Бойове посилання: https://u2.monobank.com.ua
Використовуйте після успішного проходження тесту та отримання бойових ключів.
Контактні дані менеджерів і фахівців:
менеджер проєкту: Сироткін Олексій
email: oleksii.sirotkin@gmail.com
оперативний контакт в telegram +380672394087