Для выполнения платежей через терминал необходимо получить персональную ссылку для открытия терминала. Ссылка содержит персональный код, который регистрируется в терминале и позволит открыть терминал и выполнить платеж. Время жизни ссылки ограничено, на сегодняшний день оно составляет 60 минут. Если в течение этого времени не был произведен платеж, то персональный код для открытия сессии становится недействительным.
Каждое приложение, которое выполняет запрос на получение персональной ссылки для открытия сессии терминала должно быть зарегистрировано в системе B2B Backoffice. Приложение, из которого выполняется получение персональной ссылки для открытия сессии терминала, должно иметь Client ID приложения, из которого выполняется запрос, а также секретный ключ, при помощи которого необходимо формировать подпись запроса.
URL:
- Тестовое окружение:
https://payment-terminal-form.sandbox.idynsys.org/api/auth/personal-url
- Продакшн окружение:
https://pay.trustedskycenter.com/api/auth/personal-url
Метод запроса: POST
Заголовки запросе:
X-Client-Id: (обязательно). Идентификатор приложения, получаемый при регистрации приложения в системе B2B BackofficeX-Authorization-Sign: (обязательно). Подпись запроса по секретному ключу приложения, который определяется в системе B2B Backoffice. Подпись формируется по алгоритму, описанному на странице “Подпись”Content-Type: (обязательно) Тип содержимого запроса, должно быть 'application/json'.
Структура тела запроса:
Тело запроса должно быть в формате JSON и иметь следующую структуру:
curl --location 'https://payment-terminal-form.sandbox.idynsys.org/api/auth/personal-url' \
--header 'X-Client-Id: {{xClientId}}' \
--header 'X-Authorization-Sign: {{xAuthorizationSign}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"paymentInfo": {
"type": "withdrawal",
"amount": 5001,
"currency": "NGN",
"merchantOrderId": "234345",
"merchantOrderDescription": "withdrawal for order"
},
"sessionSettings": {
"clientTheme": "dark",
"clientLanguage": "eng",
"visibleMethods": [
{
"paymentMethodName": "BankTransfer",
"communicationType": "h2h"
}
]
},
"urls": {
"redirectSuccess": "https://website.com/redirectSuccess",
"redirectFail": "https://website.com/redirectFail",
"return": "https://website.com/return",
"callback": "https://website.com/callback"
},
"userInfo": {
"externalId": "112345",
"trafficSegment": "VIP",
"trafficType": "ftd",
"riskGroupCode": "LOW",
"firstName": "Ivan",
"lastName": "Ivanov"
},
"userAccount": {
"pan": "8310021622",
"bankName": "NORTH EAST SMALL FINANCE BANK LIMITED"
}
}'
Поля в paymentInfo:
| Наименование |
Обязательное? |
Тип |
Описание |
paymentInfo.type |
Да |
string |
Тип платежа - withdrawal |
paymentInfo.amount |
Нет |
float |
Сумма платежа. Допустимые значения - больше 0. Если передается значение с дробной частью, то оно может округляться по правилам платежной системы.- Если клиент не передаёт
paymentInfo.amount или он равен 0, то сумма выбирается внутри терминала - на экране, по тем лимитам и вариантам, которые заданы в presetAmounts. - Лимиты для методов оплаты задаются в админке. Есть возможность указать быстрые суммы для выбора через
presetAmounts в sessionSettings. - Если amount передан (любое значение > 0) - терминал использует эту сумму как фиксированную — пользователь не сможет изменить её на экране. presetAmounts при данном условии игнорируется (если даже передан).
|
paymentInfo.currency |
Да |
string |
3-х значный буквенный код валюты платежа по ISO 4217. |
paymentInfo.merchantOrderId |
Да |
string |
Идентификатор ордера клиента (организации заказчика). |
paymentInfo.merchantOrderDescription |
Да |
string |
Описание ордера клиента. |
Поля в userInfo:
| Наименование |
Обязательное? |
Тип |
Описание |
userInfo.externalId |
Да |
string |
Идентификатор пользователя, который выполняет платеж. |
userInfo.trafficType |
Да |
string |
Тип трафика. Возможные значения:- ftd (первичный трафик для непроверенных пользователей делающих оплату первый раз)
- trusted (для доверенных пользователей)
|
userInfo.trafficSegment |
Нет |
string |
Сегмент трафика для текущего пользователя |
userInfo.riskGroupCode |
Нет |
string |
Код рисковой группы пользователя |
userInfo.firstName |
Да |
string |
Имя плательщика латиницей. |
userInfo.lastName |
Да |
string |
Фамилия плательщика латиницей. |
Поля в userAccount (не обязательное):
| Наименование |
Обязательное? |
Тип |
Описание |
userAccount.pan |
Да |
string |
Номер электронного или банковского счёта |
userAccount.bankName |
Да |
string |
Код и название банка, в который выполняется платеж.Возможные значения:| Код(значение поля bankName) | Название банка |
|---|
| 9payment | 9 Payment Service Bank | | abbeymb | ABBEY MORTGAGE BANK | | abmfb | AB MICROFINANCE BANK | | aboveonlymfb | ABOVE ONLY MICROFINANCE BANK | | abumfb | ABU MICROFINANCE BANK | | access | ACCESS BANK PLC | | accessmobile | AccessMobile | | accessmoney | Access Money | | accionmfb | ACCION MFB | | addossermfb | ADDOSSER MFBB | | adeyemimfb | ADEYEMI COLLEGE STAFF MICROFINANCE BANK | | advanslafayettemfb | ADVANS LA FAYETTE MFB | | agmb | AG MORTGAGE BANK PLC | | akumicrofinancebank | Aku Microfinance Bank | | albarakahmfb | AL-BARKAH MFB | | alekunmfb | ALEKUN MICROFINANCE BANK | | alertmfb | ALERT MFB | | alhayatmfb | ALHAYAT MFB | | allworkersmfb | ALLWORKERS MFB | | alphakapitalmfb | ALPHAKAPITAL MFB | | amjuuniquemfb | AMJU MFB | | ammlmfb | AMML MFB | | amuchamicrofinancebank | AMUCHA MFB | | arisemfb | ARISE MFB | | asosavings | ASO SAVINGS AND LOANS | | astrapolarismfb | ASTRAPOLARIS MFB | | auchimfb | AUCHI MICROFINANCE BANK | | bainesmfb | BAINES CREDIT MFB | | balogunmfb | BALOGUN GAMBARI MFB | | bayeromfb | BAYERO MICROFINANCE BANK | | bckashmfb | BC KASH MFB | | beststarmicrofinancebank | Beststar MFB | | betaaccessyello | BETA-ACCESS YELLO | | bipcmfb | BIPC MICROFINANCE BANK | | boctrustmfb | BOCTrust Micro-finance Bank | | boctrustmicrofinancebanklimited | BOCTRUST MICROFINANCE BANK | | bosakmfb | BOSAK MFB | | bowenmfb | BOWEN MFB | | brentmb | BRENT MORTGAGE BANK | | brethrenmfb | BRETHREN MICROFINANCE BANK | | bridgewaymfb | Bridgeway Microfinance Bank | | brightwaymfb | BRIGHTWAY MFB | | cbn | CENTRAL BANK OF NIGERIA | | cellulant | CELLULANT | | cemsmfb | CEMCS MFB | | chamsmobile | ChamsMobile | | chikummfb | CHIKUM MICROFINANCE BANK | | citibankng | Citibank Nigeria LTD | | citmfb | CIT MICROFINANCE BANK | | cmfb | Coronation Merchant Bank | | consumermfb | CONSUMER MFB | | contecglobal | CONTEC GLOBAL | | covenantmfb | Covenant | | creditafriquemfb | CREDIT AFRIQUE MFB | | daylightmfb | DAYLIGHT MICROFINANCE BANK | | diamond | DIAMOND BANK PLC | | eagleflightmfb | EAGLE FLIGHT MFB | | eartholeum | EARTHOLEUM | | ebarcsmfb | E-BARCS MFB | | eco | ECOBANK NIGERIA PLC | | ecobankexpressaccount | EcoBank Express Account | | ecomobile | EcoMobile | | edfinmfb | EDFIN MFB | | ekondomfb | EKONDO MICROFINANCE BANK | | emeralmfb | EMERALDS MFB | | empiretrustmfb | EMPIRETRUST MICROFINANCE BANK | | enterprise | Enterprise Bank | | esanmfb | ESAN MFB | | esoemfb | ESO-E MICROFINANCE BANK | | etranzact | eTranzact | | evangelmfb | EVANGEL MFB | | evergreenmfb | EVERGREEN MICROFINANCE BANK | | eyowomfb | EYOWO MICROFINANCE BANK | | fairmoneymfb | Fairmoney Microfinance | | fastmfb | FAST MFB | | fbnmortgagesltd | FBN Mortgages Limited | | fbnquestmeb | FBNQUEST MERCHANT BANK | | fcmbeasyaccount | FCMB EASY ACCOUNT | | fctmfb | FCT MFB | | federalPolynasarawamfb | FEDERALPOLY NASARAWAMFB | | fedunidustemfb | FEDERAL UNIVERSITY DUTSE MICROFINANCE BANK | | fet | FET | | fets | FETS | | ffsmfb | FFS MICROFINANCE BANK | | fidelity | FIDELITY BANK PLC | | fidelitymobile | Fidelity Mobile | | fidfundmfb | FIDFUND MFB | | finatrustmfb | FINATRUST MICROFINANCE BANK | | firmusmfb | Firmus MICROFINANCE BANK | | firstMoniewallet | FirstMonie Wallet | | firstbank | FIRST BANK OF NIGERIA PLC | | firstcitymonumentbank | FIRST CITY MONUMENT BANK PLC | | firstgenmb | FIRST GENERATION MORTGAGE BANK | | firstmobile | FBNMobile | | firstmultiplemfb | FIRST MULTIPLE MFB | | firstoptionmfb | FIRST OPTION MFB | | firstroyalmfb | FIRST ROYAL MICROFINANCE BANK | | firsttrustmob | First Trust Mortgage Bank Plc | | flutterwave | FLUTTERWAVE TECHNOLOGY SOLUTIONS LIMITED | | fortismfb | Fortis Microfinance Bank | | fortismobile | Fortis Mobile | | fsdh | FSDH MERCHANT BANK LIMIT | | fullrangemfb | FULL RANGE MFB | | futomfb | FUTO MFB | | gashuamfb | GASHUA MICROFINANCE BANK | | gatewaymb | GATEWAY MORTGAGE BANK | | globusbank | GLOBUS BANK | | glorymfb | GLORY MFB | | gomoney | GOMONEY | | goodnewsmfb | Goodnews Microfinance Bank | | gowansmfb | GOWANS MFB | | greenbankmfb | GREENBANK MFB | | greenvillemfb | GREENVILLE MICROFINANCE BANK | | greenwichmb | Greenwich Merchant Bank | | groomingmfb | GROOMING MICROFINANCE BANK | | gtb | Guaranty Trust Bank | | gtbmobile | GTMobile | | gtmobile | GT MOBILE | | hackmanmfb | HACKMAN MICROFINANCE BANK | | haggaimb | HAGGAI MORTGAGE BANK | | halamfb | HALA MFB | | hasalmfb | HASAL MFB | | hedonmark | Hedonmark | | heritage | HERITAGE BANK | | ibilemfb | IBILE MICROFINANCE BANK | | ikennemfb | IKENNE MFB | | ikiremfb | IKIRE MICROFINANCE BANK | | imostatemfb | IMO MICROFINANCE BANK | | imperialhomesmob | IMPERIAL HOMES MORTGAGE BANK | | infinitymb | INFINITY TRUST MORTGAGE BANK | | infinitymfb | INFINITY MFB | | innovectiveskesh | INNOVECTIVES KESH | | intellfin | Intellfin | | intellifin | INTELLIFIN | | irlmfb | IRL MICROFINANCE BANK | | jaiz | JAIZ BANK PLC | | jubileelife | JUBILEE LIFE MORTGAGE BANK | | jublieelife | Jubliee Life | | kadickintegration | KADICK INTEGRATION LIMITED | | kadpolymfb | KADPOLY MICROFINANCE BANK | | kcmbmfb | KCMB MFB | | kegow | KEGOW | | keystone | KEYSTONE BANK | | kontagoramfb | KONTAGORA MFB | | kudamfb | KUDA MICROFINANCE BANK | | lapomfb | LAPO MFB | | lavendermfb | LAVENDER MICROFINANCE BANK | | lbicmortgagebank | LBIC MORTGAGE BANK | | letshegomfb | LETSHEGO MICROFINANCE BANK | | lovonusmfb | LOVONUS MICROFINANCE BANK | | m36 | M36 | | mainlandmfb | MAINLAND MICROFINANCE BANK | | mainstreetmfb | Mainstreet Micro-finance Bank | | malachymfb | MALACHY MFB | | mannymfb | MANNY MICROFINANCE BANK | | mautechmfb | Mautech Microfinance Bank | | mayFreshmortgage | MAYFRESH MORTGAGE BANK | | mayfairmfb | MAYFAIR MFB | | megapraisemfb | MEGAPRAISE MICROFINANCE BANK | | meridianmfb | MERIDIAN MFB | | microcredmfb | MICROCRED MICROFINANCE BANK | | microvismfb | MICROVIS MICROFINANCE BANK | | midlandmfb | Midland MFB | | mintfinexmfb | Mint-Finex Micro-finance Bank | | mkudi | Mkudi | | moneybox | MoneyBox | | moneytrustmfb | MONEYTRUST MFB | | mutualbenefitsmfb | MUTUAL BENEFITS MFB | | mutualtrustmfb | MUTUAL TRUST MICROFINANCE BANK | | nagartamfb | NARGATA MFB | | navymfb | NAVY MICROFINANCE BANK | | ndiorahmfb | NDIORAH MFB | | newdawnmfb | NEWDAWN MICROFINANCE BANK | | newprudential | New Prudential Bank | | nigeriainterbanksettlementsystem | NIGERIA INTERBANK SETTLEMENT SYSTEM | | nipvb | NIP VIRTUAL BANK | | nirsalnationalmicrofinancebank | NIRSAL NATIONAL MICROFINANCE BANK | | nnewwomenmfb | NNEW WOMEN MFB | | novameb | NOVA MB | | npfmfb | NPF Microfinance Bank | | ochemfb | OCHE MFB | | ohafiamfb | OHAFIA MFB | | okpogamfb | OKPOGA MFB | | olabisionabanjomfb | OLABISI ONABANJO UNIVERSITY MICROFINANCE BANK | | omiyemfb | OMIYE MFB | | omoluabimob | Omoluabi Savings and Loans Plc | | onefinance | ONE FINANCE | | opay | OPAY(PAYCOM) | | optimusbank | OPTIMUS BANK | | paga | PAGA | | pagemfb | Page MFBank | | palmpay | PALMPAY | | parallex | PARALLEX MFB | | parkway | Parkway | | parkwayreadycash | ParkWay-ReadyCash | | parralexmfb | PARRALEX | | patrickgoldmfb | PATRICK GOLD | | payattitudeonline | PayAttitude Online | | pecanTrustmfb | PECAN TRUST MICROFINANCE BANK | | pennywisemfb | PENNYWISE MICROFINANCE BANK | | personaltrustmfb | PERSONAL TRUST MICROFINANCE BANK | | petramfb | PETRA MICROFINANCE BANK | | pillarmfb | PILLAR MFB | | platinummb | PLATINUM MORTGAGE BANK | | polaris | POLARIS BANK LTD (SKYE BANK PLC) | | polyuwannamfb | POLYUWANNA MFB | | premiumtrust | PREMIUM TRUST BANK | | prestigemfb | PRESTIGE MICROFINANCE BANK | | providus | PROVIDUS BANK | | purplemoneymfb | PURPLEMONEY MFB | | quickfundmfb | QUICKFUND MICROFINANCE BANK | | rahamamfb | RAHAMA MFB | | randmeb | RAND MERCHANT BANK | | refugemb | REFUGE MORTGAGE BANK | | regentmfb | REGENT MFB | | reliancemfb | RELIANCE MFB | | renmoneymfb | RENMONEY MICROFINANCE BANK | | rephidimmfb | REPHIDIM MICROFINANCE BANK | | richwaymfb | RICHWAY MFB | | rolezmfb | ROLEZ MICROFINANCE BANK | | royalexchangemfb | ROYAL EXCHANGE MICROFINANCE BANK | | rubiesmfb | RUBIES MFB | | safehavenmfb | SAFE HAVEN MFB | | safetrust | Safetrust Mortgage bank | | sagamumfb | SAGAMU MICROFINANCE BANK | | seedcapitalmfb | SEED CAPITAL MICROFINANCE BANK | | sparkle | SPARKLE MICROFINANCE BANK | | stanbic | STANBIC IBTC BANK PLC | | stanbicibtceasewallet | Stanbic IBTC @ease Wallet | | stanbicmobile | STANBIC MOBILEMONEY | | standardchartered | STANDARD CHARTERED BANK NIGERIA LTD | | stanfordmfb | STANFORD MFB | | stellasmfb | STELLAS MICROFINANCE BANK | | sterling | STERLING BANK PLC | | sterlingmobile | Sterling Mobile | | sulsapmfb | SULSAP MFB | | suntrust | SunTrust Bank | | tagpay | TAGPAY | | taj | TAJ BANK | | tcfmfb | TCF | | teasymobile | TeasyMobile | | titan | Titan Trust Bank | | titanpaystackmicrofinancebank | TITAN-PAYSTACK MICROFINANCE BANK | | tridentmfb | TRIDENT MICROFINANCE BANK | | trustbancj6mfb | TRUSTBANC J6 MICROFINANCE BANK LIMITED | | trustbondmb | TRUSTBOND MORTGAGE BANK | | trustfundmfb | TRUSTFUND MICROFINANCE BANK | | trustmfb | TRUST MFB | | uandcmfb | U AND C MFB | | uba | UNITED BANK FOR AFRICA PLC | | unaabmfb | UNAAB MFB | | unibenmfb | UNIBEN MICROFINANCE BANK | | unicalmfb | UNICAL MFB | | unionbanknga | UNION BANK OF NIGERIA PLC | | unity | UNITY BANK PLC | | unnmfb | UNN MFB | | vfdmfb | VFD MFB | | virtuemfb | VIRTUE MFB | | visamfb | VISA MICROFINANCE BANK | | visualict | Visual ICT | | vtnetworks | VTNetworks | | wema | WEMA BANK | | wetlandmfb | WETLAND MFB | | xslncemfb | XSLNCE MICROFINANCE BANK | | yesmfb | YES MFB | | zenith | ZENITH BANK PLC | | zenithmobile | ZenithMobile | | zinternetkongapay | ZINTERNET - KONGAPAY |
|
Поля в urls:
| Наименование |
Обязательное? |
Тип |
Описание |
urls.redirectSuccess |
Да |
string |
URL для перенаправления после успешного депозита. |
urls.redirectFail |
Да |
string |
URL для перенаправления после неудачного депозита. |
urls.callback |
Да |
string |
URL для отправки уведомлений о статусе транзакции. |
urls.return |
Да |
string |
URL для возврата на сайт клиента |
Поля sessionSettings:
| Наименование |
Обязательное? |
Тип |
Описание |
sessionSettings.clientTheme |
Нет |
string |
Тема терминала при его открытии. Возможные значения: |
sessionSettings.clientLanguage |
Нет |
string |
Язык терминала при его открытии. Возможные значения: |
sessionSettings.visibleMethods |
Нет |
Возможные варианты:- array [string]
- array [object]
|
Поддерживаются два формата данных:- array [string] - список названий методов, которые хочет получить клиент (массив строк)
["BankTransfer"] - array [object] - список связок “название метода + тип подключения” (массив объектов)
[{"paymentMethodName":"BankTransfer","communicationType":"h2h"}]
|
sessionSettings.presetAmounts |
Нет |
array [object] |
Предподготовленные суммы для совершения платежа (если paymentInfo.amount не передан):
[{"paymentMethodName":"BankTransfer","communicationType":"h2h","amounts":[300,500,1000]}] |
Варианты ответов
Формат: JSON
1. Успешный ответ (статус 200)
При успешном выполнении запроса API возвращает ответ со статусом 200 OK и следующей структурой:
{
"url": "https://payment-terminal-form.idynsys.org/open/bj9MBmsE0ovw1a75Si867Le1MpDg5O-1733321054223170",
"sessionId: "bj9MBmsE0ovw1a75Si867Le1MpDg5O-1733321054223170"
}
2. Ошибка доступа (статус 403)
Если подпись некорректна, секретный ключ не совпадает с ключом, зарегистрированном в системе B2B Backoffice, отсутствует или неактивно приложение, определенное в заголовке запроса X-Client-Id, то API вернет ответ со статусом 403 Forbidden и со следующей структурой:
{
"error": {
"code": "403",
"message": "Access denied"
}
}
Система отправляет коллбек на указанный в urls.callback адрес. Структура коллбека:
{
"id": 223344,
"status": "COMPLETED",
"amount": 4000,
"currency": "NGN",
"error": "",
"merchantClientId": "881100",
"merchantOrderId": "d07d573f-fc62-4652-8b35-9b4a9a9d2ed3",
"paymentMethod": "BankTransfer",
"paymentSystem": "Dalapay",
"trafficType": "ftd",
"trafficSegment": "",
"sessionId": "some-id",
"bonusCode": "bonus"
}
| Наименование |
Тип |
Обязательность |
Описание |
id |
integer |
Да |
ID ордера, созданного для платежа на стороне системы биллинга. |
status |
string |
Да |
Текущий статус ордера системы биллинга. Возможные значения:- ERROR (терминальный статус, ошибка при обработке заявки в системе биллинга, либо всех ПС по каскаду на стороне ПС)
- IN_PROGRESS (заявка в обработке на стороне платежной системы, также ожидание оплаты пользаветеля)
- COMPLETED (терминальный статус, заявка успешно обработана, платеж проведен)
- EXPIRED (терминальный статус, время ожидания оплаты прошло)
- DECLINED (терминальный статус, все ПС по каскаду отклонили платеж)
- REFUND (терминальный статус, возврат по операции успешно выполнен)
- CANCELLED_BY_MERCHANT (терминальный статус, заявка отменена мерчантом до завершения платежа)
- CANCELLED_BY_CLIENT (терминальный статус, заявка отменена пользователем)
- RETRY_CANCELLED_BY_MERCHANT (терминальный статус, повторный платёж/ретрай отменён мерчантом)
- PENDING (заявка на выплату ожидает подтверждения менеджером, если в системе биллинга не настроено автоподтверждение)
- INVALID (терминальный статус, может возникуть на этапе валидации как самих данных в запросе, так и при проверки платежных данных в блеклистах до момента отправки данных в ПС)
- WAITING_CONFIRMATION (платёж создан, требуется подтверждение от пользователя или внешней системы)
|
amount |
float |
Да |
Сумма платежа. |
currency |
string |
Да |
Валюта плаежа. 3-х значный буквенный код валюты платежа по ISO 4217. |
error |
string |
Нет |
Ошибка от ПС. |
merchantOrderId |
string |
Да |
ID ордера клиента. |
merchantClientId |
Да |
string |
ID пользователя в системе клиента, который выполняет платеж. |
sessionId |
string |
Нет |
Идентификатор сессии в терминале |
bonusCode |
string |
Нет |
Бонус-код, указанный при создании ордера |
trafficSegment |
Нет |
string |
Сегмент трафика. |
trafficType |
Нет |
string |
Тип трафика. Возможные значения: |
paymentMethod |
Нет |
string |
Платежный метод. |
paymentSystem |
Нет |
string |
Платежная система. |