API на крипто платежен шлюз: фактури, webhooks, изплащания и white label

Какво прави API на крипто платежен шлюз?

API скрива блокчейна от вашия код. Вместо да поддържате възли, да извличате адреси и да броите потвърждения, извиквате endpoint за създаване на фактура, запазвате идентификатора на шлюза и чакате известия. Шлюзът котира обменния курс, следи мрежите, прилага AML проверки и уравнява по баланса ви.

Повечето шлюзове предлагат едни и същи градивни елементи под различни имена: фактури или поръчки за входящи плащания, IPN или callbacks за известия, endpoints за преобразуване и баланс, и изплащания или тегления за изходящи преводи. При повечето доставчици има sandbox, например отделен sandbox хост при CoinGate и sandbox акаунт при NOWPayments, и той трябва да се използва преди всеки тест в mainnet.

• Invoice API: създаване, четене и отмяна на заявки за плащане с фиатна цена, приемани монети, референция на поръчката и callback URL
• Известия: webhooks или IPN при всяка промяна на статуса, обикновено подписани
• Payouts API: изпращане на крипто или фиат към клиенти, партньори или собствен портфейл
• Курсове и валути: списък на поддържаните монети, мрежи, минимални суми и актуални котировки
• Плъгини и SDK: готови модули за платформи за електронна търговия върху същото API

Как работи жизненият цикъл на фактурата?

Всеки шлюз има собствен модел на статусите, затова ги съпоставете с малък вътрешен набор, преди да пишете бизнес логика. Само краен статус платено трябва да освобождава стоките; междинните статуси съществуват, защото транзакция може да се види в блокчейна много преди да е безопасно да се приеме.

Таблицата съпоставя два публикувани модела на статуси със състоянията, от които се нуждаят повечето платформи. CoinGate например прекратява неплатена фактура след 20 минути, откакто клиентът е избрал монета, и маркира плащанията, отбелязани от AML проверки, като невалидни.

Как да се проверяват крипто webhooks и IPN?

Третирайте всяко известие като ненадеждно, докато не бъде проверено. Шлюзовете използват различни схеми: NOWPayments подписва сортираното JSON тяло с HMAC-SHA512 и го изпраща в хедъра x-nowpayments-sig, CoinGate изпраща токен, който задавате към поръчката, а BitPay препоръчва след всяко известие да извличате фактурата от API, вместо да се доверявате на тялото му.

Най-безопасният модел съчетава двете: проверете подписа, после прочетете фактурата от API и действайте според този отговор. Това струва по една заявка на промяна на статус и ви защитава от фалшифицирани или повторно възпроизведени callbacks.

• Проверявайте подписите със сравнение за константно време и отхвърляйте неподписаните заявки
• Извличайте повторно фактурата по нейния ID при шлюза, преди да променяте състоянието на поръчката
• Връщайте бързо HTTP 200 и обработвайте асинхронно; шлюзовете повтарят при грешки
• Съхранявайте всяко известие със събитието или статуса му, за да се игнорират дубликати
• Никога не се доверявайте на суми и валути, изпратени при пренасочването от браузъра

Как да се обработват недоплащане, преплащане и закъснели плащания?

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

Как работят идемпотентността и съпоставянето?

Създавайте фактури със собствена референция на поръчката и правете извикването безопасно за повторение: ако заявката изтече, потърсете фактурата по референция, преди да създадете друга, или използвайте ключ за идемпотентност, където шлюзът го поддържа. Същото правило важи за изплащанията, където дублирана заявка изпраща реални пари два пъти.

За съпоставяне съхранявайте ID на фактурата при шлюза, хеша на транзакцията, фиатната сума, крипто сумата, курса и таксата. Отчетите за сетълмент показват изплащанията на партиди, така че съпоставянето върви от поръчка към фактура към изплащане, а не от поръчка към ред в банковото извлечение.

От какво се нуждае Payouts API според Travel Rule?

Endpoints за изплащане изпращат крипто от баланса ви при шлюза към адрес, често на партиди за комисионни на партньори, продавачи в пазарище или тегления на клиенти. Повечето изискват списък с разрешени адреси, двуфакторно одобрение или API ключ с отделни права за изплащане.

В ЕС Регламент (ЕС) 2023/1113 изисква шлюзът да предава информация за наредителя и получателя с всеки превод и да проверява собствеността на самостоятелни портфейли над 1 000 EUR. Очаквайте заявките за изплащане да включват име на получателя и тип на адреса и планирайте преводи, които изчакват тези данни.

Какви са вариантите за white label на крипто платежен шлюз?

Платформите, които препродават плащания на свои търговци, често искат платежната страница да е под тяхната марка. Има три нива и цената расте с контрола. Plisio например обявява 0,5 % за API и 1,5 % за white label, а NOWPayments продава отделен white-label продукт.

Пълният white label прехвърля не само брандирането, но и отговорността. Ако сами включвате търговци и държите балансите им, може да ви трябва собствено разрешение по MiCA; моделът на под-търговци при оторизиран шлюз оставя това задължение на шлюза.

Как да свържете API на крипто шлюзове чрез OrsunPay?

OrsunPay нормализира статусите, webhooks и възстановяванията на крипто шлюзове в едно API заедно с вашите карти и банкови доставчици, като използва вашите собствени акаунти при шлюзовете. Той не съхранява крипто и не извършва изплащания от собствен баланс; маршрутизира заявките към шлюза, който изберете, и връща подписани, дедупликирани събития.

Как да интегрирате API на платежен шлюз за криптовалути

1. Открийте sandbox акаунти Създайте sandbox и продукционен акаунт при шлюза, генерирайте отделни API ключове за фактури и изплащания и задайте IPN тайната.
2. Съпоставете статусите Преведете статусите на шлюза във вътрешните си състояния и решете кое от тях освобождава стоките.
3. Създавайте фактури идемпотентно Изпращайте фиатна сума, валута, референция на поръчката и callback URL; преди да повторите изтекла заявка, потърсете фактурата по референция.
4. Проверявайте известията Проверете подписа, извлечете повторно фактурата от API и обработете събитието само веднъж.
5. Обработете граничните случаи Реализирайте толеранс, доплащане, възстановяване и изтичане и тествайте всеки поток в sandbox.
6. Съпоставяйте сетълментите Съхранявайте хеш на транзакцията, курс и такса за всяка фактура и съпоставяйте партидите изплащания с поръчките ежедневно.