PSP / Wire Transfers (с верификацией)

Ввод денег через карты / Ввод денег банковским переводом (после верификации)

Интеграция заключается во встраивании платежной кнопки в сайт партнера. При клике по этой кнопке производится отправка данных на адрес системы GarryPay.

Информация

Для обеспечения безопасности, отправляемые данные должны быть криптографически подписаны.

Весь рабочий процесс можно разделить на 2 этапа - прохождение верификации пользователя далее KYC и непосредственно сам платеж.

KYC для плательщика требуется пройти один раз. Для этого вы нам передаете id клиента на сайте партнера. Этот id связывается с конкретным партнером и при последующих платежах партнером в указанным ID заново подтверждать свою личность не придется.

Страница KYC и платежная страница вызываются одним и тем-же запросом. KYC показывается если клиент с указанным id еще не валидировался, платежная страница - если уже валидировался.

Подготовительные действия

1. Создайте кошелек в валюте USDT TRC20
2. Для того чтобы в личном кабинете появлялись трансферы при получении фиатных платежей от ваших клиентов, создайте кошелек в EUR.
3. Создайте мерчанта и закрепите перечисленные выше кошельки за ним.

Ограничения

Внимание!

Из следующих стран запрещены переводы (список и текст с предупреждением нужно разместить на видном месте партнерского сайта):

Список стран

- Бурунди
- Центральноафриканская республика
- Куба
- Крым
- Иран
- Ирак
- Ливан
- Ливия
- Северная Корея
- Сомали
- Южный Судан
- Дарфур (Судан)
- Сирия
- Венесуэла
- Йемен
- Албания
- Беларусь
- Босния и Герцеговина
- Болгария
- Демократическая республика Конго
- Хорватия
- Косово
- Македония
- Черногория
- Румыния
- Сербия
- Словения
- Зимбабве
- США
- Туркменистан
- Израиль
- Канада
- Россия

Интеграция через платежную кнопку

Код платежной кнопки должен выглядеть следующим образом:

<form action="https://merch-dev.garrypay.com/basis_payment" method="post">

   <input
    type="hidden"
    name="data"
    value="eyJvcmRlcl9pZCI6IjIyIiwiYW1vdW50IjoiMTAiLCJjdXJyZW5jeSI6IlVTRFQiLCJ1c2VyX2lkIjoiMSIsIm1lcmNoYW50X2lkIjoiMTc0YTNjYjMtYTBlMC00NDUzLThmYTctNTdhMDE2OGM3ZGY3Iiwic2VjcmV0S2V5IjoiZDNkNmViMDBiYTQ0MDcxZmFmMmJlZGU4OWNhMTM4MjRjYWE4MTkwOTc4MjJkOTBiZGJmNGY1NzZjMTI1M2VlNTk2YmQ0NDgzMzJhZTYwYjY2ZDc4In0"
    >

   <input
    type="hidden"
    name="sign"
    value="C1/DssOPem7ChcKUDsKYOjhLwq/DqMK3bDscDjYcwrI9wqhAwojCl8K4wrkNIQ=="
    >

   <input class="btn" type="submit" value="Send">

</form>

Данные для поля data готовятся следующим образом (псевдо-код):

Base64.encode('{
  "merchant_id":  "ef73bed1-2591-4a91-a74e-fe68b4e2e4e0",
  "lang":         "ru",
  "order_id":     "1eas123",
  "user_id":      "122",
  "amount":       "100.32",
  "currency":     "USDT"
}');

Т.е. JSON объект нужно транслировать в строку и закодировать в Base64.

Допустимые поля

Имя	Тип	По умолчанию	Описание
merchant_id	string	Обязательное	ID вашего мерчанта
order_id	string	Обязательное	Уникальный ID ордера
user_id	string	Обязательное	Уникальный ID пользователя (можно использовать email)
email	string	Обязательное	Email пользователя, совершающего оплату
amount	string	Обязательное	Сумма в указанной валюте
currency	string	Обязательное	Валюта в которой платим
lang	string	en	Язык платежного интерфейса, en / ru
callback	string	undefined	URL страницы на которую направляется пользователь после совершения платежа
type	string	Обязательное	Тип оплаты 1 - оплата картой (card payment) 2 - оплата банковским переводом (wire transfer)

