Skip to main content

Create a Payment

A payment is the central object in the KartaPay API: you create one for every order, then redirect your customer to the checkout URL returned in the response.

Requirements​

  • A public HTTP GET endpoint to receive successful callbacks.
  • A public HTTP GET endpoint to receive cancellation callbacks.
  • A unique clientId you generate per payment, used to reconcile the payment between your system and KartaPay.
warning

KartaPay does not provide any security layer for these merchant public endpoints. You are responsible for securing them.

Flow​

  1. Obtain an access token (see Authentication).
  2. POST a payment request to /v1/payments.
  3. Redirect the customer to the submitUrl from the response.

Request​

curl --request POST \
  --url https://api-staging.kartapay.me/v1/payments \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi...' \
  --header 'Content-Type: application/json' \
  --data '{
    "purchase": {
      "total": {
        "value": "1475",
        "currency": "KMF"
      }
    },
    "clientId": "de627e0d87fd2bdcdd7bf72b2c436379",
    "cancelUrl": "https://merchant.com/checkout/cancel",
    "successUrl": "https://merchant.com/checkout/success"
  }'

Response​

{
  "next": "https://checkout-staging.kartapay.me/payment/submit/67928bcc4c9deaf5696a0942",
  "data": {
    "id": "67928bcc4c9deaf5696a0942",
    "status": "pending",
    "captured": false,
    "purchase": {
      "total": {
        "value": "1475",
        "currency": "KMF"
      }
    },
    "cancelUrl": "https://merchant.com/checkout/cancel",
    "successUrl": "https://merchant.com/checkout/success",
    "billing": {
      "submitUrl": "https://checkout-staging.kartapay.me/payment/submit/67928bcc4c9deaf5696a0942"
    },
    "createdAt": "2025-01-23T15:51:08.625Z"
  }
}

Redirect the customer to data.billing.submitUrl to complete the payment with their chosen provider (e.g. Holo, MVola).

:::tip Next step See Handle Cancel & Approve to find out what happens once the customer is on the checkout page. :::