Skip to main content
POST
/
v2
/
checkouts
Initiate checkout
curl --request POST \
  --url https://api.sandbox.pawapay.io/v2/checkouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ],
  "clientReferenceId": "INV-123456",
  "reason": {
    "en": "GOODS PURCHASE"
  },
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}
'
{
  "checkoutId": "afb57b93-7849-49aa-babb-4c3ccbfe3d79",
  "status": "ACCEPTED",
  "redirectUrl": "https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79",
  "created": "2026-03-27T10:30:00Z",
  "expiresAt": "2026-03-27T11:30:00Z",
  "checkoutCode": "PPGAFB57B93"
}
The checkout endpoint creates a checkout and returns a redirectUrl for a hosted payment page that you forward the customer to.

Check the guide!

Follow the step-by-step guide on how to create, use, and track checkouts.
  • This API call is idempotent, which means it is safe to submit a request with the same checkoutId multiple times.
  • Duplicate requests with the same checkoutId will be ignored with the DUPLICATE_IGNORED status in the response.
  • Always check the status in the response for each request. When it is REJECTED, the failureReason describes what went wrong through its failureCode and failureMessage.
  • A checkout is the single reference for the whole payment, including any retries the customer makes.
  • One checkout can contain multiple payment attempts, but at most one can complete successfully. The customer can retry within the same checkout — PawaPay manages the attempts for you.
  • If the checkout is accepted, redirect the customer to the returned redirectUrl.
Each request can get one of the statuses on initiation:
StatusDescription
ACCEPTEDThe checkout has been accepted and the hosted payment page has been created.
REJECTEDThe checkout has been rejected. See failureReason for details.
DUPLICATE_IGNOREDThe checkout has been ignored as a duplicate of an already accepted checkout. Deduplication is based on checkoutId.

​
How to find out the final status of this checkout?

As the PawaPay Merchant API is an asynchronous API, a checkout has its own lifecycle. You can find out the final status of an ACCEPTED checkout by either:

Waiting for a callback

If you have configured callbacks, the callback with the final status of the checkout will be delivered to your callback URL.

Checking the status

Or poll the Check Checkout Status endpoint for the latest checkout and payment status.
If the checkout should no longer be used, you can expire it explicitly.
Headers related to signatures must only be included if you have enabled “Only accept signed requests”. Read more about it from the PawaPay Dashboard documentation.

Authorizations

​
Authorization
string
header
required

See Authentication.

Headers

​
Content-Digest
string<string>

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

​
Signature
string<string>

Signature of the request according to RFC-9421.

​
Signature-Input
string<string>

Signature input according to RFC-9421.

​
Accept-Signature
string<string>

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

​
Accept-Digest
string<string>

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

Body

application/json
​
checkoutId
string<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.

Required string length: 36
Example:

"f4401bd2-1568-4140-bf2d-eb77d2b2b639"

​
returnUrl
string<uri>
required

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

Example:

"https://merchant.example.com/checkout-result"

​
returnMethod
enum<string>

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".
Available options:
INSTANT,
COUNTDOWN,
CUSTOMER_ACTION
​
defaultLanguage
enum<string>

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

Available options:
en,
fr
Example:

"en"

​
countries
string[]

Restricts the checkout to the specified countries when provided.

A country that the hosted payment page allows for this checkout.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from Wikipedia.

Required string length: 3
Example:
["ZMB", "CIV"]
​
expiresAfter
integer<int32>

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

Required range: 3 <= x <= 60
Example:

60

​
amounts
object[]

The fixed amount the customer is asked to pay, specified per country and currency.

This allows you to set the amount the customer will pay in each country and currency the checkout supports. The customer is then asked to pay the amount matching the country and currency they select on the hosted payment page.

If amounts is provided, it must include an entry for every country in the countries array. If omitted, the customer enters the amount themselves on the hosted payment page.

​
payer
object

Details of the payer that should be pre-filled for the hosted payment page, if specified.

​
clientReferenceId
string

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

Example:

"INV-123456"

​
reason
object

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

Example:
{ "en": "GOODS PURCHASE" }
​
metadata
object[]

A list of metadata that you can attach to the payment for providing additional context about the payment. For example, adding the channel from which the payment was initated, product ID or anything else that might help your operations team.

Metadata will be included in:

  • In the dashboard on payment details pages
  • Financial statements as JSON object
  • Callbacks

Metadata can be used when searching in the PawaPay Dashboard. Full value of the metadata field must be used for searches.

Metadata will not be visible to the customer that is involved in this payment.

Up to 10 metadata fields can be attached to a payment.

Example:
[
  { "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.

​
checkoutId
string<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.

Required string length: 36
Example:

"f4401bd2-1568-4140-bf2d-eb77d2b2b639"

​
status
enum<string>
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.
Available options:
ACCEPTED,
REJECTED,
DUPLICATE_IGNORED
​
redirectUrl
string<uri>

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

Example:

"https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79"

​
created
string<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

Example:

"2020-02-21T17:32:29Z"

​
expiresAt
string<date-time>

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

Example:

"2026-03-27T11:30:00Z"

​
checkoutCode
string

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

Example:

"PPGAFB57B93"

​
failureReason
object