Concepts
Core concepts behind Credo's payment system - transactions, references, fees, and settlements.
Before diving deeper into the API, it helps to understand how Credo's payment system works at a high level.
Transaction lifecycle
Every payment goes through a series of states from initialization to settlement:
Transaction statuses
| Code | Status | Description |
|---|---|---|
0 | Successful | Payment completed successfully |
1 | Refunded | Transaction has been refunded |
2 | Refund | Queued for refund |
3 | Failed | Payment failed |
4 | Settle | Queued for settlement |
5 | Settled | Funds have been paid out |
6 | Review | Flagged for manual review |
7 | Declined | Failed fraud check |
9 | Cancelled | Cancelled by customer |
10 | Cancelled | Cancelled by merchant |
12 | Attempted | Account generated, awaiting credit |
13 | Attempted | Customer attempted payment |
14 | Initialized | Payment page loaded |
15 | Initializing | Payment URL generated |
Statuses 14 and 15 represent pre-payment states. These records may not appear in your transaction history.
References
Credo uses three identifiers to track every transaction:
Always store both the transRef and your businessReference together. This makes reconciliation and support much easier.
Amounts
All monetary values in the API are expressed in the lowest currency unit - kobo for NGN, cents for USD.
| You want to charge | You send |
|---|---|
| NGN 150.00 | 15000 |
| NGN 1,000.00 | 100000 |
| USD 25.00 | 2500 |
// Converting Naira to kobo
const amountInKobo = nairaAmount * 100;Fee bearer
The bearer field controls who pays the transaction processing fee:
| Value | Who pays | What happens |
|---|---|---|
0 | Customer | Fee is added on top of the amount. Customer pays more. |
1 | Merchant | Fee is deducted from the amount. You receive less. |
Example - charging NGN 150.00 with a NGN 3.25 fee:
- Customer is charged: NGN 153.25
- You receive: NGN 150.00
- Customer is charged: NGN 150.00
- You receive: NGN 146.75
Payment channels
Control which payment methods are shown to the customer using the channel array:
| Channel | Description |
|---|---|
CARD | Credit and debit cards (Visa, Mastercard, Verve) |
BANK | Direct bank transfers |
{
"channels": ["BANK", "BANK"]
}If you omit the channel field, all available methods are presented to the customer.
Settlement
Settlement is the process of transferring funds from Credo to your bank account after a successful transaction.
How it works
Settlement Amount = Transaction Amount - Fee (if merchant bears fee)Paused settlement
You can hold funds in escrow by setting pauseSettlement to 1:
{
"pauseSettlement": 1,
"pauseSettlementDate": "2026-03-15"
}Funds are held until the specified date. Useful for escrow services, milestone-based delivery, or dispute resolution.
Split settlement
Automatically distribute transaction proceeds to multiple accounts. You can configure splits from the dashboard (using a serviceCode) or dynamically at transaction time (using splitConfiguration). See the Settlement System guide for details.
API keys
Credo uses two types of API keys:
| Key | Prefix | Usage |
|---|---|---|
| Public key | 0PUB | Initializing payments. Safe for client-side use. |
| Secret key | - | Verifying transactions and sensitive operations. Server-side only. |
Keep your secret key safe
Never expose your secret key in frontend code, mobile apps, or version control. Use environment variables and keep it on your server.
Webhooks
Webhooks are HTTP POST notifications sent to your server when events occur. They're the most reliable way to confirm transaction outcomes — callbacks can be missed if a customer closes their browser.
Credo sends webhooks for 4 event types:
| Event | When it fires |
|---|---|
transaction.successful | Payment processed successfully |
transaction.failed | Payment declined (bad card, insufficient funds, etc.) |
transaction.transaction.transfer.reverse | Bank transfer underpaid/overpaid — amount reversed to customer |
transaction.settlement.success | Merchant settlement has been paid out |
Key points:
- Verify the
credo-signatureheader (HMAC-SHA512) before processing - Respond with HTTP
200immediately - Credo retries up to 5 times if your endpoint doesn't respond
Learn more in the Webhooks guide.
Next steps
Was this page helpful?
Last updated on