The Retrieve Checkout endpoint returns the complete session
record for a specific checkout, identified by its unique ID. The
response includes the checkout status, payable amount, currency,
associated payment link or subscription, and any transactions
linked to the session. This data is essential for verifying the
outcome of a payment flow and reconciling checkout activity
against business records.
Use the include query parameter to load additional related
data such as the associated payment link and transactions. This
endpoint is ideal for verifying checkout status during the
payment flow.
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission payment.checkouts.view
Request
Request body schema:
application/json
Path parameters:
checkout_id
required
checkout_id
required
Type: ulid
Length: 26
The unique ID assigned to each checkout which is generated
by our system using the ULID format. Each ID is
precisely 26 characters long, ensuring a unique and consistent
identifier for every checkout. This ULID is
automatically created by our system and is used to uniquely identify
and track each checkout in our database.
A list of additional checkout related objects to eager-load
and return with the response. Pass only the relations you need to
keep response payloads lean.
See Including Resources
for the full list of supported include values and usage details.
Response
200
Response schema:
application/json
Response body:
checkout
checkout
Type: object
The full checkout record, including billed amount,
currency, payment method, lifecycle status, and creation and expiration
timestamps.
id
id
Type: ulid
Length: 26
The unique ID assigned to each checkout which is generated
by our system using the ULID format. Each ID is
precisely 26 characters long, ensuring a unique and consistent
identifier for every checkout. This ULID is
automatically created by our system and is used to uniquely identify
and track each checkout in our database.
payable_id
payable_id
Type: ulid
The checkout payable model ID.
payable_type
payable_type
Type: enum
Possible values:
JSON
["payment.payment_link"]
The checkout payable model type.
currency_code
currency_code
Type: enum
Possible values:
JSON
["EGP"]
The three-character ISO-4217 Currency Code
that identifies the currency for the checkout. Your business should be eligible
to use the selected currency code.
paid_amount
paid_amount
Type: decimal
The checkout amount value that has already been paid. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
total_amount
total_amount
Type: decimal
The checkout total amount value that is due. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
remaining_amount
remaining_amount
Type: decimal
The checkout remaining amount to be paid. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
is_completed
is_completed
Type: boolean
This attribute indicates whether the checkout is completed or not.
is_coupon_allowed
is_coupon_allowed
Type: boolean
This attribute indicates if coupons are allowed for this checkout.
has_billing_address
has_billing_address
Type: boolean
This attribute indicates the customer needs to provide their billing address or not.
has_shipping_address
has_shipping_address
Type: boolean
This attribute indicates the customer needs to provide their shipping address or not.
This attribute tells that what stage the checkout is in.
error_redirect_url
error_redirect_url
Type: url|null
Max: 1000
This attribute specifies the URL to which a user is redirected to in case of a failure in the
checkout's process. It is used for error handling and user experience improvement, allowing users
to be informed and take appropriate actions in case of a process failure. The URL should be
carefully crafted to provide useful information or alternatives to the user following a
failure event.
success_redirect_url
success_redirect_url
Type: url|null
Max: 1000
Similar to error_redirect_url, this attribute defines the URL where users are redirected
after a successful operation or transaction within the checkout. It's a critical part of user
experience, ensuring users are guided to the correct next step or confirmation page after a
successful interaction.
pay_action
pay_action
Type: enum|null
Default: pay
Possible values:
JSON
["pay","book","rent","donate","subscribe"]
The checkout pay action.
fee_strategy
fee_strategy
Type: enum
Default: default
Possible values:
JSON
["payer","payee","default"]
The checkout applied transactions processing
Fees Strategy.
urls
urls
Type: object
A collection of URLs related to the checkout.
url
url
Type: url
This is the full URL to the checkout page. It's a direct link that takes
you to the specific page where the transaction or payment process happens.
This link is typically unique and you can use it to share the checkout
page with your customers.
qr_code_url
qr_code_url
Type: url
This is the unique QR code image URL for the checkout. When user scans
this QR they will be redirected to the correct checkout pay page to proceed
the payment.
paid_at
paid_at
Type: datetime|null
This attribute indicates when the checkout was paid.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format
specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
payer
payer
Type: object|null
The payer object containing the personal contact details and address
information of the customer who is submitting payment for this checkout.
name
name
Type: string
Min: 2
Max: 100
The payer's full legal or preferred name as it appears on billing
documents and payment receipts.
email
email
Type: string
Min: 5
Max: 255
The payer's email address used for transactional receipts, payment
confirmations, and support communications.
phone_number
phone_number
Type: string
The payer's mobile phone number used for SMS notifications, direct
contact, and two-factor verification.
shipping_address_as_billing_address
shipping_address_as_billing_address
Type: boolean
Indicates whether the payer's shipping address is identical to their
billing address, streamlining data entry when both match.
billing_address
billing_address
Type: object|null
The payer's billing address details. Required only when the checkout
is configured to collect a billing address.
country_code
country_code
Type: string
Specify the unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country where payer is located. This code is part of the standard
international country codes set by the ISO .
line_one
line_one
Type: string
Min: 2
Max: 255
The primary address line, typically containing the building or house number and
street name. This field is required and must precisely identify the street-level
location for deliveries, correspondence, and geographic lookups.
line_two
line_two
Type: string|null
Min: 2
Max: 255
An optional secondary address line used for additional information like apartment,
suite, or building numbers that help refine the location for delivery services.
city
city
Type: string
Min: 2
Max: 50
This attribute specifies the city in which the address is located. It's essential
for routing mail and deliveries within the correct geographical area.
state
state
Type: string|null
Min: 2
Max: 50
The state or region attribute further narrows down the location, especially in
countries with large geographical areas divided into states, provinces, or regions.
zip_code
zip_code
Type: string|null
Min: 2
Max: 30
Also known as postal code in some regions, this numeric or alphanumeric code is
critical for sorting mail and determining delivery routes with precision.
phone_number
phone_number
Type: string|null
Max: 30
A primary contact number that can be a mobile or cellular number, providing a
direct line to the individual or entity associated with the address.
landline_number
landline_number
Type: string|null
Max: 30
An alternative to the mobile number, this is a fixed-line telephone number
associated with the location, useful for contact purposes where mobile signals
may be unreliable.
fax_number
fax_number
Type: string|null
Max: 30
An optional fax number associated with the address. Used to receive documents
transmitted over telephone lines in business or institutional contexts where fax
communication is still supported.
note
note
Type: string|null
Min: 2
Max: 255
This free-text field allows for additional information or special instructions
related to the address or delivery preferences to be included.
first_name
first_name
Type: string|null
Min: 2
Max: 50
The given name of the individual associated with the address, important for
personalizing communication and ensuring the correct recipient for mail or
services.
last_name
last_name
Type: string|null
Min: 2
Max: 50
The family or surname of the individual, completing the personal identification
and used in conjunction with the first name for full clarity on the recipient's
identity.
location
location
Type: object|null
This attribute is used to offer a precise, geographical identification of a
place, which is crucial for various applications like mapping, navigation,
and location-based services.
lat
lat
Type: decimal
Min: -90
Max: 90
The geographic latitude of the address, expressed in decimal degrees. Valid
values range from -90 (south pole) to 90 (north pole). Used together with
longitude to pinpoint the exact location on a map or coordinate system.
lng
lng
Type: decimal
Min: -180
Max: 180
The geographic longitude of the address, expressed in decimal degrees. Valid
values range from -180 (west) to 180 (east). Combined with latitude, provides
the precise GPS coordinates required for mapping and location-based services.
country
country
Type: object
A country object containing the official name, two-letter
ISO code, flag emoji, primary language, international dialing
code, and ISO currency code.
name
name
Type: string
The official name of the country in English or In Arabic if the
Accepted-Language header is set to ar. This is the commonly
recognized name that would be used in international contexts and
is essential for any application that references countries by name.
flag
flag
Type: string
A Unicode representation of the country's flag. Unlike an image URL,
Unicode flags are character codes that render as the country's flag
emoji across compatible digital platforms. This allows for easy
integration of flags into text-based content and interfaces without
needing external images.
lang
lang
Type: string|null
This attribute represents the primary language spoken in the country.
It's typically expressed in ISO 639-1 format,
a two-letter code identifying the language, making it easier for applications
to adapt content or interfaces according to the user's region.
code
code
Type: string
The unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country. This code is part of the standard
international country codes set by the ISO .
dial_code
dial_code
Type: string
The international dialing code for the country, such as +1 for
the United States, +44 for the United Kingdom or +20 for
Egypt. This code is crucial for making international telephone calls
and can be used in applications that require user phone number verification.
currency_code
currency_code
Type: string
This attribute describes the official currency used in the country,
typically denoted by its ISO currency code,
such as USD for the United States Dollar, EUR for the Euro or EGP for
Egyptian Pound.
shipping_address
shipping_address
Type: object|null
The payer's shipping address details. Required only when the checkout
is configured to collect a shipping address.
country_code
country_code
Type: string
Specify the unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country where payer is located. This code is part of the standard
international country codes set by the ISO .
line_one
line_one
Type: string
Min: 2
Max: 255
The primary address line, typically containing the building or house number and
street name. This field is required and must precisely identify the street-level
location for deliveries, correspondence, and geographic lookups.
line_two
line_two
Type: string|null
Min: 2
Max: 255
An optional secondary address line used for additional information like apartment,
suite, or building numbers that help refine the location for delivery services.
city
city
Type: string
Min: 2
Max: 50
This attribute specifies the city in which the address is located. It's essential
for routing mail and deliveries within the correct geographical area.
state
state
Type: string|null
Min: 2
Max: 50
The state or region attribute further narrows down the location, especially in
countries with large geographical areas divided into states, provinces, or regions.
zip_code
zip_code
Type: string|null
Min: 2
Max: 30
Also known as postal code in some regions, this numeric or alphanumeric code is
critical for sorting mail and determining delivery routes with precision.
phone_number
phone_number
Type: string|null
Max: 30
A primary contact number that can be a mobile or cellular number, providing a
direct line to the individual or entity associated with the address.
landline_number
landline_number
Type: string|null
Max: 30
An alternative to the mobile number, this is a fixed-line telephone number
associated with the location, useful for contact purposes where mobile signals
may be unreliable.
fax_number
fax_number
Type: string|null
Max: 30
An optional fax number associated with the address. Used to receive documents
transmitted over telephone lines in business or institutional contexts where fax
communication is still supported.
note
note
Type: string|null
Min: 2
Max: 255
This free-text field allows for additional information or special instructions
related to the address or delivery preferences to be included.
first_name
first_name
Type: string|null
Min: 2
Max: 50
The given name of the individual associated with the address, important for
personalizing communication and ensuring the correct recipient for mail or
services.
last_name
last_name
Type: string|null
Min: 2
Max: 50
The family or surname of the individual, completing the personal identification
and used in conjunction with the first name for full clarity on the recipient's
identity.
location
location
Type: object|null
This attribute is used to offer a precise, geographical identification of a
place, which is crucial for various applications like mapping, navigation,
and location-based services.
lat
lat
Type: decimal
Min: -90
Max: 90
The geographic latitude of the address, expressed in decimal degrees. Valid
values range from -90 (south pole) to 90 (north pole). Used together with
longitude to pinpoint the exact location on a map or coordinate system.
lng
lng
Type: decimal
Min: -180
Max: 180
The geographic longitude of the address, expressed in decimal degrees. Valid
values range from -180 (west) to 180 (east). Combined with latitude, provides
the precise GPS coordinates required for mapping and location-based services.
country
country
Type: object
A country object containing the official name, two-letter
ISO code, flag emoji, primary language, international dialing
code, and ISO currency code.
name
name
Type: string
The official name of the country in English or In Arabic if the
Accepted-Language header is set to ar. This is the commonly
recognized name that would be used in international contexts and
is essential for any application that references countries by name.
flag
flag
Type: string
A Unicode representation of the country's flag. Unlike an image URL,
Unicode flags are character codes that render as the country's flag
emoji across compatible digital platforms. This allows for easy
integration of flags into text-based content and interfaces without
needing external images.
lang
lang
Type: string|null
This attribute represents the primary language spoken in the country.
It's typically expressed in ISO 639-1 format,
a two-letter code identifying the language, making it easier for applications
to adapt content or interfaces according to the user's region.
code
code
Type: string
The unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country. This code is part of the standard
international country codes set by the ISO .
dial_code
dial_code
Type: string
The international dialing code for the country, such as +1 for
the United States, +44 for the United Kingdom or +20 for
Egypt. This code is crucial for making international telephone calls
and can be used in applications that require user phone number verification.
currency_code
currency_code
Type: string
This attribute describes the official currency used in the country,
typically denoted by its ISO currency code,
such as USD for the United States Dollar, EUR for the Euro or EGP for
Egyptian Pound.
created_at
created_at
Type: datetime
The created datetime of the checkout.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format
specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
updated_at
updated_at
Type: datetime
The updated datetime of the checkout.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format
specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.