Pesa ni namba kamili
Viasi vyote ni vipimo vidogo — senti — kama namba kamili. Hakuna desimali inayopita kwenye mtandao, hivyo hakuna kinachozungushwa tofauti upande wako na wetu.
Wasanidi
API ya malipo unayoweza kuikumbuka kichwani.
REST juu ya HTTPS, JSON kuingia na kutoka, idempotency kwenye kila uandishi, na webhooks zinazojaribu tena hadi uthibitishe kupokea. Viasi ni namba kamili kwa senti, kwa sababu namba za desimali hazina nafasi karibu na pesa.
Sandbox tangu siku ya kwanza
Uandishi wa idempotent
Webhooks zilizotiwa saini
# Charge a customer wallet
POST /v1/charges
Authorization: Bearer sk_live_...
Idempotency-Key: 8f14e45f-ea
{
"amount": 4500,
"currency": "USD",
"source": "wallet:+263771234567",
"reference": "INV-2048"
}
# 201 Created
{
"id": "chg_3Nk2...",
"status": "succeeded",
"amount": 4500,
"fee": 54,
"tax": 90,
"net": 4356
}
Misingi
Maamuzi ya muundo utakayokutana nayo
Uandishi ni idempotent
Tuma Idempotency-Key kwenye kila POST. Jaribu tena mara nyingi upendavyo; funguo ileile hurudisha matokeo ya awali badala ya kutoza mara mbili.
Ada ziko wazi
Kila jibu la kutoza hubeba amount, fee, tax na net kama sehemu tofauti. Huhitaji kamwe kukokotoa moja kutoka nyingine.
Webhooks hujaribu tena
Matukio hujaribiwa tena kwa muda unaoongezeka kwa saa 24 hadi urudishe 2xx. Kila moja hubeba kichwa cha saini unachopaswa kuthibitisha kabla ya kuamini mwili wa ujumbe.
Hali ni za mwisho
Kutoza huishia succeeded, failed au reversed. Hakuna kinachobadilisha hali kimyakimya baada ya usuluhishi.
Funguo zina mipaka
Funguo za kuchapisha zinaweza tu kuunda nia za malipo. Funguo za siri hazipaswi kamwe kuwa kwenye msimbo wa mteja wala kwenye hifadhi ya msimbo.
Upeo wa API
Vituo vya API utakavyotumia
| Kiunganishi | Mbinu | Inachofanya |
|---|---|---|
| /v1/charges | POST | Kusanya kutoka pochi, akaunti ya pesa za simu au kadi. |
| /v1/charges/:id | GET | Pata kutoza pamoja na mchanganuo wa ada, kodi na kiasi halisi. |
| /v1/refunds | POST | Rejesha kutoza kote au sehemu yake; ada hurudishwa kwa uwiano. |
| /v1/payouts | POST | Tuma fedha kwenye pochi, namba ya pesa za simu au akaunti ya benki. |
| /v1/payouts/batches | POST | Wasilisha hadi malipo 5,000 kwa mwito mmoja; kila mstari hufaulu au hushindwa peke yake. |
| /v1/balances | GET | Salio linalopatikana na linalosubiri, kwa kila sarafu. |
| /v1/settlements | GET | Usuluhishi pamoja na orodha ya miamala iliyo nyuma ya kila mmoja. |
| /v1/events | GET | Rudia matukio ya webhook ambayo huenda umeyakosa. |
Webhooks
Thibitisha kabla ya kuamini
Kila tukio hubeba kichwa ThumaPay-Signature . Kokotoa HMAC ya mwili ghafi kwa siri ya kiunganishi chako na ulinganishe kwa muda thabiti. Kataa chochote kisicholingana, na kataa muda wa zaidi ya dakika tano ili kuzuia kurudiwa.
// Node — verify a webhook
const sig = req.headers['thumapay-signature'];
const expected = crypto
.createHmac('sha256', endpointSecret)
.update(req.rawBody)
.digest('hex');
if (!crypto.timingSafeEqual(
Buffer.from(sig),
Buffer.from(expected))) {
return res.status(400).end();
}
Maswali
Maelezo ya uunganishaji
Ndiyo. Funguo za sandbox hutolewa wakati mmoja na funguo halisi na hufanya kazi kwa namna ileile, ikiwa ni pamoja na uwasilishaji wa webhook na uigaji wa makosa. Hakuna pesa zinazohama.
Sandbox hutoa thamani za kuchochea zinazolazimisha matokeo maalum — fedha hazitoshi, uthibitisho umeisha muda, mpokeaji hajapatikana — ili uweze kujenga ushughulikiaji wa makosa bila kusubiri hitilafu halisi.
Mipaka ni kwa kila funguo na hurudishwa kwenye kila jibu ndani ya vichwa vya mipaka. Kundi la malipo huhesabiwa kama ombi moja bila kujali idadi ya mistari — ndicho kiini cha kulitumia.
Salio hushikiliwa kwa kila sarafu na halibadilishwi kiotomatiki. Kama sarafu ya malipo inatofautiana na sarafu ya salio, mwito hushindwa badala ya kutumia kiwango kimyakimya.
Funguo hutolewa mara akaunti yako ya biashara itakapothibitishwa. Anza mchakato huo kwenye ukurasa wa Biashara; ufikiaji wa sandbox waweza kutolewa wakati uthibitisho bado unaendelea.
Anza kujenga nayo leo
Ufikiaji wa sandbox hausubiri uthibitisho kamili. Pata funguo, unganisha kutoza, na uone mchanganuo wa ada kwenye mwili wa jibu lako mwenyewe.