Пример кода

JS

import crypto from "crypto";

const data = new Buffer(JSON.stringify({
  merchant_id: "ef73bed1-2591-4a91-a74e-fe68b4e2e4e0"
  order_id: "234-12",
  amount: "102.5",
  currency: "EUR",
  user_id: "123",
  type: "1",
})).toString("base64")

const hmac = crypto.createHmac("sha256", key);
hmac.update(data);
const sign = Buffer.from(hmac.digest("hex")).toString("base64");

PHP

$params = [
  'merchant_id' => 'ef73bed1-2591-4a91-a74e-fe68b4e2e4e0',
  'order_id' => '234-12',
  'user_id' => $user->id,
  'email' => $user->email,
  'amount' => 102.5,
  'currency' => 'EUR',
  'lang' => $lang,
  'type' => 1,
  'callback' => 'https://merchant_site.com/callback_url',
];

$data = base64_encode(json_encode($params));
$sign = base64_encode(hash_hmac('sha256', $data, $secret));

Callback

IP сервера с которого поступают запросы: 185.49.70.96

Информация

Процесс оплаты делится на два этапа

1. Пользователь проходит верификацию

2. Пользователь производит платеж

Так как мы не можем гарантировать что пользователь на этапе верификации укажет тот-же email что вы передали в запросе, в песочнице мы эмулируем ситуацию что пользователь указал другой email. Мы передаем его при успешной верификации на шаге psp_kyc_step3

Для того чтобы перейти ко второму этапу и отладить платежные колбэки, замените в вашем запросе email на тот, который вы получаете в колбэке на этапе psp_kyc_step3 из параметра user_email

Пример запроса

{
  data: 'eyJhY3Rpb24iOiJwMnBfcHJkZXIiLCJkYXRhIjp7ImRhdGEiOnsiYWRfaWQiOjUyMSwiYW1vdW50IjoxMDAsImN1cnJlbmN5IjoiVVNEIiwibWVyY2hhbnRfaWQiOiI5MGYxZDE5OC05MjkzLTQwNjItYjc5NC05NDgxNmM3NWNjODYiLCJjb3VudHJ5IjoicnVzIn0sImVycm9yIjoiTUVSQ0hBTlRBQ0NPVU5UTk9URk9VTkQifX0=',
  sign: 'MGM4NGIyZTY2OWMyNzYzNjFhODcyODdjZGViN2UxMWQ4MzY2ZmNiYmE4ZDRiOTVhMTU1ODMxYTZlYTMwYjJmZg=='
}

data - JSON закодированный в base64

sign - подпись данных

Проверка подлинности данных

• Сгенерируйте подпись используя закодированные в base64 полученные данные и ваш Secret Key
• Сверьте сгенерированную подпись с полученной из запроса.
• Если подпись совпадает, данные подлинные, их можно декодировать и обрабатывать далее

Генерация подписи на основе полученных данных:

JS

//secretKey - Секретный ключ вашего мерчанта
const hmac = crypto.createHmac("sha256", secretKey);
//base64data - Закодированные данные из запроса
hmac.update(base64data);
const sign = Buffer.from(hmac.digest("hex")).toString("base64");

PHP

//$secretKey - Секретный ключ вашего мерчанта
//$base64data - Закодированные данные из запроса
$sign = base64_encode(hash_hmac('sha256', $base64data), $secretKey));

Этапы операции

Каждый callback в объекте данных содержит параметр action. Благодаря этому параметру можно определить на какой стадии процесс верификации / платежа

KYC:

Название action	Описание
psp_kyc_step1	Пользователь начал процесс KYC
psp_kyc_step2	Пользователь отправил форму KYC
psp_kyc_step3	Верификация пройдена

Примеры KYC колбэков

psp_kyc_step1

{
  "action":"psp_kyc_step1",
  "data": {
    "email":"tst_10@test.com",
    "user_id":"tst_10"
  }
}

psp_kyc_step2

{
  "action":"psp_kyc_step2",
    "data": {
      "basis_user_hash":"10_1653901265246",
      "merchant_id":"xxx",
      "user_id":"tst_10",
      "email":"tst_10@test.com",
      "ip":"::ffff:127.0.0.1",
      "bstatus":0
  }
}

