--- title: "Initiate checkout" method: POST path: "/v2/checkouts" tags: ["checkouts"] --- # Initiate checkout `POST /v2/checkouts` ## 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](https://datatracker.ietf.org/doc/rfc9421/). - `Signature-Input` string, string — Signature input according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). - `Accept-Signature` string, string — Expected signature algorithm of the response according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). - `Accept-Digest` string, string — Expected digest algorithm of the response according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). ## Request body - CheckoutInitiationRequest - `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. - `returnUrl` string, uri, required — The URL the customer should be redirected to after the payment is processed. - `returnMethod` 'INSTANT' | 'COUNTDOWN' | 'CUSTOMER_ACTION' — Controls how the customer is returned from the hosted payment page to the `returnUrl` once the payment is finished or cancelled. The customer is always returned eventually; this only affects the experience. * `INSTANT` - The customer is redirected back immediately, with no extra screen. * `COUNTDOWN` - A short countdown is shown, then the customer is redirected automatically. * `CUSTOMER_ACTION` - The checkout page waits until the customer presses "Return to merchant". - `defaultLanguage` 'en' | 'fr' — The default language of the checkout page. Supported languages are `en` and `fr`. - `countries` CheckoutCountry[] — Restricts the checkout to the specified countries when provided. - `expiresAfter` integer — Number of minutes after creation when the checkout should expire. Must be between 3 and 60. Defaults to 15 if not provided. - `amounts` CheckoutAmount[] — 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. - `country` string, required — 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). - `currency` string, required — 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. - `amount` string, required — 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. - `payer` CheckoutPayer — Details of the payer that should be pre-filled for the hosted payment page, if specified. - `type` 'MMO', required — The type of account involved in the transaction. At the moment, only **MMO** is supported. - `accountDetails` CheckoutAccountDetails, required - `phoneNumber` string — 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. - `provider` string — 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). - `allowCustomerToOverride` boolean, required — Indicates whether the customer may change the pre-filled payer details in the hosted payment page. - `clientReferenceId` string — A reference to an entity in your system that this payment relates to. For example, an invoice ID, customer ID etc. - `reason` CheckoutReason — Localized reason values shown to the customer inside the hosted payment page. - `metadata` TransactionMetadataRequestItem[] — 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. - `additionalProperties` string — The metadata that you are attaching to the payment. For example `"orderId":"ORD-123456789"`. - `isPII` boolean — Indicates whether the field contains personally identifiable information. Used for compliance with GDPR or other relevant data privacy laws. ## Response `200` Request has valid payload. See `status` to confirm if the checkout was accepted for processing. - CheckoutCreationResponse - `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. - `status` 'ACCEPTED' | 'REJECTED' | 'DUPLICATE_IGNORED', required — The initiation status of the checkout: * `ACCEPTED` - The checkout has been **accepted** and the hosted payment page has been created. * `REJECTED` - The checkout has been **rejected**. See `failureReason` for details. * `DUPLICATE_IGNORED` - The checkout has been ignored as a duplicate of an already accepted checkout. Deduplication is based on `checkoutId`. - `redirectUrl` string, uri — The URL to which the customer must be redirected to open and complete the hosted payment page. - `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](https://tools.ietf.org/html/rfc3339#section-5.6) - `expiresAt` string, date-time — The timestamp when the checkout and its hosted payment page are scheduled to expire. - `checkoutCode` string — A unique identifier that forms part of the checkout's redirect URL. - `failureReason` CheckoutCreationFailureReason - `failureCode` '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', required — 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. - `failureMessage` string — Description of the reason for this failure. ## Other responses - `400` — Request was rejected due to incompatibility with PawaPay API specification. - `401` — Authentication failed. Make sure you have added the API token into the header. If using signatures, make sure they are valid. - `403` — Authorization failure. Please check your authentication token. - `500` — An unknown failure has occured. --- [API](https://skmtc.net/pawapay/apis/pawapay-merchant-api-v2.md) · [All operations](https://skmtc.net/pawapay/apis/pawapay-merchant-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pawapay/pawapay-merchant-api-v2/versions/ce13c31e9746/schema)