API FONDYВерсия 1.0

Расщепление платежей (только Украина)

  1. Тестовые реквизиты
  2. Описание API
      Методы расщепления:
      Схемы расщепления:
  3. Формат запроса
  4. Формат промежуточного ответа
  5. Формат финального ответа
  6. Расчет сигнатуры
  7. Возврат средств
  8. Получение статуса расщепления

Тестовые реквизиты

ID мерчантаКлюч платежаОписание
700001testОсновной (технический) мерчант. От имени этого мерчанта будет строиться запрос на API расщепления и формироваться сигнатура
500001Мерчант контрагента 1, на которого необходимо расщепить первую часть суммы
600001Мерчант контрагента 2, на которого необходимо расщепить вторую часть суммы

 

Описание API

АПИ расчетного центра позволяет расщеплять платеж, оплаченый плательщиком, на несколько получателей — контрагентов.

В примере показана работа с двумя контрагентами, но их может быть больше.

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

Свободные реквизиты счета IBAN

пример:

"receiver":{
       "requisites": {
         "amount": 100,
         "settlement_description": "Назначение платежа для банковского перевода",
         "account": 123456789,
         "jur_name": "ООО Ромашка"
       },
       "type": "bank_account"
     }

Реквизиты мерчанта

пример:

"receiver":{
       "requisites": {
         "amount": 200,
         "settlement_description": "Назначение платежа для банковского перевода",
         "merchant_id": 600001
       },
       "type": "merchant"
     }

Токен карты

пример:

"receiver":{
       "requisites": {
         "rectoken": "da82035bc13c78f2eb74df7caf81decc3601061c",
         "amount": 500
       },
       "type": "rectoken"
     }

Номер карты

пример:

"receiver":{
       "requisites": {
         "amount": 500,
         "card_number": 4444555511116666
       },
       "type": "card"
     }

Возможны 3 схемы работы

Схема 1. С передачей реквизитов расщепления в запросе на создание платежа

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

Шаг 1.

Необходимо посредством сервер-сервер запроса на адрес https://api.fondy.eu/api/checkout/url сформировать URL страницы, на которую будет перенаправлен плательщик для ввода реквизитов карты, либо страница может быть загружена на сайте магазина через JS API или как embedded или любым другим методом интеграции. При создании платежа запрос должен содержать инструкции расщепления в параметре receiver.

Шаг 2.

Перенаправить клиента в браузере на checkout_url или загрузить платежную страницу на сайте мерчанта.

Шаг 3. 

Обработать ответ о результате платежа на страницу ответа в браузере response_url и колбек на серверную страницу server_callback_url

Схема 2. Посредством рекурентного токена, полученного по Схеме 1 или обычной покупки/верификации с передачей параметра required_rectoken = Y

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

Шаг 1.

Необходимо посредством сервер-сервер запроса отправить токен карты плательщика на https://api.fondy.eu/api/recurring (см. документацию Покупка по токену карты)

Ответ с результатом будет получен как в контексте запроса, так и в колбеке на серверную страницу server_callback_url.

Запрос должен содержать инструкции расщепления в параметре receiver

 

Схема 3. Посредством передачи operation_id в запросе на https://api.fondy.eu/api/settlement 

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

При такой схеме взаимодействия, плательщик сначала оплачивает заказ любым из способов интеграции покупки.

Когда мерчанту становятся известны все данные для расщепления, необходимо послать инструкцию в параметре receiver на https://api.fondy.eu/api/settlement 

Шаг 1.

Необходимо осуществить покупку на сумму будущего расщепления любым из методов интеграции.

Шаг 2. 

Обработать ответ о результате платежа на страницу ответа в браузере response_url и колбек на серверную страницу server_callback_url

Шаг 3. 

Послать запрос расщепления на https://api.fondy.eu/api/settlement передав в него параметр operation_id идентичный order_id из шага 1 и инструкции расщепления в параметре receiver.

