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.
Store the checkoutCode from the response. It is appended to your returnUrl as a query parameter when the customer is returned to your site, so you can identify which checkout they are returning from.
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, 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.
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.
Show child attributes
payer
object
Details of the payer that should be pre-filled for the hosted payment page, if specified.
Show child attributes
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.
Show child attributes
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.
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.
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 code identifying the checkout. It forms the path of the hosted payment page's redirectUrl and is appended to your returnUrl as the checkoutCode query parameter when the customer is returned to your site. Store it after initiating the checkout, so you can identify which checkout the customer is returning from.
Example:
"7mVk1x8UbTamQ64xGR"
failureReason
object
Show child attributes
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"PawaPay Merchant API","colors":{"primary":"#7D3CFF","light":"#C3AFFF","dark":"#7D3CFF"},"logo":{"light":"https://mintcdn.com/pawapay/Kh3dyKjADbJS5N9-/images/pawapay_logo_black.svg?fit=max\u0026auto=format\u0026n=Kh3dyKjADbJS5N9-\u0026q=85\u0026s=dcb6b0f2f8b6c6e735e80732b4b9a8a0","dark":"https://mintcdn.com/pawapay/Kh3dyKjADbJS5N9-/images/pawapay_logo_white.svg?fit=max\u0026auto=format\u0026n=Kh3dyKjADbJS5N9-\u0026q=85\u0026s=045ebe0ed432187a1da3097d6a600fd0","href":"https://pawapay.io"},"favicon":"https://mintcdn.com/pawapay/5t50YVnmXOFXUEhT/images/favicon.png?fit=max\u0026auto=format\u0026n=5t50YVnmXOFXUEhT\u0026q=85\u0026s=c97dd58d1705627ef95648764043828d","background":{"decoration":"gradient"},"navbar":{"links":[{"href":"https://dashboard.sandbox.pawapay.io","label":"Sandbox login"}],"primary":{"type":"button","label":"Create account","href":"https://dashboard.sandbox.pawapay.io/#/merchant-signup"}},"footer":{"socials":{"website":"https://pawapay.io","linkedin":"https://www.linkedin.com/company/pawapay"}},"search":{"prompt":"Search/ask from AI (MIGHT NOT BE ACCURATE) "},"fonts":{"heading":{"family":"Instrument Sans","weight":600},"body":{"family":"Instrument Sans","weight":400}},"integrations":{"clearbit":{"publicApiKey":"pk_c7e1c1e424425978e94bb81fd8af7a14"},"mixpanel":{"projectToken":"b877b7fe27113f1d7e427b2cdbe8515f","region":"eu"}},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Run in Postman","icon":"circle-play","href":"https://app.getpostman.com/run-collection/25129489-56cbaf62-56c2-4734-bf1f-f61d369cc9e3?action=collection%2Ffork\u0026source=rip_markdown\u0026collection-url=entityId%3D25129489-56cbaf62-56c2-4734-bf1f-f61d369cc9e3%26entityType%3Dcollection%26workspaceId%3D8c3e7775-3da5-4bab-8a8c-ffb331ccfe27"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"pawapay","hasAudioNarration":false,"actualSubdomain":"pawapay","customDomains":["docs.pawapay.io"],"gitSource":{"type":"github","owner":"pawapay","repo":"docs-hub","deployBranch":"develop","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"issues":true,"thumbs":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6afe97222238c3c29ae646ac","clientVersion":"0.0.4227","searchFilterCounts":[{"language":"default","tag":"API Reference","count":56},{"language":"default","tag":"API docs","count":27},{"language":"default","tag":"Dashboard Docs","count":26},{"language":"default","tag":"Payouts","count":12},{"language":"default","tag":"Introduction","count":11},{"language":"default","tag":"Finances","count":10},{"language":"default","tag":"Refunds","count":9},{"language":"default","tag":"Deposits","count":8},{"language":"default","tag":"Toolkit","count":8},{"language":"default","tag":"Overview","count":7}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[],"googleFontsInlined":true},"customCss":[]}
{"page":{"pagePath":"v2/api-reference/checkouts/initiate-checkout","slug":"/v2/api-reference/checkouts/initiate-checkout","pageMetadata":{"openapi":"openapi_v2 post /v2/checkouts","description":"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.","title":"Initiate checkout","href":"/v2/api-reference/checkouts/initiate-checkout"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{Card,CardGroup,Heading,Info,Table}=_components;if(!Card)_missingMdxReference(`Card`,true);if(!CardGroup)_missingMdxReference(`CardGroup`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`The checkout endpoint creates a checkout and returns a `,_jsx(_components.code,{children:`redirectUrl`}),` for a hosted payment page that you forward the customer to.`]}),`\n`,_jsx(Card,{title:`Check the guide!`,icon:`readme`,href:`/v2/docs/checkouts`,horizontal:`true`,children:_jsx(_components.p,{children:`Follow the step-by-step guide on how to create, use, and track checkouts.`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`This API call is `,_jsx(_components.strong,{children:`idempotent`}),`, which means it is safe to submit a request with the same `,_jsx(_components.code,{children:`checkoutId`}),` multiple times.`]}),`\n`,_jsxs(_components.li,{children:[`Duplicate requests with the same `,_jsx(_components.code,{children:`checkoutId`}),` will be ignored with the `,_jsx(_components.code,{children:`DUPLICATE_IGNORED`}),` status in the response.`]}),`\n`,_jsxs(_components.li,{children:[`Always check the `,_jsx(_components.code,{children:`status`}),` in the response for each request. When it is `,_jsx(_components.code,{children:`REJECTED`}),`, the `,_jsx(_components.code,{children:`failureReason`}),` describes what went wrong through its `,_jsx(_components.code,{children:`failureCode`}),` and `,_jsx(_components.code,{children:`failureMessage`}),`.`]}),`\n`,_jsx(_components.li,{children:`A checkout is the single reference for the whole payment, including any retries the customer makes.`}),`\n`,_jsx(_components.li,{children:`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.`}),`\n`,_jsxs(_components.li,{children:[`If the checkout is accepted, redirect the customer to the returned `,_jsx(_components.code,{children:`redirectUrl`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Store the `,_jsx(_components.code,{children:`checkoutCode`}),` from the response. It is appended to your `,_jsx(_components.code,{children:`returnUrl`}),` as a query parameter when the customer is returned to your site, so you can identify which checkout they are returning from.`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`Each request can get one of the statuses on initiation:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Status`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`ACCEPTED`})}),_jsxs(_components.td,{children:[`The checkout has been `,_jsx(_components.strong,{children:`accepted`}),` and the hosted payment page has been created.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`REJECTED`})}),_jsxs(_components.td,{children:[`The checkout has been `,_jsx(_components.strong,{children:`rejected`}),`. See `,_jsx(_components.code,{children:`failureReason`}),` for details.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`DUPLICATE_IGNORED`})}),_jsxs(_components.td,{children:[`The checkout has been ignored as a duplicate of an already accepted checkout. Deduplication is based on `,_jsx(_components.code,{children:`checkoutId`}),`.`]})]})]})]}),`\n`,_jsx(Heading,{level:`3`,id:`how-to-find-out-the-final-status-of-this-checkout`,children:`How to find out the final status of this checkout?`}),`\n`,_jsxs(_components.p,{children:[`As the PawaPay Merchant API is an `,_jsx(_components.a,{href:`/v2/docs/what_to_know#callbacks`,children:`asynchronous API`}),`, a checkout has its own lifecycle. You can find out the final status of an `,_jsx(_components.code,{children:`ACCEPTED`}),` checkout by either:`]}),`\n`,_jsxs(CardGroup,{cols:2,children:[_jsx(Card,{title:`Waiting for a callback`,icon:`webhook`,href:`/v2/api-reference/checkouts/checkout-callback`,horizontal:`true`,children:_jsx(_components.p,{children:`If you have configured callbacks, the callback with the final status of the checkout will be delivered to your callback URL.`})}),_jsx(Card,{title:`Checking the status`,icon:`code-compare`,href:`/v2/api-reference/checkouts/check-checkout-status`,horizontal:`true`,children:_jsxs(_components.p,{children:[`Or poll the `,_jsx(_components.code,{children:`Check Checkout Status`}),` endpoint for the latest checkout and payment status.`]})})]}),`\n`,_jsxs(_components.p,{children:[`If the checkout should no longer be used, you can `,_jsx(_components.a,{href:`/v2/api-reference/checkouts/expire-checkout`,children:`expire it`}),` explicitly.`]}),`\n`,_jsx(Info,{children:_jsxs(_components.p,{children:[`Headers related to `,_jsx(_components.a,{href:`/v2/docs/signatures`,children:`signatures`}),` must only be included if you have enabled “Only accept signed requests”.\nRead more about it from the `,_jsx(_components.a,{href:`/dashboard/other/system_conf/api_tokens#signed-requests`,children:`PawaPay Dashboard documentation`}),`.`]})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"openapi":"openapi_v2 post /v2/checkouts","description":"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.","title":"Initiate checkout","href":"/v2/api-reference/checkouts/initiate-checkout"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"How to find out the final status of this checkout?","slug":"how-to-find-out-the-final-status-of-this-checkout","depth":3,"children":[]}],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["checkouts"],"summary":"Initiate checkout","operationId":"createCheckout","requestBody":"3e1ce480-42bf-4d93-bd8e-46982e8a6793","parameters":["4a4c2a56-c5aa-4869-81bb-97783fb8fec6","6bd28bbf-6ab8-4e77-9714-1fb151655d1b","7ee35788-015d-4302-99f6-596921bc595a","f9caa9b0-725f-4578-b4da-c73cdf28f1f5","dc1303d4-627b-4cfc-b4b9-a3bad810fa49"],"responses":{"200":"8e30f370-1524-4b70-b4ab-4485a572ce0c","400":"705d9f45-d115-4c49-ab8c-69413d696f41","401":"f7ea0345-9241-4f7f-8008-178375b1b43e","403":"a7af92ff-dd34-4ed9-86bb-5d55826700dd","500":"506857e9-4490-488d-a4c5-3caf19368fc3"},"method":"post","type":"path","servers":["332d3246-544a-43e8-a048-d892bbfd6c56","b2edd67b-6644-48f0-ad04-0671ca7dc003"],"security":["b5c32e51-470f-4ecf-869d-e12b6610cbf5"],"path":"/v2/checkouts","baseUrlOptions":["https://api.sandbox.pawapay.io","https://api.pawapay.io"],"title":"Initiate checkout","description":"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"4a4c2a56-c5aa-4869-81bb-97783fb8fec6":{"in":"header","name":"Content-Digest","schema":{"type":"string","format":"string","description":"SHA-256 or SHA-512 hash of the request body.","isRequired":false,"uniqueKey":"","typeLabel":"string\u003cstring>"},"required":false},"6bd28bbf-6ab8-4e77-9714-1fb151655d1b":{"in":"header","name":"Signature","schema":{"type":"string","format":"string","description":"Signature of the request according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).","isRequired":false,"uniqueKey":"","typeLabel":"string\u003cstring>"},"required":false},"7ee35788-015d-4302-99f6-596921bc595a":{"in":"header","name":"Signature-Input","schema":{"type":"string","format":"string","description":"Signature input according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).","isRequired":false,"uniqueKey":"","typeLabel":"string\u003cstring>"},"required":false},"f9caa9b0-725f-4578-b4da-c73cdf28f1f5":{"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/).","isRequired":false,"uniqueKey":"","typeLabel":"string\u003cstring>"},"required":false},"dc1303d4-627b-4cfc-b4b9-a3bad810fa49":{"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/).","isRequired":false,"uniqueKey":"","typeLabel":"string\u003cstring>"},"required":false}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["checkoutId","returnUrl"],"properties":{"checkoutId":{"minLength":36,"maxLength":36,"type":"string","format":"uuid","description":"A UUIDv4 based unique ID for this payment. \nWe require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments.\nPlease store this ID in your system before initiating the payment with PawaPay.\n","example":"f4401bd2-1568-4140-bf2d-eb77d2b2b639","isRequired":true,"uniqueKey":"checkoutId","typeLabel":"string\u003cuuid>"},"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","isRequired":true,"uniqueKey":"returnUrl","typeLabel":"string\u003curi>"},"returnMethod":{"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.\n* `INSTANT` - The customer is redirected back immediately, with no extra screen.\n* `COUNTDOWN` - A short countdown is shown, then the customer is redirected automatically.\n* `CUSTOMER_ACTION` - The checkout page waits until the customer presses \"Return to merchant\".\n","enum":["INSTANT","COUNTDOWN","CUSTOMER_ACTION"],"uniqueKey":"returnMethod","typeLabel":"enum\u003cstring>"},"defaultLanguage":{"type":"string","description":"The default language of the checkout page. Supported languages are `en` and `fr`.","enum":["en","fr"],"example":"en","uniqueKey":"defaultLanguage","typeLabel":"enum\u003cstring>"},"countries":{"type":"array","description":"Restricts the checkout to the specified countries when provided.","items":{"type":"string","minLength":3,"maxLength":3,"description":"A country that the hosted payment page allows for this checkout.\n\nFormat 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).\n","example":"ZMB","uniqueKey":"countries.items.[INDEX]","typeLabel":"string"},"example":["ZMB","CIV"],"uniqueKey":"countries","typeLabel":"string[]"},"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,"uniqueKey":"expiresAfter","typeLabel":"integer\u003cint32>"},"amounts":{"type":"array","description":"The fixed amount the customer is asked to pay, specified per country and currency.\n\nThis 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.\n\nIf `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.\n","items":{"required":["country","currency","amount"],"type":"object","properties":{"country":{"type":"string","minLength":3,"maxLength":3,"description":"The country this amount is for.\n\nFormat 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).\n","example":"ZMB","isRequired":true,"uniqueKey":"amounts.items.[INDEX].country","typeLabel":"string"},"currency":{"type":"string","description":"The currency in which the `amount` is specified.\n\nFormat 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).\n\nFind the supported currencies for the [provider](/v2/docs/providers).\n\nThe [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint has all the providers configured for your account together with the supported currencies.\n","example":"ZMW","isRequired":true,"uniqueKey":"amounts.items.[INDEX].currency","typeLabel":"string"},"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.\n\nAmount must follow below requirements or the request will be **rejected**:\n* 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.\n* Transaction limits apply. Find them from the [Active Configuration](/v2/api-reference/toolkit/active-configuration) endpoint.\n* 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.\n","example":"15","isRequired":true,"uniqueKey":"amounts.items.[INDEX].amount","typeLabel":"string"}},"uniqueKey":"amounts.items.[INDEX]","typeLabel":"object"},"uniqueKey":"amounts","typeLabel":"object[]"},"payer":{"description":"Details of the payer that should be pre-filled for the hosted payment page, if specified.","required":["type","accountDetails"],"type":"object","properties":{"type":{"type":"string","description":"The type of account involved in the transaction. At the moment, only **MMO** is supported.","example":"MMO","enum":["MMO"],"isRequired":true,"uniqueKey":"payer.type","typeLabel":"enum\u003cstring>"},"accountDetails":{"required":["allowCustomerToOverride"],"type":"object","properties":{"allowCustomerToOverride":{"type":"boolean","description":"Indicates whether the customer may change the pre-filled payer details in the hosted payment page.","example":true,"isRequired":true,"uniqueKey":"payer.accountDetails.allowCustomerToOverride","typeLabel":"boolean"},"phoneNumber":{"type":"string","description":"The phone number (MSISDN) of the customer paying or receiving payment.\nThe format is described in [Wikipedia](https://en.wikipedia.org/wiki/MSISDN). \n\nUse [predict provider](/v2/api-reference/toolkit/predict-provider) to validate and sanitise the phone number.\n\nPhone number validation has following rules:\n * Only digits without whitespaces or any other separators or prefixes like '+'.\n * Should not start with zero.\n * Country code is mandatory.\n * Should not exceed or be less than the valid length of specified country.\n","example":"260763456789","uniqueKey":"payer.accountDetails.phoneNumber","typeLabel":"string"},"provider":{"type":"string","description":"The provider represents the mobile money operator or processor that can process payments.\n\nFind here a list of all the supported [providers](/v2/docs/providers). \n\nThe [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint provides the list of provider configured for your account.\n\nYou can use the [predict provider](/v2/api-reference/toolkit/predict-provider) enpoint to predict the provider to use based on the phone number (MSISDN).\n","example":"MTN_MOMO_ZMB","uniqueKey":"payer.accountDetails.provider","typeLabel":"string"}},"isRequired":true,"uniqueKey":"payer.accountDetails","typeLabel":"object"}},"uniqueKey":"payer","typeLabel":"object"},"clientReferenceId":{"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","uniqueKey":"clientReferenceId","typeLabel":"string"},"reason":{"type":"object","description":"Localized reason values shown to the customer inside the hosted payment page.","additionalProperties":{"minLength":4,"maxLength":22,"type":"string","pattern":"^[a-zA-Z0-9 ]+$","description":"A short narration for the transaction. \nDepending on the 'provider', this message may be visible to the customer in the SMS receipt or within their transaction history.\n\nDefaults to your company name as registered on your PawaPay account trimmed to fit the length limitations.\n","example":"Note of 4 to 22 chars","uniqueKey":"reason.additionalProperties","typeLabel":"string"},"example":{"en":"GOODS PURCHASE"},"uniqueKey":"reason","typeLabel":"object"},"metadata":{"description":"A list of metadata that you can attach to the payment for providing additional context about the payment.\nFor example, adding the channel from which the payment was initated, product ID or anything else that might help your operations team.\n\nMetadata will be included in:\n- In the dashboard on payment details pages\n- Financial statements as JSON object \n- Callbacks\n\nMetadata can be used when searching in the PawaPay Dashboard. \nFull value of the metadata field must be used for searches.\n\nMetadata will not be visible to the customer that is involved in this payment. \n\nUp to 10 metadata fields can be attached to a payment.\n","type":"array","items":{"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\"","uniqueKey":"metadata.items.[INDEX].\\additionalProperties","typeLabel":"string"},"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,"uniqueKey":"metadata.items.[INDEX].isPII","typeLabel":"boolean"}},"example":[{"orderId":"ORD-123456789"},{"customerId":"customer@email.com","isPII":true}],"uniqueKey":"metadata.items.[INDEX]","typeLabel":"object"},"example":[{"orderId":"ORD-123456789"},{"customerId":"customer@email.com","isPII":true}],"uniqueKey":"metadata","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"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}]}}},"exampleType":"generated"}},"required":true,"exampleType":"generated"},"responses":{"8e30f370-1524-4b70-b4ab-4485a572ce0c":{"description":"Request has valid payload. See `status` to confirm if the checkout was accepted for processing.","content":{"application/json":{"schema":{"required":["checkoutId","status"],"type":"object","properties":{"checkoutId":{"minLength":36,"maxLength":36,"type":"string","format":"uuid","description":"A UUIDv4 based unique ID for this payment. \nWe require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments.\nPlease store this ID in your system before initiating the payment with PawaPay.\n","example":"f4401bd2-1568-4140-bf2d-eb77d2b2b639","isRequired":true,"uniqueKey":"checkoutId","typeLabel":"string\u003cuuid>"},"status":{"type":"string","description":"The initiation status of the checkout:\n* `ACCEPTED` - The checkout has been **accepted** and the hosted payment page has been created.\n* `REJECTED` - The checkout has been **rejected**. See `failureReason` for details.\n* `DUPLICATE_IGNORED` - The checkout has been ignored as a duplicate of an already accepted checkout. Deduplication is based on `checkoutId`.\n","enum":["ACCEPTED","REJECTED","DUPLICATE_IGNORED"],"isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"redirectUrl":{"type":"string","format":"uri","description":"The URL to which the customer must be redirected to open and complete the hosted payment page.","example":"https://checkout.sandbox.pawapay.io/7mVk1x8UbTamQ64xGR","uniqueKey":"redirectUrl","typeLabel":"string\u003curi>"},"created":{"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","uniqueKey":"created","typeLabel":"string\u003cdate-time>"},"expiresAt":{"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","uniqueKey":"expiresAt","typeLabel":"string\u003cdate-time>"},"checkoutCode":{"type":"string","description":"A unique code identifying the checkout. It forms the path of the hosted payment page's `redirectUrl` and is appended to your `returnUrl` as the `checkoutCode` query parameter when the customer is returned to your site. Store it after initiating the checkout, so you can identify which checkout the customer is returning from.","example":"7mVk1x8UbTamQ64xGR","uniqueKey":"checkoutCode","typeLabel":"string"},"failureReason":{"required":["failureCode"],"type":"object","properties":{"failureCode":{"type":"string","description":"Possible checkout initiation failure codes:\n* `NO_AUTHENTICATION` - The API token was not found in the request headers.\n* `AUTHENTICATION_ERROR` - The API token in the request headers is not valid.\n* `AUTHORISATION_ERROR` - The API token in the request header is not authorised to make this request.\n* `HTTP_SIGNATURE_ERROR` - The signature you have passed with the request did not pass verification.\n* `INVALID_INPUT` - We were unable to parse the payload of the request.\n* `MISSING_PARAMETER` - A mandatory parameter was missing from the request body.\n* `UNSUPPORTED_PARAMETER` - An unsupported parameter was found in the request body.\n* `INVALID_PARAMETER` - A parameter had an incorrect value.\n* `DUPLICATE_METADATA_FIELD` - A duplicate metadata field was found in the request.\n* `INVALID_PAYER_FORMAT` - The payer details are in an invalid format.\n* `INVALID_PHONE_NUMBER` - The phone number is in the wrong format for the selected provider.\n* `EXPIRES_AFTER_OUT_OF_BOUNDS` - The 'expiresAfter' is outside the allowed range of 3 to 60 minutes.\n* `DEPOSITS_NOT_ALLOWED` - Deposits are not enabled on your PawaPay account for this operation.\n* `UNKNOWN_ERROR` - An unknown error has occured.\n","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","isRequired":true,"uniqueKey":"failureReason.failureCode","typeLabel":"enum\u003cstring>"},"failureMessage":{"type":"string","description":"Description of the reason for this failure.","uniqueKey":"failureReason.failureMessage","typeLabel":"string"}},"uniqueKey":"failureReason","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"ACCEPTED":{"title":"ACCEPTED","value":{"checkoutId":"afb57b93-7849-49aa-babb-4c3ccbfe3d79","status":"ACCEPTED","redirectUrl":"https://checkout.sandbox.pawapay.io/7mVk1x8UbTamQ64xGR","created":"2026-03-27T10:30:00Z","expiresAt":"2026-03-27T11:30:00Z","checkoutCode":"7mVk1x8UbTamQ64xGR"}},"DUPLICATE_IGNORED":{"title":"DUPLICATE_IGNORED","value":{"checkoutId":"afb57b93-7849-49aa-babb-4c3ccbfe3d79","status":"DUPLICATE_IGNORED","created":"2026-03-27T10:30:00Z"}},"INVALID_PHONE_NUMBER":{"title":"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'."}}}},"exampleType":"examples"}},"exampleType":"examples"},"705d9f45-d115-4c49-ab8c-69413d696f41":{"description":"Request was rejected due to incompatibility with PawaPay API specification.","content":{"application/json":{"schema":{"required":["status","failureReason"],"type":"object","properties":{"status":{"type":"string","enum":["REJECTED"],"description":"The status of the response will always be `REJECTED`","example":"REJECTED","isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"failureReason":{"required":["failureCode"],"type":"object","properties":{"failureCode":{"type":"string","description":"Reason for the failure:\n* `INVALID_INPUT` - We were unable to parse the payload of the request.\n* `MISSING_PARAMETER` - A mandatory parameter was missing from the request body.\n* `UNSUPPORTED_PARAMETER` - An unsupported parameter was found in the request body.\n* `INVALID_PARAMETER` - A parameter had an incorrect value.\n* `NOT_FOUND` - The specified checkout was not found.\n","enum":["INVALID_INPUT","MISSING_PARAMETER","UNSUPPORTED_PARAMETER","INVALID_PARAMETER","NOT_FOUND"],"isRequired":true,"uniqueKey":"failureReason.failureCode","typeLabel":"enum\u003cstring>"},"failureMessage":{"type":"string","description":"A description of the failure","uniqueKey":"failureReason.failureMessage","typeLabel":"string"}},"isRequired":true,"uniqueKey":"failureReason","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"INVALID_INPUT":{"title":"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":{"title":"MISSING_PARAMETER","value":{"status":"REJECTED","failureReason":{"failureCode":"MISSING_PARAMETER","failureMessage":"Request does not include the required parameter 'returnUrl'."}}},"INVALID_PARAMETER":{"title":"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":{"title":"UNSUPPORTED_PARAMETER","value":{"status":"REJECTED","failureReason":{"failureCode":"UNSUPPORTED_PARAMETER","failureMessage":"Request includes an unsupported parameter 'unsupported'. Please remove unsupported parameters from request body."}}}},"exampleType":"examples"}},"exampleType":"examples"},"f7ea0345-9241-4f7f-8008-178375b1b43e":{"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":{"type":"object","required":["failureCode","failureMessage"],"properties":{"status":{"type":"string","enum":["REJECTED"],"description":"The status of the response will always be `REJECTED`","example":"REJECTED","uniqueKey":"status","typeLabel":"enum\u003cstring>"},"failureReason":{"required":["failureReason"],"type":"object","properties":{"failureCode":{"type":"string","description":"Reason for the failure:\n* `NO_AUTHENTICATION` - The API token was not found in the request headers.\n* `AUTHENTICATION_ERROR` - The API token in the request headers is not valid.\n* `HTTP_SIGNATURE_ERROR` - The signature you have passed with the request did not pass verification.\n","enum":["NO_AUTHENTICATION","AUTHENTICATION_ERROR","HTTP_SIGNATURE_ERROR"],"uniqueKey":"failureReason.failureCode","typeLabel":"enum\u003cstring>"},"failureMessage":{"type":"string","description":"A description of the failure","uniqueKey":"failureReason.failureMessage","typeLabel":"string"}},"uniqueKey":"failureReason","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"AUTHENTICATION_ERROR":{"title":"AUTHENTICATION_ERROR","value":{"status":"REJECTED","failureReason":{"failureCode":"AUTHENTICATION_ERROR","failureMessage":"The API token in the request is invalid."}}}},"exampleType":"examples"}},"exampleType":"examples"},"a7af92ff-dd34-4ed9-86bb-5d55826700dd":{"description":"Authorization failure. Please check your authentication token.","content":{"application/json":{"schema":{"type":"object","required":["failureCode","failureMessage"],"properties":{"status":{"type":"string","enum":["REJECTED"],"description":"The status of the response will always be `REJECTED`","example":"REJECTED","uniqueKey":"status","typeLabel":"enum\u003cstring>"},"failureReason":{"required":["failureReason"],"type":"object","properties":{"failureCode":{"type":"string","description":"Reason for the failure:\n* `AUTHORISATION_ERROR` - The API Token in the request header is not authorised to make this request.\n* `DEPOSITS_NOT_ALLOWED` - Deposits are not enabled with the provider on your PawaPay account.\n* `PAYOUTS_NOT_ALLOWED` - Payouts are not enabled with the provider on your PawaPay account.\n* `REMITTANCES_NOT_ALLOWED` - Remittances are not enabled with the provider on your PawaPay account.\n* `REFUNDS_NOT_ALLOWED` - Refunds are not enabled with the provider on your PawaPay account.\n","enum":["AUTHORISATION_ERROR","DEPOSITS_NOT_ALLOWED","PAYOUTS_NOT_ALLOWED","REMITTANCES_NOT_ALLOWED","REFUNDS_NOT_ALLOWED"],"uniqueKey":"failureReason.failureCode","typeLabel":"enum\u003cstring>"},"failureMessage":{"type":"string","description":"A description of the failure","uniqueKey":"failureReason.failureMessage","typeLabel":"string"}},"uniqueKey":"failureReason","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"AUTHORISATION_ERROR":{"title":"AUTHORISATION_ERROR","value":{"status":"REJECTED","failureReason":{"failureCode":"AUTHORISATION_ERROR","failureMessage":"The API token in the request is not authorised for this endpoint."}}}},"exampleType":"examples"}},"exampleType":"examples"},"506857e9-4490-488d-a4c5-3caf19368fc3":{"description":"An unknown failure has occured.","content":{"application/json":{"schema":{"type":"object","required":["failureCode","failureMessage"],"properties":{"failureReason":{"type":"object","properties":{"failureCode":{"type":"string","description":"Reason for the failure:\n* `UNKNOWN_ERROR` - Unable to process request due to an unknown problem.\n","example":"UNKNOWN_ERROR","uniqueKey":"failureReason.failureCode","typeLabel":"string"},"failureMessage":{"type":"string","description":"A description of the failure","example":"Unable to process request due to an unknown problem.","uniqueKey":"failureReason.failureMessage","typeLabel":"string"}},"uniqueKey":"failureReason","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"UNKNOWN_ERROR":{"title":"UNKNOWN_ERROR","value":{"failureReason":{"failureCode":"UNKNOWN_ERROR","failureMessage":"Unable to process request due to an unknown problem."}}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"b5c32e51-470f-4ecf-869d-e12b6610cbf5":{"bearerAuth":{"type":"http","description":"See [Authentication](/v2/docs/how_to_start#how-to-authenticate-calls-to-the-merchant-api).","scheme":"bearer","bearerFormat":"JWT","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"332d3246-544a-43e8-a048-d892bbfd6c56":{"url":"https://api.sandbox.pawapay.io","description":"PawaPay Merchant API sandbox"},"b2edd67b-6644-48f0-ad04-0671ca7dc003":{"url":"https://api.pawapay.io","description":"PawaPay Merchant API production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","description":"See [Authentication](/v2/docs/how_to_start#how-to-authenticate-calls-to-the-merchant-api).","scheme":"bearer","bearerFormat":"JWT","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"See [Authentication](/v2/docs/how_to_start#how-to-authenticate-calls-to-the-merchant-api).","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"v2/api-reference/openapi_v2.yaml"},"subdomain":"pawapay","siteName":"PawaPay Merchant API","title":"Initiate checkout - PawaPay Merchant API","navMaps":{"firstHrefInVersion":{"v2":{"href":"/v2/api-reference/checkouts/initiate-checkout","matchLevel":0},"v1":{"href":"/getting_started","matchLevel":4}},"firstHrefInLanguage":{}},"lastModified":"2026-11-11T15:22:38.728Z","originalFileLocation":"v2/api-reference/checkouts/initiate-checkout.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.\">\u003cmeta data-mint-head name=\"application-name\" content=\"PawaPay Merchant API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Initiate checkout - PawaPay Merchant API\">\u003cmeta data-mint-head property=\"og:description\" content=\"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"PawaPay Merchant API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://pawapay.mintlify.site/_mintlify/api/og/v2?division=Checkouts\u0026amp;title=Initiate+checkout\u0026amp;description=API+reference%3A+create+a+PawaPay+checkout+and+get+a+redirectUrl+to+a+hosted+mobile+money+payment+page.+Idempotent+by+checkoutId.\u0026amp;theme=6df4a9d744128cd68aba8e91\u0026amp;signature=f386a959bdada12254f7f207af33d0bea944cf9606bbeec2db2e80961682a641\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Initiate checkout - PawaPay Merchant API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://pawapay.mintlify.site/_mintlify/api/og/v2?division=Checkouts\u0026amp;title=Initiate+checkout\u0026amp;description=API+reference%3A+create+a+PawaPay+checkout+and+get+a+redirectUrl+to+a+hosted+mobile+money+payment+page.+Idempotent+by+checkoutId.\u0026amp;theme=6df4a9d744128cd68aba8e91\u0026amp;signature=f386a959bdada12254f7f207af33d0bea944cf9606bbeec2db2e80961682a641\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/pawapay/1ir90k4Vxmsj1N5e/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"PawaPay Merchant API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#7D3CFF\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/v2/api-reference/checkouts/initiate-checkout.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.pawapay.io/#organization\",\"name\":\"PawaPay Merchant API\",\"url\":\"https://docs.pawapay.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/pawapay/Kh3dyKjADbJS5N9-/images/pawapay_logo_black.svg?fit=max\u0026auto=format\u0026n=Kh3dyKjADbJS5N9-\u0026q=85\u0026s=dcb6b0f2f8b6c6e735e80732b4b9a8a0\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.pawapay.io#website\",\"name\":\"PawaPay Merchant API\",\"url\":\"https://docs.pawapay.io\",\"publisher\":{\"@id\":\"https://docs.pawapay.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout#webpage\",\"url\":\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout\",\"name\":\"Initiate checkout\",\"description\":\"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.\",\"dateModified\":\"2026-11-11T15:22:38.728Z\",\"isPartOf\":{\"@id\":\"https://docs.pawapay.io#website\"},\"breadcrumb\":{\"@id\":\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"PawaPay Merchant API\",\"item\":\"https://docs.pawapay.io\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Initiate checkout\",\"item\":\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout#apireference\",\"headline\":\"Initiate checkout\",\"name\":\"Initiate checkout\",\"description\":\"API reference: create a PawaPay checkout and get a redirectUrl to a hosted mobile money payment page. Idempotent by checkoutId.\",\"url\":\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout\",\"mainEntityOfPage\":{\"@id\":\"https://docs.pawapay.io/v2/api-reference/checkouts/initiate-checkout#webpage\"},\"dateModified\":\"2026-11-11T15:22:38.728Z\",\"publisher\":{\"@id\":\"https://docs.pawapay.io/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.pawapay.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"PawaPay Merchant API\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"PawaPay Merchant API\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/v2/api-reference/checkouts/initiate-checkout.md","siteName":"PawaPay Merchant API","nav":{"global":{"anchors":[{"anchor":"Run in Postman","icon":"circle-play","href":"https://app.getpostman.com/run-collection/25129489-56cbaf62-56c2-4734-bf1f-f61d369cc9e3?action=collection%2Ffork\u0026source=rip_markdown\u0026collection-url=entityId%3D25129489-56cbaf62-56c2-4734-bf1f-f61d369cc9e3%26entityType%3Dcollection%26workspaceId%3D8c3e7775-3da5-4bab-8a8c-ffb331ccfe27"}]},"versions":[{"version":"v2","tabs":[{"tab":"API docs","pages":[{"title":"API docs","href":"/v2/docs/welcome"}]},{"tab":"API Reference","groups":[{"group":"Deposits","pages":[{"openapi":"v2/api-reference/openapi_v2.yaml POST /v2/deposits","title":"Initiate deposit","href":"/v2/api-reference/deposits/initiate-deposit"},{"openapi":"openapi_v2 get /v2/deposits/{depositId}","title":"Check deposit status","href":"/v2/api-reference/deposits/check-deposit-status"},{"openapi":"openapi_v2 post /v2/deposits/resend-callback/{depositId}","title":"Resend deposit callback","href":"/v2/api-reference/deposits/resend-deposit-callback"},{"title":"Deposit callback","icon":"webhook","href":"/v2/api-reference/deposits/deposit-callback"}]},{"group":"Payouts","pages":[{"openapi":"openapi_v2 post /v2/payouts","title":"Initiate payout","href":"/v2/api-reference/payouts/initiate-payout"},{"openapi":"openapi_v2 get /v2/payouts/{payoutId}","title":"Check payout status","href":"/v2/api-reference/payouts/check-payout-status"},{"openapi":"openapi_v2 post /v2/payouts/resend-callback/{payoutId}","title":"Resend payout callback","href":"/v2/api-reference/payouts/resend-payout-callback"},{"openapi":"openapi_v2 post /v2/payouts/fail-enqueued/{payoutId}","title":"Cancel enqueued payout","href":"/v2/api-reference/payouts/cancel-enqueued-payout"},{"openapi":"v2/api-reference/openapi_v2.yaml POST /v2/payouts/bulk","title":"Initiate bulk payouts","href":"/v2/api-reference/payouts/initiate-bulk-payout"},{"title":"Payout callback","icon":"webhook","href":"/v2/api-reference/payouts/payout-callback"}]},{"group":"Refunds","pages":[{"openapi":"openapi_v2 post /v2/refunds","title":"Initiate refund","href":"/v2/api-reference/refunds/initiate-refund"},{"openapi":"openapi_v2 get /v2/refunds/{refundId}","title":"Check refund status","href":"/v2/api-reference/refunds/check-refund-status"},{"openapi":"openapi_v2 post /v2/refunds/resend-callback/{refundId}","title":"Resend refund callback","href":"/v2/api-reference/refunds/resend-refund-callback"},{"openapi":"openapi_v2 post /v2/refunds/fail-enqueued/{refundId}","title":"Cancel enqueued refund","href":"/v2/api-reference/refunds/cancel-enqueued-refund"},{"title":"Refund callback","icon":"webhook","href":"/v2/api-reference/refunds/refund-callback"}]},{"group":"Remittances","pages":[{"openapi":"openapi_v2 post /v2/remittances","title":"Initiate remittance","href":"/v2/api-reference/remittances/initiate-remittance"},{"openapi":"openapi_v2 get /v2/remittances/{remittanceId}","title":"Check remittance status","href":"/v2/api-reference/remittances/check-remittance-status"},{"openapi":"openapi_v2 post /v2/remittances/resend-callback/{remittanceId}","title":"Resend remittance callback","href":"/v2/api-reference/remittances/resend-remittance-callback"},{"openapi":"openapi_v2 post /v2/remittances/fail-enqueued/{remittanceId}","title":"Cancel enqueued remittance","href":"/v2/api-reference/remittances/cancel-enqueued-remittance"},{"title":"Remittance callback","icon":"webhook","description":"API reference: the callback PawaPay sends to your callback URL when a remittance payout reaches a final status, with payload fields.","href":"/v2/api-reference/remittances/remittance-callback"}]},{"group":"Checkouts","pages":[{"openapi":"openapi_v2 post /v2/checkouts","title":"Initiate checkout","href":"/v2/api-reference/checkouts/initiate-checkout"},{"openapi":"openapi_v2 get /v2/checkouts/{checkoutId}","description":"API reference: get a PawaPay checkout's status by checkoutId, with the latest payment attempt and the full attempt history.","title":"Check checkout status","href":"/v2/api-reference/checkouts/check-checkout-status"},{"openapi":"openapi_v2 post /v2/checkouts/{checkoutId}/expire","title":"Expire checkout","href":"/v2/api-reference/checkouts/expire-checkout"},{"title":"Checkout callback","icon":"webhook","href":"/v2/api-reference/checkouts/checkout-callback"}]},{"group":"Payment page","pages":[{"openapi":"openapi_v2 post /v2/paymentpage","title":"Deposit via Payment Page","href":"/v2/api-reference/payment-page/deposit-via-payment-page"}]},{"group":"Finances","pages":[{"openapi":"openapi_v2 get /v2/wallet-balances","title":"Wallet balances","href":"/v2/api-reference/finances/wallet-balances"},{"openapi":"openapi_v2 get /v2/wallet-breakdowns","title":"Wallet breakdowns","href":"/v2/api-reference/finances/wallet-breakdowns"},{"openapi":"openapi_v2 post /v2/statements","title":"Statements","href":"/v2/api-reference/finances/initiate-statement"},{"openapi":"openapi_v2 get /v2/statements/{statementId}","title":"Check statement status","href":"/v2/api-reference/finances/check-statement-status"},{"title":"Statement callback","icon":"webhook","href":"/v2/api-reference/finances/statement-callback"},{"openapi":"openapi_v2 get /v2/settlements","title":"Settlements","href":"/v2/api-reference/finances/settlements"}]},{"group":"Toolkit","pages":[{"openapi":"openapi_v2 get /v2/active-conf","title":"Active Configuration","href":"/v2/api-reference/toolkit/active-configuration"},{"openapi":"openapi_v2 get /v2/availability","title":"Provider Availability","href":"/v2/api-reference/toolkit/availability"},{"openapi":"openapi_v2 post /v2/predict-provider","title":"Predict Provider","href":"/v2/api-reference/toolkit/predict-provider"},{"openapi":"openapi_v2 get /v2/public-key/http","title":"Public Keys","href":"/v2/api-reference/toolkit/public-keys"}]}]},{"tab":"Dashboard Docs","pages":[{"title":"Dashboard Docs","href":"/dashboard/introduction"}]}]},{"version":"v1","pages":[{"title":"v1","href":"/getting_started"}]}]},"basePath":"","title":"Initiate checkout - PawaPay Merchant API","deploymentId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","buildId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CrDfRf61.js","snippetPresets-Dv-cOUrx.js","utils-BUTreAgv.js","style-to-object-BY3JEAdk.js","utils-wsznt9RM.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-DEsMlaPy.js","conditional-requirements-CFM0id0Q.js","cloneDeep-DontW4xJ.js","_Uint8Array-pP7X6_RM.js","isObject-FP1Yky1u.js","ApiExamples-CU_aGGP0.js","usePlaygroundInputsStore-7dNmUIbS.js","shallow-fTtruD8x.js","isEqual-BRfNFpSD.js","CodeSnippets-52884wUJ.js","CodeSnippet-eoRjC4Le.js","getApiPlaygroundDisplay-CZyAPlR2.js","Page-Cr9IwkK7.js","DynamicMarkdown-NFqqduU7.js","SectionHeading-DQ-mJoAt.js","icon-DXTBUt6s.js","MethodPill-2v-b3js5.js","getPastedJson-v_8Y1_4v.js","DuplicateIcon-DXIkhZIo.js","createIcon-DRpYuPZs.js","axios-CsQoIw0U.js","Markdown-CwtoSfEf.js","AssistantPageLink-CTqa3eoi.js","dist-DIfYWxfm.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}