LakiPay logodocs
back

Hosted Checkout

Let LakiPay host the payment UI: your backend creates a checkout session, you send the customer to our page to pick a method and pay, then we redirect them back and notify you via webhooks.

When to use it

Use hosted checkout when you want a maintained, PCI-friendly flow without building provider-specific screens. You still authenticate with X-API-Key on your server—never expose keys in the browser.

Overview

Create a session with POST /api/v2/payment/checkout. The JSON body describes the charge, allowed mediums, and where to send the shopper after success or failure.

Endpoint
POST https://api.lakipay.co/api/v2/payment/checkout
Authentication
X-API-Key: PUBLICKEY:SECRETKEY

Typical flow

  1. 1Your server calls the checkout API with amount, currency, reference, phone number, redirects, and supported_mediums.
  2. 2You read the checkout URL from the response and issue an HTTP redirect (or open the link) for the customer.
  3. 3After payment, LakiPay sends the shopper to redirects.success or redirects.failed.
  4. 4Rely on callback_url webhooks and/or the transaction detail API for authoritative status—do not trust the redirect alone.

Request

Send JSON with Content-Type: application/json.

Example (cURL)

curl -X POST https://api.lakipay.co/api/v2/payment/checkout \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-publickey:your-secretkey" \
  -d '{
    "amount": 1000.5,
    "currency": "ETB",
    "phone_number": "251911111111",
    "reference": "ORDER123456",
    "description": "Payment for order #123",
    "callback_url": "https://example.com/callback",
    "redirects": {
      "success": "https://example.com/success",
      "failed": "https://example.com/failed"
    },
    "supported_mediums": ["MPESA", "TELEBIRR", "CBE"]
  }'

Body fields

ParameterTypeRequiredDescription
amountdecimalRequiredCharge amount (e.g. two decimal places).
currencystringRequiredCurrency code such as ETB.
phone_numberstringRequiredCustomer phone with country code, digits only (no leading +).
referencestringRequiredUnique id for this checkout session in your system.
supported_mediumsarray[string]RequiredMethods shown on the hosted page (e.g. MPESA, TELEBIRR, CBE, ETHSWITCH).
redirects.successstringRequiredURL after a successful payment.
redirects.failedstringRequiredURL after a failed or cancelled attempt.
callback_urlstringOptionalServer-to-server webhook URL for asynchronous payment updates.
descriptionstringOptionalShown to the customer or stored for reconciliation.

Security

Call this endpoint only from your backend. The response contains a privileged checkout link tied to your merchant session.

Response

Successful responses use the same envelope as other LakiPay APIs: status, message, and data. See Core Concepts → Response format for general rules and errors.

Example success body

Redirect the customer to data.checkout_url. Keep data.lakipay_transaction_id to poll transaction detail or correlate webhooks.

{
  "status": "SUCCESS",
  "message": "Checkout session created successfully",
  "data": {
    "checkout_url": "https://checkout.lakipay.co/pay/abc123...",
    "lakipay_transaction_id": "TXN-123456789",
    "reference": "ORDER123456",
    "amount": 1000.5,
    "currency": "ETB",
    "status": "INITIATED"
  }
}

data fields (hosted checkout)

FieldTypeDescription
checkout_urlstringHosted payment page URL—redirect or open this for the payer.
lakipay_transaction_idstringLakiPay transaction id for lookups and webhook correlation.
referencestringEcho of the reference you sent in the request.
amountdecimalAuthorized charge amount.
currencystringCurrency for this session.
statusstringInitial session status (e.g. INITIATED) before the customer completes payment.

After redirect

Configure callback_url and verify signatures per the Webhooks guide so your order state stays accurate even if the customer closes the browser.

Next steps

API Reference

Compact parameter summary for hosted checkout alongside other endpoints.

SDKs

Official clients expose hosted checkout helpers in several languages.

Direct Payments

Prefer server-initiated provider calls without a hosted page? Use direct payments.

Getting Started

Base URL, API keys, and your first payment-style request patterns.