Формат запроса

Запрос отправляется методом POST в формате JSON на endpoint:

Схема 1:

https://api.fondy.eu/api/checkout/url

Схема 2:

https://api.fondy.eu/api/recurring

Схема 3:

https://api.fondy.eu/api/settlement

Формат запроса

{
 "request": {
   "version": 2.0,
   "data": "ewogIm9yZGVyIjogewogICAic2VydmVyX2NhbGxiYWNrX3VybCI6ICJodHRwOi8vc2l0ZS5jb20vY2FsbGJhY2siLAogICAicmVjdG9rZW4iOiAiOTg5YmI5MzRiZTZiMWEwYjRmZDc1YzU5YWRhZTczOTRlNTZmNGM2MCIsIC8vINC00LvRjyDQodGF0LXQvNCwIDIuINCf0L7RgdGA0LXQtNGB0YLQstC+0Lwg0YLQvtC60LXQvdCwCiAgICJjdXJyZW5jeSI6ICJVQUgiLAogICAiYW1vdW50IjogIjE0MDAiLAogICAib3JkZXJfdHlwZSI6ICJzZXR0bGVtZW50IiwKICAgInJlc3BvbnNlX3VybCI6ICJodHRwOi8vc2l0ZS5jb20vdGVzdC9yZXNwb25zZXBhZ2UvIiwKICAgIm9yZGVyX2lkIjogInRlc3QxMjM0NTYxNDY3NDYyMDk5LjE5IiwKICAgIm9wZXJhdGlvbl9pZCI6ICJ0ZXN0MTIzNDU2MTQ2NzQ2MjA5OS4xOSIsCiAgICJvcmRlcl9kZXNjIjogInRlc3Qgb3JkZXIiLAogICAibWVyY2hhbnRfaWQiOiA3MDAwMDEsCiAgICJyZWNlaXZlciI6IFsKICAgICB7CiAgICAgICAicmVxdWlzaXRlcyI6IHsKICAgICAgICAgImFtb3VudCI6IDEwMCwKICAgICAgICAgInNldHRsZW1lbnRfZGVzY3JpcHRpb24iOiAi0J3QsNC30L3QsNGH0LXQvdC40LUg0L/Qu9Cw0YLQtdC20LAg0LTQu9GPINCx0LDQvdC60L7QstGB0LrQvtCz0L4g0L/QtdGA0LXQstC+0LTQsCIsCiAgICAgICAgICJtZXJjaGFudF9pZCI6IDUwMDAwMQogICAgICAgfSwKICAgICAgICJ0eXBlIjogIm1lcmNoYW50IgogICAgIH0sewogICAgICAgInJlcXVpc2l0ZXMiOiB7CiAgICAgICAgICJhbW91bnQiOiAyMDAsCiAgICAgICAgICJzZXR0bGVtZW50X2Rlc2NyaXB0aW9uIjogItCd0LDQt9C90LDRh9C10L3QuNC1INC/0LvQsNGC0LXQttCwINC00LvRjyDQsdCw0L3QutC+0LLRgdC60L7Qs9C+INC/0LXRgNC10LLQvtC00LAiLAogICAgICAgICAibWVyY2hhbnRfaWQiOiA2MDAwMDEKICAgICAgIH0sCiAgICAgICAidHlwZSI6ICJtZXJjaGFudCIKICAgICB9LAogICAgIHsKICAgICAgICJyZXF1aXNpdGVzIjogewogICAgICAgICAiYW1vdW50IjogMTAwLAogICAgICAgICAic2V0dGxlbWVudF9kZXNjcmlwdGlvbiI6ICLQndCw0LfQvdCw0YfQtdC90LjQtSDQv9C70LDRgtC10LbQsCDQtNC70Y8g0LHQsNC90LrQvtCy0YHQutC+0LPQviDQv9C10YDQtdCy0L7QtNCwIiwKICAgICAgICAgImFjY291bnQiOiAxMjM0NTY3ODksCiAgICAgICAgICJtZm8iOiAxMjM0NSwKICAgICAgICAgIm9rcG8iOiAxMjM0NTY3ODksCiAgICAgICAgICJqdXJfbmFtZSI6ICLQntCe0J4g0KDQvtC80LDRiNC60LAiCiAgICAgICB9LAogICAgICAgInR5cGUiOiAiYmFua19hY2NvdW50IgogICAgIH0sCiAgICAgewogICAgICAgInJlcXVpc2l0ZXMiOiB7CiAgICAgICAgICJyZWN0b2tlbiI6ICJkYTgyMDM1YmMxM2M3OGYyZWI3NGRmN2NhZjgxZGVjYzM2MDEwNjFjIiwKICAgICAgICAgImFtb3VudCI6IDUwMAogICAgICAgfSwKICAgICAgICJ0eXBlIjogInJlY3Rva2VuIgogICAgIH0sCiAgICAgewogICAgICAgInJlcXVpc2l0ZXMiOiB7CiAgICAgICAgICJhbW91bnQiOiA1MDAsCiAgICAgICAgICJjYXJkX251bWJlciI6IDQ0NDQ1NTU1MTExMTY2NjYKICAgICAgIH0sCiAgICAgICAidHlwZSI6ICJjYXJkIgogICAgIH0KICAgXQogfQp9Cg==",
   "signature": "943571471619207087eb57e2b4ef69affd337b1a"
 }
}

