URL:
- Тестовое окружение:
https://api-gateway.sandbox.idynsys.org/api/accounts/external-app/withdrawal
- Продакшн окружение:
https://api-gateway.idynsys.org/api/accounts/external-app/withdrawal
Метод запроса: POST
Заголовки запросе:
X-Client-Id: (обязательно). Идентификатор приложения, получаемый при регистрации приложения в системе B2B Backoffice.X-Authorization-Sign: (обязательно). Подпись запроса по секретному ключу приложения, который определяется в системе B2B Backoffice. Подпись формируется по алгоритму, описанному на странице “Подпись”Content-Type: (обязательно) Тип содержимого запроса, должно быть application/json.
Структура тела запроса:
Тело запроса должно быть в формате JSON и иметь следующую структуру:
curl --location 'https://api-gateway.sandbox.idynsys.org/api/accounts/external-app/withdrawal' \
--header 'X-Client-Id: {{xClientId}}' \
--header 'X-Authorization-Sign: {{xAuthorizationSign}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"paymentMethodName": "BankTransfer",
"communicationType": "h2h",
"skipTerminalFlow": false,
"payment": {
"amount": 4000.00,
"currency": "NGN"
},
"merchantOrder": {
"id": "d07d573f-fc62-4652-8b35-9b4a9a9d2ed3",
"description": "desc"
},
"urls": {
"callback": "https://callback.com"
},
"sessionDetails": {
"ipAddress": "139.0.51.23",
"acceptLanguage": "en-US",
"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
"fingerprint": "aekrtpwoiertjw34tij34w2-t89twp3j409j"
},
"customer": {
"id": "test1",
"firstName": "Ivan",
"lastName": "Ivanov"
},
"customerAccount": {
"pan": "8310021622",
"bankName": "NORTH EAST SMALL FINANCE BANK LIMITED"
}
}'
В следующей таблице информация об обязательности атрибутов для платежного метода BankTransfer WITHDRAWAL H2H в рамках ПС Dalapay:
| Поле |
Обязательное |
Тип |
Описание |
paymentMethodName |
Да |
string |
Код метода оплаты. Возможные значения> |
communicationType |
Да |
string |
Тип коммуникации для выполнения платежа. Возможные значения: |
skipTerminalFlow |
Нет |
boolean |
Признак пропуска редиректа на платежный терминал. По умолчанию false. Если передано true, в ответе не будет возвращено поле redirectUrl, а дальнейшая обработка платежа должна выполняться на стороне мерчанта через urls.callback. |
trafficType |
Нет |
string |
Тип трафика. Возможные значения: |
payment.amount |
Да |
float |
Сумма платежа. Допустимые значения - больше 0. Если передается значение с дробной частью, то оно может округляться по правилам платежной системы. |
payment.currency |
Да |
string |
3-х значный буквенный код валюты платежа по ISO 4217. |
merchantOrder.id |
Да |
string |
Идентификатор ордера клиента (организации заказчика). |
merchantOrder.description |
Да |
string |
Описание ордера клиента. |
customer.id |
Да |
string |
Идентификатор пользователя в магазине, который выполняет платеж. |
customer.firstName |
Да |
string |
Имя плательщика латиницей. |
customer.lastName |
Да |
string |
Фамилия плательщика латиницей. |
sessionDetails.acceptLanguage |
Да |
string |
Соответствуете заголовку Accept-Language в браузере, используется для указания предпочтений клиента по языкам. |
sessionDetails.fingerprint |
Да |
string |
Подпись данных пользователя в запросе. см. https://github.com/fingerprintjs/fingerprintjs |
sessionDetails.ipAddress |
Да |
string |
IP адрес пользователя. |
sessionDetails.userAgent |
Да |
string |
Информацию о браузере, операционной системе и устройстве пользователя. |
customerAccount.pan |
Да |
string |
Номер электронного или банковского счёта |
customerAccount.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.callback |
Да |
string |
URL для отправки уведомлений о статусе транзакции. |
trafficSegment |
Нет |
string |
Сегмент трафика. Задается через валютный счет. |
riskGroupCode |
Нет |
string |
Код рисковой группы пользователя. Задается через валютный счет. |
Ответ возвращается в формате JSON.
1. Успешный ответ (статус 200)
При успешном выполнении запроса API возвращает ответ со статусом 200 OK и следующей структурой:
{
"amount": 4000,
"currency": "NGN",
"id": 467343,
"status": "NEW"
}
Описание полей ответа:
| Наименование |
Тип |
Обязательное? |
Описание |
| id |
integer |
Да |
Идентификатор ордера для выполненного платежа. Может содержать значение 0, если ордер не был создан по причине отсутствия настроенных маршрутов, некорректных данных для создания ордера и других случаев. |
| amount |
integer |
Да |
Сумма платежа |
| currency |
string |
Да |
Валюта платежа |
| status |
string |
Да |
Код статуса выполнения платежа.Возможные значения- ERROR
- IN_PROGRESS
- COMPLETED
- DECLINED
- INVALID
|
| error |
string |
Нет |
Содержит текстовое описание ошибки, в случае, если статус = ERROR |
2. Ошибка доступа (статус 403)
Если подпись некорректна, секретный ключ не совпадает с ключом, зарегистрированном в системе B2B Backoffice, отсутствует или неактивно приложение, определенное в заголовке запроса X-Client-Id, то API вернет ответ со статусом 403 Forbidden
{
"success": false,
"message": "access denied"
}
3. Ошибка валидации (статус 422)
Если не удается создать ордер по переданному body, то срабатывает ошибка валидации
{
"success": false,
"message": "data validation error for: payment.amount - Value is required"
}
4. Внутренняя ошибка (статус 500)
При внутренней ошибке:
{
"success": false,
"message": "internal error"
}
- Выплаты не переводятся в статус EXPIRED по истечению 72 часов. По зависшим ордерам необходимо написать техподдержке (tg @BillingTechSupport).
Система отправляет коллбек на указанный в 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": ""
}
| Наименование |
Тип |
Обязательность |
Описание |
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 |
Платежная система. |