> ## 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. # Check checkout status Get the current status of a checkout based on its `checkoutId`. The response returns the overall checkout state together with the latest payment attempt, when available, and the full history of attempts within that checkout. ## OpenAPI ````yaml openapi_v2 get /v2/checkouts/{checkoutId} 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/{checkoutId}: get: tags: - checkouts summary: Check checkout status operationId: getCheckout parameters: - $ref: '#/components/parameters/CheckoutId' responses: '200': description: Request has been processed by PawaPay. content: application/json: schema: $ref: '#/components/schemas/CheckoutSearchResult' examples: WAITING_PAYMENT: value: status: FOUND data: checkoutId: afb57b93-7849-49aa-babb-4c3ccbfe3d79 status: WAITING_PAYMENT redirectUrl: >- https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79 created: '2026-03-27T10:30:00Z' countries: [] amounts: [] depositsHistory: [] metadata: {} reason: {} checkoutCode: PPGAFB57B93 COMPLETED: value: status: FOUND data: checkoutId: afb57b93-7849-49aa-babb-4c3ccbfe3d79 status: COMPLETED redirectUrl: >- https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79 returnUrl: https://merchant.example.com/checkout-result returnMethod: INSTANT defaultLanguage: en countries: - ZMB expiresAfter: 60 amounts: - country: ZMB currency: ZMW amount: '100' payer: type: MMO accountDetails: phoneNumber: '260973024434' provider: MTN_MOMO_ZMB allowCustomerToOverride: true clientReferenceId: ORDER-123 created: '2026-03-27T10:30:00Z' providerTransactionId: PROVIDER-TXN-123 depositStatus: COMPLETED deposit: depositId: eac4d2f3-cf36-4a24-a9eb-7014c630f8f0 status: COMPLETED created: '2026-03-27T10:35:00Z' providerTransactionId: PROVIDER-TXN-123 amount: '100' currency: ZMW country: ZMB payer: type: MMO accountDetails: phoneNumber: '260973024434' provider: MTN_MOMO_ZMB customerMessage: To ACME company depositsHistory: - depositId: eac4d2f3-cf36-4a24-a9eb-7014c630f8f0 status: COMPLETED created: '2026-03-27T10:35:00Z' providerTransactionId: PROVIDER-TXN-123 amount: '100' currency: ZMW country: ZMB payer: type: MMO accountDetails: phoneNumber: '260973024434' provider: MTN_MOMO_ZMB customerMessage: To ACME company metadata: orderId: ORDER-123 customerId: CUST-456 reason: en: GOODS PURCHASE checkoutCode: PPGAFB57B93 FAILED: value: status: FOUND data: checkoutId: afb57b93-7849-49aa-babb-4c3ccbfe3d79 status: FAILED redirectUrl: >- https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79 created: '2026-03-27T10:30:00Z' countries: [] amounts: [] providerTransactionId: PROVIDER-TXN-123 depositStatus: FAILED deposit: depositId: eac4d2f3-cf36-4a24-a9eb-7014c630f8f0 status: FAILED created: '2026-03-27T10:35:00Z' providerTransactionId: PROVIDER-TXN-123 failureReason: failureCode: PAYMENT_NOT_APPROVED failureMessage: The payer did not approve the payment. depositsHistory: - depositId: eac4d2f3-cf36-4a24-a9eb-7014c630f8f0 status: FAILED created: '2026-03-27T10:35:00Z' providerTransactionId: PROVIDER-TXN-123 failureReason: failureCode: PAYMENT_NOT_APPROVED failureMessage: The payer did not approve the payment. metadata: {} reason: {} checkoutCode: PPGAFB57B93 EXPIRED: value: status: FOUND data: checkoutId: afb57b93-7849-49aa-babb-4c3ccbfe3d79 status: EXPIRED redirectUrl: >- https://payment.example.com/checkout/afb57b93-7849-49aa-babb-4c3ccbfe3d79 created: '2026-03-27T10:30:00Z' countries: [] amounts: [] depositsHistory: [] metadata: {} reason: {} checkoutCode: PPGAFB57B93 NOT_FOUND: value: status: NOT_FOUND '401': description: >- Authentication failed. Make sure you have added the API token into the header. 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: CheckoutId: in: path name: checkoutId required: true description: The id of the checkout that you are performing this operation on. schema: minLength: 36 maxLength: 36 type: string format: uuid example: f4401bd2-1568-4140-bf2d-eb77d2b2b639 schemas: CheckoutSearchResult: required: - status type: object properties: status: $ref: '#/components/schemas/SearchResultStatus' data: $ref: '#/components/schemas/Checkout' 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. SearchResultStatus: type: string description: | The result of this operation. - `FOUND` - The payment was found in PawaPay. - `NOT_FOUND` - The payment was not found in PawaPay. enum: - FOUND - NOT_FOUND Checkout: required: - checkoutId - status - redirectUrl - countries - amounts - depositsHistory - metadata - reason - checkoutCode type: object properties: checkoutId: $ref: '#/components/schemas/ResponsePaymentId' status: $ref: '#/components/schemas/CheckoutStatus' redirectUrl: $ref: '#/components/schemas/CheckoutRedirectUrl' returnUrl: $ref: '#/components/schemas/ReturnUrl' returnMethod: $ref: '#/components/schemas/CheckoutReturnMethod' defaultLanguage: type: string description: >- The default language of the checkout when one was specified during creation. example: en countries: type: array description: >- The list of countries that the hosted payment page should allow for this checkout. items: $ref: '#/components/schemas/CheckoutCountry' example: - ZMB - CIV expiresAfter: type: integer format: int32 description: >- Number of minutes after creation when this checkout is configured to expire. Between 3 and 60; defaults to 15. example: 60 amounts: type: array description: > The fixed amount the customer is asked to pay, specified per country and currency, as configured for this checkout. When set, it contains an entry for each country in the `countries` array, defining the amount the customer pays for the country and currency they select on the hosted payment page. If not set, 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' created: $ref: '#/components/schemas/CreatedTimestamp' providerTransactionId: $ref: '#/components/schemas/ProviderTransactionId' depositStatus: $ref: '#/components/schemas/CheckoutCurrentDepositStatus' deposit: $ref: '#/components/schemas/CheckoutDeposit' depositsHistory: type: array description: >- History of payment attempts within this checkout. A single checkout can contain multiple attempts, but at most one can complete successfully. items: $ref: '#/components/schemas/CheckoutDeposit' metadata: $ref: '#/components/schemas/TransactionMetadataResponse' reason: $ref: '#/components/schemas/CheckoutReason' checkoutCode: $ref: '#/components/schemas/CheckoutCode' 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 ResponsePaymentId: minLength: 36 maxLength: 36 type: string format: uuid description: >- The unique ID for this payment in PawaPay as specified by you during initiation. example: f4401bd2-1568-4140-bf2d-eb77d2b2b639 CheckoutStatus: type: string description: > Possible checkout lifecycle statuses. This is distinct from the initiation status (`CheckoutCreationStatus`) returned when the checkout is created. * `WAITING_PAYMENT` - The checkout and its hosted payment page have been created and are waiting for the customer to pay. * `PROCESSING` - A payment attempt is in progress and the checkout is still being processed. * `COMPLETED` - The checkout has completed successfully. This is a **final status.** * `FAILED` - The checkout has failed. Inspect `deposit` or `depositsHistory` for the latest attempt result when available. This is a **final status.** * `EXPIRED` - The checkout has expired and can no longer be used. This is a **final status.** * `CANCELLED` - The customer cancelled the payment on the hosted payment page. This is a **final status.** enum: - WAITING_PAYMENT - PROCESSING - COMPLETED - FAILED - EXPIRED - CANCELLED 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 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 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' ProviderTransactionId: type: string description: >- The unique ID for this payment assigned by the provider. The customer would see this ID on their SMS receipt and transaction history. example: ABC123 CheckoutCurrentDepositStatus: type: string description: > Current aggregate status for the checkout, representing the latest payment attempt: * `PROCESSING` - The latest payment attempt is still being processed. Attempts undergoing reconciliation also remain `PROCESSING` until a final status is determined. * `COMPLETED` - The latest payment attempt completed successfully. * `FAILED` - The latest payment attempt failed. enum: - PROCESSING - COMPLETED - FAILED CheckoutDeposit: required: - depositId - status - created type: object properties: depositId: $ref: '#/components/schemas/ResponsePaymentId' status: $ref: '#/components/schemas/CheckoutDepositStatus' created: $ref: '#/components/schemas/CreatedTimestamp' providerTransactionId: $ref: '#/components/schemas/ProviderTransactionId' failureReason: $ref: '#/components/schemas/CheckoutDepositFailureReason' amount: $ref: '#/components/schemas/Amount' currency: $ref: '#/components/schemas/Currency' country: $ref: '#/components/schemas/Country' payer: $ref: '#/components/schemas/PayerOrRecipient' customerMessage: $ref: '#/components/schemas/CustomerMessage' metadata: $ref: '#/components/schemas/TransactionMetadataResponse' TransactionMetadataResponse: description: > The metadata that was provided in the original initation request in a JSON object format. type: object properties: additionalProperties: type: string description: >- Each passed in metadata field will be a property of the metadata JSON object. example: orderId: ORD-123456789 customerId: customer@email.com 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 CheckoutCode: type: string description: A unique identifier that forms part of the checkout's redirect URL. example: PPGAFB57B93 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 CheckoutDepositStatus: type: string description: > Possible statuses for a payment attempt inside the checkout: * `ACCEPTED` - The payment attempt has been accepted by PawaPay for processing. * `PROCESSING` - The payment attempt is being processed. Attempts undergoing reconciliation also remain `PROCESSING` until a final status is determined. * `COMPLETED` - The payment attempt completed successfully. * `FAILED` - The payment attempt failed. enum: - ACCEPTED - PROCESSING - COMPLETED - FAILED CheckoutDepositFailureReason: description: The failure reason of the payment attempt when its status is `FAILED`. required: - failureCode type: object properties: failureCode: type: string description: | Failure code of the payment attempt. Checkout payments use the same failure codes as standard deposits. example: PAYMENT_NOT_APPROVED failureMessage: type: string description: Human readable description of the payment attempt failure. example: The payer did not approve the payment. Country: type: string minLength: 3 maxLength: 3 description: > The country in which the payment was initiated. 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 PayerOrRecipient: description: Details about the customer who is paying or receiving the payment. required: - type - accountDetails type: object properties: type: $ref: '#/components/schemas/AccountDetailsType' accountDetails: $ref: '#/components/schemas/AccountDetails' 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 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 AccountDetails: required: - provider - phoneNumber type: object properties: phoneNumber: $ref: '#/components/schemas/PhoneNumber' provider: $ref: '#/components/schemas/Provider' securitySchemes: bearerAuth: type: http description: >- See [Authentication](/v2/docs/how_to_start#how-to-authenticate-calls-to-the-merchant-api). scheme: bearer bearerFormat: JWT ````