Payment Flow
KisPay offers two integration methods for processing payments: Redirect Checkout and Direct Checkout. This guide explains how payments flow through each method, from initiation to completion.
How It Works
All KisPay payments follow this general flow:
- Create Session - Your server calls KisPay API to create a checkout session
- Customer Pays - Customer completes payment (either on KisPay’s page or your own)
- Verify Status - Your server checks payment status via API
- Complete Order - Update your database and show confirmation to customer
Integration Methods Overview
| Feature | Redirect Checkout | Direct Checkout |
|---|---|---|
| Checkout Page | KisPay-hosted | Your own website/app |
| User Experience | Redirected to KisPay | Stays on your site |
| Integration Complexity | Simple | Moderate |
| Customization | Limited | Full control |
| Best For | Quick integration | Custom experience |
Redirect Checkout Flow
In redirect checkout, customers are temporarily redirected to KisPay’s hosted checkout page to complete their payment, then returned to your website.
Step-by-Step Flow
Step 1: Customer Initiates Payment
- Customer clicks “Pay Now” or “Checkout” on your website
- Your frontend sends payment details to your backend server
Step 2: Create Checkout Session
- Your server calls KisPay API to create a checkout session
- KisPay returns a unique
sessionIdandcheckoutUrl
Step 3: Redirect to KisPay
- Customer is redirected to KisPay’s secure checkout page
- Customer selects payment method (TeleBirr, CBE Birr, Awash Birr)
Step 4: Payment Processing
- Customer completes payment with their chosen provider
- Payment provider confirms transaction with KisPay
Step 5: Payment Confirmation
- Customer is redirected back to your website (success/cancel/error URL)
Step 6: Verify Payment
- Your server verifies payment status via API call
- Update order status and show confirmation to customer
The customer completes payment on KisPay’s secure page, then returns to your website where you verify the payment status to confirm the transaction.
Direct Checkout Flow
In direct checkout, customers complete payment directly on your website without leaving. You have full control over the UI/UX.
Step-by-Step Flow
Step 1: Customer Initiates Payment
- Customer fills out payment form on your website
- Customer stays on your site throughout the process
Step 2: Create Checkout Session
- Your server calls KisPay API to create a checkout session
- KisPay returns a
sessionIdfor tracking
Step 3: Display Payment Options
- Your frontend shows available payment methods
- Customer selects their preferred method (TeleBirr, CBE Birr, etc.)
Step 4: Submit Payment
- Customer enters payment credentials in your form
- Your frontend submits payment to your backend
Step 5: Process Payment
- Your server sends payment request to KisPay API
- KisPay forwards to payment provider
Step 6: Poll Payment Status
- Your frontend polls for payment status
- Once confirmed, show success message
Step 7: Verify & Complete
- Verify final payment status via API
- Update order and show confirmation
With direct checkout, the customer stays on your website. Your system polls the payment status every few seconds until the payment is confirmed or fails.
Payment Statuses
Understanding payment statuses helps you handle different scenarios correctly.
Status Descriptions
| Status | Description | Action Required |
|---|---|---|
| INITIATED | Session created, awaiting customer action | Show checkout page/form |
| PENDING | Customer submitted payment, waiting for provider | Poll for status updates |
| PROCESSING | Payment provider processing transaction | Continue polling |
| COMPLETED | Payment successful, funds confirmed | Update order, show success |
| FAILED | Payment failed or declined | Show error, allow retry |
| EXPIRED | Session expired (no payment within time limit) | Create new session |
| CANCELLED | Customer cancelled the payment | Return to cart/product page |
Handling Payment Outcomes
After processing a payment, you need to handle different outcomes:
Successful Payments (COMPLETED)
- Update order status in your database
- Send confirmation email to customer
- Display success message with order details
- Redirect customer to order confirmation page
Failed Payments (FAILED)
- Display clear error message to customer
- Allow customer to retry payment
- Offer alternative payment methods
- Log the failure for analysis
Pending Payments (PENDING)
- Continue polling for status updates
- Show loading indicator to customer
- Set reasonable timeout (2-3 minutes)
- Handle timeout gracefully
Cancelled Payments (CANCELLED)
- Return customer to cart or product page
- Preserve cart contents
- Allow easy retry of payment
Expired Sessions (EXPIRED)
- Create new checkout session
- Inform customer and allow retry
- Verify order details are still valid
API Endpoints Quick Reference
| Endpoint | Method | Purpose |
|---|---|---|
/checkout/create_session | POST | Create checkout session (both methods) |
/checkout/event-links/create-event-link | POST | Process payment (direct checkout) |
/payments/status/{sessionId} | GET | Check payment status |
Need Help?
If you have questions about implementing the payment flow:
- Developer Support: developers@kispay.et
Pro Tip: Start with Redirect Checkout for quick integration, then migrate to Direct Checkout when you need more customization. Both methods use the same backend API endpoints.