data — это base64 кодированный набор данных формата:

{
 "order": {
   "server_callback_url": "http://site.com/callback",
   "rectoken": "989bb934be6b1a0b4fd75c59adae7394e56f4c60", // для Схема 2. Посредством токена
   "currency": "UAH",
   "amount": "1400",
   "order_type": "settlement",
   "response_url": "http://site.com/test/responsepage/",
   "order_id": "test1234561467462099.19",
   "operation_id": "test1234561467462099.19",
   "order_desc": "test order",
   "merchant_id": 700001,
   "receiver": [
     {
       "requisites": {
         "amount": 100,
         "settlement_description": "Назначение платежа для банковского перевода",
         "merchant_id": 500001
       },
       "type": "merchant"
     },{
       "requisites": {
         "amount": 200,
         "settlement_description": "Назначение платежа для банковского перевода",
         "merchant_id": 600001
       },
       "type": "merchant"
     },
     {
       "requisites": {
         "amount": 100,
         "settlement_description": "Назначение платежа для банковского перевода",
         "account": 123456789,
         "jur_name": "ООО Ромашка"
       },
       "type": "bank_account"
     },
     {
       "requisites": {
         "rectoken": "da82035bc13c78f2eb74df7caf81decc3601061c",
         "amount": 500
       },
       "type": "rectoken"
     },
     {
       "requisites": {
         "amount": 500,
         "card_number": 4444555511116666
       },
       "type": "card"
     }
   ]
 }
}

Формат промежуточного ответа

Ответ возвращается в формате JSON в контексте запроса Формат промежуточного ответа https://api.fondy.eu/api/checkout/url

{
 "response": {
   "version": "2.0",
   "data": "eyJvcmRlciI6IHsicGF5bWVudF9pZCI6ICIxNTg2MTkzIiwgImNoZWNrb3V0X3VybCI6ICJodHRwOi8vYXBpLmRldi5mb25keS5ldS9hcGkvY2hlY2tvdXQ/dG9rZW49YWM5NDJlNzA3NjA2NmM2Yjg5Njk4NmNlYTJjNDBhMTlmYmQyNjY4MSJ9fQ==",
   "signature": "9bd5fe9d5f0165f323bae89c3d74e14cce688f3d"
 }
}

где data — это base64 кодированный набор данных, который содежит URL адрес страницы, на которую необходимо перенаправить плательщика

