> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawapay.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate checkout
The checkout endpoint creates a checkout and returns a `redirectUrl` for a hosted payment page that you forward the customer to.
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:
| Status | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `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`. |
### How to find out the final status of this checkout?
As the PawaPay Merchant API is an [asynchronous API](/v2/docs/what_to_know#callbacks), a checkout has its own lifecycle. You can find out the final status of an `ACCEPTED` checkout by either:
If you have configured callbacks, the callback with the final status of the checkout will be delivered to your callback URL.
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](/v2/api-reference/checkouts/expire-checkout) explicitly.
Headers related to [signatures](/v2/docs/signatures) must only be included if you have enabled “Only accept signed requests”.
Read more about it from the [PawaPay Dashboard documentation](/dashboard/other/system_conf/api_tokens#signed-requests).
## OpenAPI
````yaml openapi_v2 post /v2/checkouts
openapi: 3.0.0
info:
title: PawaPay Merchant API V2
description: Please find complete documentation from https://docs.pawapay.io/.
version: v2
x-logo:
url: >-
https://global-uploads.webflow.com/62824591015aa314fd308df1/6411b26596e3de3f52551c00_Logopawapay-p-500.png
href: https://docs.pawapay.io/
altText: PawaPay logo
servers:
- url: https://api.sandbox.pawapay.io
description: PawaPay Merchant API sandbox
- url: https://api.pawapay.io
description: PawaPay Merchant API production
security:
- bearerAuth: []
tags:
- name: deposits
x-displayName: Deposits
- name: split-payments
x-displayName: Split Payments
- name: checkouts
x-displayName: Checkouts
- name: payouts
x-displayName: Payouts
- name: refunds
x-displayName: Refunds
- name: remittances
x-displayName: Remittances
- name: payment-page
x-displayName: Payment Page
- name: toolkit
x-displayName: Toolkit
- name: finances
x-displayName: Finances
paths:
/v2/checkouts:
post:
tags:
- checkouts
summary: Initiate checkout
operationId: createCheckout
parameters:
- $ref: '#/components/parameters/Content-Digest'
- $ref: '#/components/parameters/Signature'
- $ref: '#/components/parameters/Signature-Input'
- $ref: '#/components/parameters/Accept-Signature'
- $ref: '#/components/parameters/Accept-Digest'
requestBody:
$ref: '#/components/requestBodies/CheckoutCreationRequest'
responses:
'200':
description: >-
Request has valid payload. See `status` to confirm if the checkout
was accepted for processing.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutCreationResponse'
examples:
ACCEPTED:
value:
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
DUPLICATE_IGNORED:
value:
checkoutId: afb57b93-7849-49aa-babb-4c3ccbfe3d79
status: DUPLICATE_IGNORED
created: '2026-03-27T10:30:00Z'
INVALID_PHONE_NUMBER:
value:
checkoutId: afb57b93-7849-49aa-babb-4c3ccbfe3d79
status: REJECTED
failureReason:
failureCode: INVALID_PHONE_NUMBER
failureMessage: >-
The phone number '2607634' seems to be invalid for the
provider 'MTN_MOMO_ZMB'.
'400':
description: >-
Request was rejected due to incompatibility with PawaPay API
specification.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutFailureResponse'
examples:
INVALID_INPUT:
value:
status: REJECTED
failureReason:
failureCode: INVALID_INPUT
failureMessage: >-
We are unable to parse the body of the request. Please
consult API documentation for valid request payload.
MISSING_PARAMETER:
value:
status: REJECTED
failureReason:
failureCode: MISSING_PARAMETER
failureMessage: >-
Request does not include the required parameter
'returnUrl'.
INVALID_PARAMETER:
value:
status: REJECTED
failureReason:
failureCode: INVALID_PARAMETER
failureMessage: >-
Value for parameter 'reason' is invalid. Please consult
API documentation for validation rules.
UNSUPPORTED_PARAMETER:
value:
status: REJECTED
failureReason:
failureCode: UNSUPPORTED_PARAMETER
failureMessage: >-
Request includes an unsupported parameter 'unsupported'.
Please remove unsupported parameters from request body.
'401':
description: >-
Authentication failed. Make sure you have added the API token into
the header. If using signatures, make sure they are valid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AuthenticationFailureResponse'
examples:
AUTHENTICATION_ERROR:
value:
status: REJECTED
failureReason:
failureCode: AUTHENTICATION_ERROR
failureMessage: The API token in the request is invalid.
'403':
description: Authorization failure. Please check your authentication token.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AuthorizationFailureResponse'
examples:
AUTHORISATION_ERROR:
value:
status: REJECTED
failureReason:
failureCode: AUTHORISATION_ERROR
failureMessage: >-
The API token in the request is not authorised for this
endpoint.
'500':
description: An unknown failure has occured.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/UnknownFailureResponse'
examples:
UNKNOWN_ERROR:
value:
failureReason:
failureCode: UNKNOWN_ERROR
failureMessage: Unable to process request due to an unknown problem.
components:
parameters:
Content-Digest:
in: header
name: Content-Digest
schema:
type: string
format: string
description: SHA-256 or SHA-512 hash of the request body.
required: false
Signature:
in: header
name: Signature
schema:
type: string
format: string
description: >-
Signature of the request according to
[RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).
required: false
Signature-Input:
in: header
name: Signature-Input
schema:
type: string
format: string
description: >-
Signature input according to
[RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).
required: false
Accept-Signature:
in: header
name: Accept-Signature
schema:
type: string
format: string
description: >-
Expected signature algorithm of the response according to
[RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).
required: false
Accept-Digest:
in: header
name: Accept-Digest
schema:
type: string
format: string
description: >-
Expected digest algorithm of the response according to
[RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).
required: false
requestBodies:
CheckoutCreationRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutInitiationRequest'
required: true
schemas:
CheckoutCreationResponse:
required:
- checkoutId
- status
type: object
properties:
checkoutId:
$ref: '#/components/schemas/InitiationPaymentId'
status:
$ref: '#/components/schemas/CheckoutCreationStatus'
redirectUrl:
$ref: '#/components/schemas/CheckoutRedirectUrl'
created:
$ref: '#/components/schemas/CreatedTimestamp'
expiresAt:
$ref: '#/components/schemas/CheckoutExpirationTimestamp'
checkoutCode:
$ref: '#/components/schemas/CheckoutCode'
failureReason:
$ref: '#/components/schemas/CheckoutCreationFailureReason'
CheckoutFailureResponse:
required:
- status
- failureReason
type: object
properties:
status:
type: string
enum:
- REJECTED
description: The status of the response will always be `REJECTED`
example: REJECTED
failureReason:
$ref: '#/components/schemas/CheckoutFailureReason'
AuthenticationFailureResponse:
required:
- failureCode
- failureMessage
type: object
properties:
status:
type: string
enum:
- REJECTED
description: The status of the response will always be `REJECTED`
example: REJECTED
failureReason:
$ref: '#/components/schemas/AuthenticationFailureReason'
AuthorizationFailureResponse:
required:
- failureCode
- failureMessage
type: object
properties:
status:
type: string
enum:
- REJECTED
description: The status of the response will always be `REJECTED`
example: REJECTED
failureReason:
$ref: '#/components/schemas/AuthorizationFailureReason'
UnknownFailureResponse:
required:
- failureCode
- failureMessage
type: object
properties:
failureReason:
type: object
properties:
failureCode:
type: string
description: >
Reason for the failure:
* `UNKNOWN_ERROR` - Unable to process request due to an unknown
problem.
example: UNKNOWN_ERROR
failureMessage:
type: string
description: A description of the failure
example: Unable to process request due to an unknown problem.
CheckoutInitiationRequest:
type: object
required:
- checkoutId
- returnUrl
properties:
checkoutId:
$ref: '#/components/schemas/InitiationPaymentId'
returnUrl:
$ref: '#/components/schemas/ReturnUrl'
returnMethod:
$ref: '#/components/schemas/CheckoutReturnMethod'
defaultLanguage:
type: string
description: >-
The default language of the checkout page. Supported languages are
`en` and `fr`.
enum:
- en
- fr
example: en
countries:
type: array
description: Restricts the checkout to the specified countries when provided.
items:
$ref: '#/components/schemas/CheckoutCountry'
example:
- ZMB
- CIV
expiresAfter:
type: integer
format: int32
minimum: 3
maximum: 60
description: >-
Number of minutes after creation when the checkout should expire.
Must be between 3 and 60. Defaults to 15 if not provided.
example: 60
amounts:
type: array
description: >
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.
items:
$ref: '#/components/schemas/CheckoutAmount'
payer:
$ref: '#/components/schemas/CheckoutPayer'
clientReferenceId:
$ref: '#/components/schemas/ClientReference'
reason:
$ref: '#/components/schemas/CheckoutReason'
metadata:
$ref: '#/components/schemas/TransactionMetadataRequest'
InitiationPaymentId:
minLength: 36
maxLength: 36
type: string
format: uuid
description: >
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.
example: f4401bd2-1568-4140-bf2d-eb77d2b2b639
CheckoutCreationStatus:
type: string
description: >
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`.
enum:
- ACCEPTED
- REJECTED
- DUPLICATE_IGNORED
CheckoutRedirectUrl:
type: string
format: uri
description: >-
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
CreatedTimestamp:
type: string
description: >-
The timestamp of when the payment was created in the PawaPay platform.
Format defined by 'date-time' in RFC3339 section 5.6 from
[IETF](https://tools.ietf.org/html/rfc3339#section-5.6)
format: date-time
example: '2020-02-21T17:32:29Z'
CheckoutExpirationTimestamp:
type: string
format: date-time
description: >-
The timestamp when the checkout and its hosted payment page are
scheduled to expire.
example: '2026-03-27T11:30:00Z'
CheckoutCode:
type: string
description: A unique identifier that forms part of the checkout's redirect URL.
example: PPGAFB57B93
CheckoutCreationFailureReason:
required:
- failureCode
type: object
properties:
failureCode:
type: string
description: >
Possible checkout initiation failure codes:
* `NO_AUTHENTICATION` - The API token was not found in the request
headers.
* `AUTHENTICATION_ERROR` - The API token in the request headers is
not valid.
* `AUTHORISATION_ERROR` - The API token in the request header is not
authorised to make this request.
* `HTTP_SIGNATURE_ERROR` - The signature you have passed with the
request did not pass verification.
* `INVALID_INPUT` - We were unable to parse the payload of the
request.
* `MISSING_PARAMETER` - A mandatory parameter was missing from the
request body.
* `UNSUPPORTED_PARAMETER` - An unsupported parameter was found in
the request body.
* `INVALID_PARAMETER` - A parameter had an incorrect value.
* `DUPLICATE_METADATA_FIELD` - A duplicate metadata field was found
in the request.
* `INVALID_PAYER_FORMAT` - The payer details are in an invalid
format.
* `INVALID_PHONE_NUMBER` - The phone number is in the wrong format
for the selected provider.
* `EXPIRES_AFTER_OUT_OF_BOUNDS` - The 'expiresAfter' is outside the
allowed range of 3 to 60 minutes.
* `DEPOSITS_NOT_ALLOWED` - Deposits are not enabled on your PawaPay
account for this operation.
* `UNKNOWN_ERROR` - An unknown error has occured.
enum:
- NO_AUTHENTICATION
- AUTHENTICATION_ERROR
- AUTHORISATION_ERROR
- HTTP_SIGNATURE_ERROR
- INVALID_INPUT
- MISSING_PARAMETER
- UNSUPPORTED_PARAMETER
- INVALID_PARAMETER
- DUPLICATE_METADATA_FIELD
- INVALID_PAYER_FORMAT
- INVALID_PHONE_NUMBER
- EXPIRES_AFTER_OUT_OF_BOUNDS
- DEPOSITS_NOT_ALLOWED
- UNKNOWN_ERROR
example: INVALID_PAYER_FORMAT
failureMessage:
type: string
description: Description of the reason for this failure.
CheckoutFailureReason:
required:
- failureCode
type: object
properties:
failureCode:
type: string
description: >
Reason for the failure:
* `INVALID_INPUT` - We were unable to parse the payload of the
request.
* `MISSING_PARAMETER` - A mandatory parameter was missing from the
request body.
* `UNSUPPORTED_PARAMETER` - An unsupported parameter was found in
the request body.
* `INVALID_PARAMETER` - A parameter had an incorrect value.
* `NOT_FOUND` - The specified checkout was not found.
enum:
- INVALID_INPUT
- MISSING_PARAMETER
- UNSUPPORTED_PARAMETER
- INVALID_PARAMETER
- NOT_FOUND
failureMessage:
type: string
description: A description of the failure
AuthenticationFailureReason:
required:
- failureReason
type: object
properties:
failureCode:
type: string
description: >
Reason for the failure:
* `NO_AUTHENTICATION` - The API token was not found in the request
headers.
* `AUTHENTICATION_ERROR` - The API token in the request headers is
not valid.
* `HTTP_SIGNATURE_ERROR` - The signature you have passed with the
request did not pass verification.
enum:
- NO_AUTHENTICATION
- AUTHENTICATION_ERROR
- HTTP_SIGNATURE_ERROR
failureMessage:
type: string
description: A description of the failure
AuthorizationFailureReason:
required:
- failureReason
type: object
properties:
failureCode:
type: string
description: >
Reason for the failure:
* `AUTHORISATION_ERROR` - The API Token in the request header is not
authorised to make this request.
* `DEPOSITS_NOT_ALLOWED` - Deposits are not enabled with the
provider on your PawaPay account.
* `PAYOUTS_NOT_ALLOWED` - Payouts are not enabled with the provider
on your PawaPay account.
* `REMITTANCES_NOT_ALLOWED` - Remittances are not enabled with the
provider on your PawaPay account.
* `REFUNDS_NOT_ALLOWED` - Refunds are not enabled with the provider
on your PawaPay account.
enum:
- AUTHORISATION_ERROR
- DEPOSITS_NOT_ALLOWED
- PAYOUTS_NOT_ALLOWED
- REMITTANCES_NOT_ALLOWED
- REFUNDS_NOT_ALLOWED
failureMessage:
type: string
description: A description of the failure
ReturnUrl:
type: string
format: uri
description: >-
The URL the customer should be redirected to after the payment is
processed.
example: https://merchant.example.com/checkout-result
CheckoutReturnMethod:
type: string
description: >
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".
enum:
- INSTANT
- COUNTDOWN
- CUSTOMER_ACTION
CheckoutCountry:
type: string
minLength: 3
maxLength: 3
description: >
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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements).
example: ZMB
CheckoutAmount:
required:
- country
- currency
- amount
type: object
properties:
country:
type: string
minLength: 3
maxLength: 3
description: >
The country this amount is for.
Format is ISO 3166-1 alpha-3, three character country code in upper
case. Read more from
[Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements).
example: ZMB
currency:
$ref: '#/components/schemas/Currency'
amount:
$ref: '#/components/schemas/Amount'
CheckoutPayer:
description: >-
Details of the payer that should be pre-filled for the hosted payment
page, if specified.
required:
- type
- accountDetails
type: object
properties:
type:
$ref: '#/components/schemas/AccountDetailsType'
accountDetails:
$ref: '#/components/schemas/CheckoutAccountDetails'
ClientReference:
type: string
description: >-
A reference to an entity in your system that this payment relates to.
For example, an invoice ID, customer ID etc.
example: INV-123456
CheckoutReason:
type: object
description: >-
Localized reason values shown to the customer inside the hosted payment
page.
additionalProperties:
$ref: '#/components/schemas/CustomerMessage'
example:
en: GOODS PURCHASE
TransactionMetadataRequest:
description: >
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.
type: array
items:
$ref: '#/components/schemas/TransactionMetadataRequestItem'
example:
- orderId: ORD-123456789
- customerId: customer@email.com
isPII: true
Currency:
type: string
description: >
The currency in which the `amount` is specified.
Format must be the ISO 4217 three character currency code in upper case.
Read more from
[Wikipedia](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
Find the supported currencies for the [provider](/v2/docs/providers).
The [active
configuration](/v2/api-reference/toolkit/active-configuration) endpoint
has all the providers configured for your account together with the
supported currencies.
example: ZMW
Amount:
minLength: 1
maxLength: 23
type: string
pattern: ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$
description: >
The amount of the payment.
Amount must follow below requirements or the request will be
**rejected**:
* Not all providers support decimals. Find which ones do from
[providers](/v2/docs/providers) or dynamically using [active
configuration](/v2/api-reference/toolkit/active-configuration) endpoint.
* Transaction limits apply. Find them from the [Active
Configuration](/v2/api-reference/toolkit/active-configuration) endpoint.
* Leading zeroes are not permitted except where the value is less than
1. For any value less than one, one and only one leading zero must be
supplied.
example: '15'
AccountDetailsType:
type: string
description: >-
The type of account involved in the transaction. At the moment, only
**MMO** is supported.
example: MMO
enum:
- MMO
CheckoutAccountDetails:
required:
- allowCustomerToOverride
type: object
properties:
phoneNumber:
$ref: '#/components/schemas/PhoneNumber'
provider:
$ref: '#/components/schemas/Provider'
allowCustomerToOverride:
type: boolean
description: >-
Indicates whether the customer may change the pre-filled payer
details in the hosted payment page.
example: true
CustomerMessage:
minLength: 4
maxLength: 22
type: string
pattern: ^[a-zA-Z0-9 ]+$
description: >
A short narration for the transaction.
Depending on the 'provider', this message may be visible to the customer
in the SMS receipt or within their transaction history.
Defaults to your company name as registered on your PawaPay account
trimmed to fit the length limitations.
example: Note of 4 to 22 chars
TransactionMetadataRequestItem:
type: object
properties:
additionalProperties:
type: string
description: >-
The metadata that you are attaching to the payment. For example
`"orderId":"ORD-123456789"`.
example: '"orderId": "ORD-123456789"'
isPII:
type: boolean
default: false
description: >-
Indicates whether the field contains personally identifiable
information. Used for compliance with GDPR or other relevant data
privacy laws.
example: true
example:
- orderId: ORD-123456789
- customerId: customer@email.com
isPII: true
PhoneNumber:
type: string
description: >
The phone number (MSISDN) of the customer paying or receiving payment.
The format is described in
[Wikipedia](https://en.wikipedia.org/wiki/MSISDN).
Use [predict provider](/v2/api-reference/toolkit/predict-provider) to
validate and sanitise the phone number.
Phone number validation has following rules:
* Only digits without whitespaces or any other separators or prefixes like '+'.
* Should not start with zero.
* Country code is mandatory.
* Should not exceed or be less than the valid length of specified country.
example: '260763456789'
Provider:
type: string
description: >
The provider represents the mobile money operator or processor that can
process payments.
Find here a list of all the supported [providers](/v2/docs/providers).
The [active
configuration](/v2/api-reference/toolkit/active-configuration) endpoint
provides the list of provider configured for your account.
You can use the [predict
provider](/v2/api-reference/toolkit/predict-provider) enpoint to predict
the provider to use based on the phone number (MSISDN).
example: MTN_MOMO_ZMB
securitySchemes:
bearerAuth:
type: http
description: >-
See
[Authentication](/v2/docs/how_to_start#how-to-authenticate-calls-to-the-merchant-api).
scheme: bearer
bearerFormat: JWT
````