Accept a Payment
This guide walks you through a complete server-side payment integration.
Before you begin
Integration steps
Step 1: Create a PaymentIntent (server-side)
Create a PaymentIntent on your server when the customer initiates checkout.
- cURL
- Node.js
curl -X POST https://api.ikawaari.com/v1/payment-intents \
-H "Authorization: Bearer ik_test_your_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"currency": "XOF",
"payment_method_types": ["mobile_money", "card"],
"metadata": {
"order_id": "order_123"
}
}'
const paymentIntent = await ik.paymentIntents.create({
amount: 10000,
currency: 'XOF',
payment_method_types: ['mobile_money', 'card'],
metadata: { order_id: 'order_123' },
});
// Send paymentIntent.client_secret to your frontend
res.json({ clientSecret: paymentIntent.client_secret });
Step 2: Collect payment details
Option A: Redirect to Ikawaari Checkout
The simplest integration — redirect the customer to a hosted payment page:
const session = await ik.checkoutSessions.create({
payment_intent: paymentIntent.id,
success_url: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
cancel_url: 'https://yoursite.com/cancel',
});
// Redirect customer to session.url
Option B: Use Payment Links (no-code)
Create a reusable payment link from the dashboard — no code required. See Payment Links.
Option C: Custom UI
Build your own payment form and confirm the payment:
// Confirm with mobile money
const result = await ik.paymentIntents.confirm(paymentIntent.id, {
payment_method: {
type: 'mobile_money',
mobile_money: {
phone: '+2250700000000',
operator: 'orange_ci',
},
},
});
Step 3: Handle the payment result
After confirmation, the payment enters processing state. For mobile money, the customer receives a USSD prompt on their phone.
{
"id": "pi_1a2b3c4d5e",
"status": "processing",
"next_action": {
"type": "mobile_money_ussd",
"mobile_money_ussd": {
"message": "Please confirm the payment on your phone"
}
}
}
Step 4: Listen for webhooks
Set up a webhook endpoint to receive payment confirmations:
// POST /webhooks/ikawaari
app.post('/webhooks/ikawaari', (req, res) => {
const event = req.body;
switch (event.type) {
case 'payment_intent.succeeded':
const paymentIntent = event.data;
// Fulfill the order
fulfillOrder(paymentIntent.metadata.order_id);
break;
case 'payment_intent.payment_failed':
// Notify the customer
notifyCustomer(event.data.metadata.order_id);
break;
}
res.json({ received: true });
});
Important
Always use webhooks to confirm payment success. Do not rely solely on client-side redirects.
Error handling
| Error Code | Description | Action |
|---|---|---|
insufficient_funds | Customer doesn't have enough balance | Ask customer to top up |
payment_timeout | Customer didn't confirm in time | Create a new PaymentIntent |
provider_unavailable | Mobile money operator is down | Retry or offer alternative method |
invalid_phone | Phone number format is incorrect | Validate phone number format |