{
 "order": {
   "payment_id": "1586193",
   "checkout_url": "http://api.fondy.eu/api/checkout?token=ac942e7076066c6b896986cea2c40a19fbd26681"
 }
}

Формат финального ответа

Ответ возвращается в формате JSON на server_callback_url и response_url после того, как клиент завершит оплату

Формат финального ответа:

{
 "response": {
   "version": "2.0",
   "data": "eyJvcmRlciI6IHsicnJuIjogIiIsICJtYXNrZWRfY2FyZCI6ICI0NDQ0NTVYWFhYWFg2NjY2IiwgInNlbmRlcl9jZWxsX3Bob25lIjogIiIsICJyZXNwb25zZV9zdGF0dXMiOiAic3VjY2VzcyIsICJzZW5kZXJfYWNjb3VudCI6ICIiLCAiZmVlIjogIiIsICJyZWN0b2tlbl9saWZldGltZSI6ICIiLCAicmV2ZXJzYWxfYW1vdW50IjogIjAiLCAic2V0dGxlbWVudF9hbW91bnQiOiAiMCIsICJhY3R1YWxfYW1vdW50IjogIjIwMDAiLCAib3JkZXJfc3RhdHVzIjogImFwcHJvdmVkIiwgInJlc3BvbnNlX2Rlc2NyaXB0aW9uIjogIiIsICJ2ZXJpZmljYXRpb25fc3RhdHVzIjogIiIsICJvcmRlcl90aW1lIjogIjAyLjA3LjIwMTYgMTU6MjE6MzkiLCAiYWN0dWFsX2N1cnJlbmN5IjogIlVBSCIsICJvcmRlcl9pZCI6ICJ0ZXN0MTIzNDU2MTQ2NzQ2MjA5OS4xOSIsICJwYXJlbnRfb3JkZXJfaWQiOiAiIiwgIm1lcmNoYW50X2RhdGEiOiAiIiwgInRyYW5fdHlwZSI6ICJwdXJjaGFzZSIsICJlY2kiOiAiIiwgInNldHRsZW1lbnRfZGF0ZSI6ICIiLCAicGF5bWVudF9zeXN0ZW0iOiAiY2FyZCIsICJyZWN0b2tlbiI6ICIiLCAiYXBwcm92YWxfY29kZSI6ICI0Nzg0NTAiLCAibWVyY2hhbnRfaWQiOiA2MDAwMDEsICJzZXR0bGVtZW50X2N1cnJlbmN5IjogIiIsICJwYXltZW50X2lkIjogMTU4NjE5MywgInRyYW5zYWN0aW9uIjogW3sic3RhdHVzIjogImFwcHJvdmVkIiwgImFtb3VudCI6IDIwLjAsICJmZWUiOiAwLjAsICJyZXZlcnNhbF9hbW91bnQiOiAwLjAsICJwYXJlbnRfdHJhbl9pZCI6IG51bGwsICJyZWNlaXZlciI6IHt9LCAibWVyY2hhbnRfaWQiOiA2MDAwMDEsICJ0eXBlIjogInB1cmNoYXNlIiwgImlkIjogMTAwMTU0Mzk2MCwgImRvY19ubyI6IG51bGx9XSwgInByb2R1Y3RfaWQiOiAiIiwgImN1cnJlbmN5IjogIlVBSCIsICJjYXJkX2JpbiI6IDQ0NDQ1NSwgInJlc3BvbnNlX2NvZGUiOiAiIiwgImNhcmRfdHlwZSI6ICJWSVNBIiwgImFtb3VudCI6ICIyMDAwIiwgInNlbmRlcl9lbWFpbCI6ICJoZS5sb2xpa29AZ21haWwuY29tIn19",
   "signature": "54aeeadf05b04e2e4097a4aa5907c3a62684d058"
 }
}

где data — это base64 кодированный набор данных, содержащих информацию о всех финансовых операциях и их статусе