psp_kyc_step3

{
  "action":"psp_kyc_step3",
  "data":{
    "basis_hash_id":"10_1653901741508",
    "basis_user_id":"1653901741513",
    "email":"1653901741513@test.com",
    "merchant_id":"xxx",
    "user_id":"tst_10",
    "user_email":"1653901741513@test.com",
    "first_name":"Maxx",
    "last_name":"Xamm",
    "middle_name":"",
    "phone":"",
    "phone2":"",
    "bstatus":10,
    "profile":{
      "access_token":"aat-79874831-39b7-4e00-bb4e-980799cad464",
      "address":"Lenina, 12",
      "address2":"",
      "autocheck_bad_reasons":"video",
      "birthday":"2000-11-11",
      "city":"Kandagar",
      "country":"AF",
      "country_name":"Afghanistan",
      "country_residence":"AF",
      "country_residence_name":"Afghanistan",
      "document_number":"",
      "email":"1653901741513@test.com",
      "email_confirmed":"true",
      "expiry_date":"0001-01-01",
      "first_name":"Maxx",
      "gender":"male",
      "id":"2129803",
      "issue_date":"0001-01-01",
      "last_name":"Xamm",
      "middle_name":"",
      "passport":"\/passport\/83230a4a-2829-463a-8536-968617eb67eb.jpg",
      "passport2":"",
      "phone":"",
      "phone2":"",
      "photo":"\/video\/a61f4f38-2feb-4ae4-8205-751ab883146f.mp4",
      "photo_image":"",
      "user_hash":"67175f61-29d9-4205-9690-f7e1537f3b54",
      "utility_bill":"\/bill\/7f6bb828-4cfe-4a0f-96db-ba474c10c236.jpeg",
      "zip":"123444"
    }
  }
}

Платежные:

Название action	Описание
psp_paymentlink_requested	Платежная ссылка запрошена и будет отправлена на email пользователя который платит (при суммах на которые нет заготовленных ссылок)
psp_paymentlink_sent	Пользователь направлен на форму оплаты
psp_prepayment	Поступила оплата от пользователя
psp_payment_completed	Произведена выплата криптовалюты мерчанту, сделка завершена
psp_cancel	Пользователь нажал кнопку отменить платеж

Примеры платежных колбэков

psp_paymentlink_requested

{
  "action":"psp_paymentlink_requested",
  "data":{
    "order_id":"461",
    "user_id":"tst_10",
    "email":"1653901741513@test.com",
    "merchant_id":"xxx",
    "amount":10,
    "currency":"EUR",
  }
}

psp_paymentlink_sent

{
  "action":"psp_paymentlink_sent",
  "data":{
    "amount":10,
    "currency":"EUR"
  }
}

psp_prepayment

{
  "action":"psp_prepayment",
  "data":{
    "order_id":"463",
    "user_id":"tst_15",
    "email":"tst_15@test.com",
    "amount":10,
    "currency":"EUR",
  }
}

psp_payment_completed

{
  "action":"psp_payment_completed",
  "data":{
    "order_id":"463",
    "user_id":"tst_15",
    "email":"tst_15@test.com",
    "merchant_id":"xxx",
    "amount":10,
    "currency":"EUR",
    "lang":"en",
    "type":"1",
    "callback_url":"https:\/\/test.com\/send-me-callback",
    "ip":"::ffff:127.0.0.1"
  }
}

psp_cancel

{
  "action":"psp_cancel",
  "data":{
    "order_id":"444",
    "user_id":"tst_10",
    "email":"1653668006688@test.com",
    "merchant_id":"xxx",
    "amount":10,
    "currency":"EUR",
    "lang":"en",
    "type":"1",
    "callback_url":"https:\/\/test.com\/send-me-callback"
  }
}

Колбэки рассылаются путем отправки HTTP POST запроса на адрес указанный в настройках мерчанта.

Внимание!

Во время тестирования вы не увидите платежную форму. Процесс оплаты пользователем эмулируется, и вы получаете платежные колбэки, так, как это было бы при оплате пользователем через платежную форму.

Сообщите вашему клиенту, чтобы при оплате он указывал тот-же email что и при верификации, во избежание потери платежа