Sign in

v1

latestOpenAPI 3.0.02026-07-2627149175.2 KB
checkouts

Initiate checkout

post/v2/checkouts

Headers

Content-Digeststring string

SHA-256 or SHA-512 hash of the request body.

Signaturestring string

Signature of the request according to RFC-9421.

Signature-Inputstring string

Signature input according to RFC-9421.

Accept-Signaturestring string

Expected signature algorithm of the response according to RFC-9421.

Accept-Digeststring string

Expected digest algorithm of the response according to RFC-9421.

Request body

checkoutIdstring uuid required

A UUIDv4 based unique ID for this payment. We require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments. Please store this ID in your system before initiating the payment with PawaPay.

returnUrlstring uri required

The URL the customer should be redirected to after the payment is processed.

returnMethod'INSTANT' | 'COUNTDOWN' | 'CUSTOMER_ACTION'

Controls how the customer is returned from the hosted payment page to the returnUrl once the payment is finished or cancelled. The customer is always returned eventually; this only affects the experience.

  • INSTANT - The customer is redirected back immediately, with no extra screen.
  • COUNTDOWN - A short countdown is shown, then the customer is redirected automatically.
  • CUSTOMER_ACTION - The checkout page waits until the customer presses "Return to merchant".
defaultLanguage'en' | 'fr'

The default language of the checkout page. Supported languages are en and fr.

countriesCheckoutCountry[]

Restricts the checkout to the specified countries when provided.

expiresAfterinteger

Number of minutes after creation when the checkout should expire. Must be between 3 and 60. Defaults to 15 if not provided.

clientReferenceIdstring

A reference to an entity in your system that this payment relates to. For example, an invoice ID, customer ID etc.

reasonCheckoutReason

Localized reason values shown to the customer inside the hosted payment page.

Example request

{
  "checkoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "returnUrl": "https://merchant.example.com/checkout-result",
  "defaultLanguage": "en",
  "countries": [
    "ZMB",
    "CIV"
  ],
  "expiresAfter": 60,
  "amounts": [
    {
      "country": "ZMB",
      "currency": "ZMW",
      "amount": "15"
    }
  ],
  "payer": {
    "type": "MMO",
    "accountDetails": {
      "phoneNumber": "260763456789",
      "provider": "MTN_MOMO_ZMB",
      "allowCustomerToOverride": true
    }
  },
  "clientReferenceId": "INV-123456",
  "reason": {
    "en": "GOODS PURCHASE"
  },
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}

Response

Request has valid payload. See status to confirm if the checkout was accepted for processing.

checkoutIdstring uuid required

A UUIDv4 based unique ID for this payment. We require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments. Please store this ID in your system before initiating the payment with PawaPay.

status'ACCEPTED' | 'REJECTED' | 'DUPLICATE_IGNORED' required

The initiation status of the checkout:

  • ACCEPTED - The checkout has been accepted and the hosted payment page has been created.
  • REJECTED - The checkout has been rejected. See failureReason for details.
  • DUPLICATE_IGNORED - The checkout has been ignored as a duplicate of an already accepted checkout. Deduplication is based on checkoutId.
redirectUrlstring uri

The URL to which the customer must be redirected to open and complete the hosted payment page.

createdstring date-time

The timestamp of when the payment was created in the PawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 from IETF

expiresAtstring date-time

The timestamp when the checkout and its hosted payment page are scheduled to expire.

checkoutCodestring

A unique identifier that forms part of the checkout's redirect URL.

Example response

{
  "checkoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "redirectUrl": "https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79",
  "created": "2020-02-21T17:32:29Z",
  "expiresAt": "2026-03-27T11:30:00Z",
  "checkoutCode": "PPGAFB57B93",
  "failureReason": {
    "failureCode": "INVALID_PAYER_FORMAT"
  }
}