{
 "order": {
   "rrn": "",
   "masked_card": "444455XXXXXX6666",
   "sender_cell_phone": "",
   "response_status": "success",
   "sender_account": "",
   "fee": "",
   "rectoken_lifetime": "",
   "reversal_amount": "0",
   "settlement_amount": "0",
   "actual_amount": "2000",
   "order_status": "approved",
   "response_description": "",
   "verification_status": "",
   "order_time": "02.07.2016 15:21:39",
   "actual_currency": "UAH",
   "order_id": "test1234561467462099.19",
   "parent_order_id": "",
   "merchant_data": "",
   "tran_type": "purchase",
   "eci": "",
   "settlement_date": "",
   "payment_system": "card",
   "rectoken": "",
   "approval_code": "478450",
   "merchant_id": 600001,
   "settlement_currency": "",
   "payment_id": 1586193,
   "transaction": [
     {
       "status": "approved",
       "amount": 20.0,
       "fee": 0.0,
       "reversal_amount": 0.0,
       "parent_tran_id": null,
       "receiver": {},
       "merchant_id": 600001,
       "type": "purchase",
       "id": 1001543960,
       "doc_no": null
     }
   ],
   "product_id": "",
   "currency": "UAH",
   "card_bin": 444455,
   "response_code": "",
   "card_type": "VISA",
   "amount": "2000",
   "sender_email": "demo@fondy.eu"
 }
}

Расчет сигнатуры

Параметр signature рассчитывается как функция sha1(password + ‘|’ +data)

Возврат средств

При возврате средств, в параметрах receiver->requisites-> необходимо указывать, с какого мерчанта какая часть основной суммы должна быть удержана.

Например если основная сумма «amount»: «300», то необходимо в запросе указать receiver->receiver->amount таким образом, чтобы все их значения суммарно равнялись основной сумме.

Основная сумма вернется на карту плательщика либо в режиме онлайн, либо по регламенту банка в течении несколько дней, если онлайн реверс невозможен.

POST: https://api.fondy.eu/api/reverse/order_id

Пример параметра data:

{
  "order": {
    "order_id": "test1234561467462099.19",
    "currency": "UAH",
    "amount": "300",
    "merchant_id": "700001",
    "receiver": [
      {
        "requisites": {
          "amount": 100,
          "merchant_id": "500001"
        },
        "type": "merchant"
      },
      {
        "requisites": {
          "amount": 200,
          "merchant_id": "600001"
        },
        "type": "merchant"
      }
    ]
  }
}

где: order_id и merchant_id — идентификаторы оригинального платежа Пример ответа в случае успешного возврата:

{
  "order": {
    "reverse_status": "approved",
    "reversal_amount": "300",
    "order_id": "test1234561467462099.19",
    "response_status": "success",
    "response_code": "",
    "response_description": "",
    "merchant_id": 700001
  }
}

Пример ответа в случае отказа:

{
  "order": {
    "reverse_status": "declined",
    "reversal_amount": "300",
    "order_id": "test1234561467462099.19",
    "response_status": "success",
    "response_code": "1016",
    "response_description": "Merchant not found",
    "merchant_id": 700001
  }
}

Получение статуса расщепления

При создании на стороне FONDY платежной инструкции на расщепление, процесс обработки инструкции проходит в три статуса: created -> processing -> completed

created: инструкция получена и поставлена в очередь на расщепление

processing: создана платежная проводка для отправки в систему СЭП НБУ

completed: система СЭП НБУ подтвердила, что средства зачислены получателям

Для получения статуса расщепления, необходимо использовать API Получение списка транзакций. В параметрах order_id и meerchant_id необходимо передавать значения того ордера, который содержал инструкцию расщепления в параметре receiver.

При успешном расщеплении в списке транзакций будут транзакции с tran_type=settlement и transaction_status=approved которые соответствуют расщепленным сумам.

Расщепление проходит по регламенту в срок, указанный в договоре между мерчантом и FONDY.

 

Хочу принимать платежи со всего мира!