Retrieve Payment Link Checkout

In Payiano Retrieve Checkout feature bridges the gap between creating a Payment Link and the final Checkout process, offering a seamless and integrated experience for customers. This feature allows businesses to retrieve the associated Checkout information tied to each Payment Link. This Checkout information is crucial as it encompasses the customer's journey from clicking the Payment Link to selecting their preferred payment method, be it via credit card, bank transfer, or other means, on a secure payment platform.

This dual functionality is particularly beneficial for a wide range of users – from online retailers and freelancers invoicing clients, to charities collecting donations – as it simplifies the online payment process, ensuring a smooth and secure transaction. By integrating the retrieval of both Payment Link and Checkout details, Payiano enhances the efficiency of financial transactions. It allows businesses to monitor and manage payments effectively, ensuring a streamlined payment process that reduces manual errors, increases operational efficiency, and ultimately leads to greater customer satisfaction.

This integration is a testament to Payiano's commitment to providing comprehensive, user-friendly solutions that cater to the dynamic needs of modern businesses, making it an invaluable tool for anyone looking to optimize their online payment systems.

GET/payment_links/{id}/checkout
Sandbox: https://api.payiano.dev/v1/payment_links/{id}/checkout
Live: https://api.payiano.com/v1/payment_links/{id}/checkout
Security
  • Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
  • Your access token should be associated to one of these permissions payment_links_view or checkouts_view
Request
Request body schema:
application/json
Path parameters:
id
required
Type: ulid
Length: 26

The unique ID assigned to each payment link 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 payment link. This ULID is automatically created by our system and is used to uniquely identify and track each payment link in our database.

Query parameters:
identify_by
Type: enum|null
Possible values:
[
"id", "reference_id" ]

This attribute specifies which identifier is being used to interact with a resource in the Payiano API. It helps the system understand how to identify resource when processing API requests. By default, the identify_by attribute is set to id, so you only need to specify it if you're using a different identifier.

includes
Type: array_of_enums|null
Possible values:
[
"checkout.payer", "checkout.payer.billing_address", "checkout.payer.billing_address.country", "checkout.payer.shipping_address", "checkout.payer.shipping_address.country" ]

A list of additional checkout relations to return, if available. Feel free to send the relations you would like to return with every item. See Including Resources to better understand how this is working.

Response
200
Response schema:
application/json
Response body:
checkout
Type: object

The payment link checkout model details.

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
Type: ulid

The checkout payable model ID.

payable_type
Type: enum
Possible values:
[
"PAYMENT_LINK" ]

The checkout payable model type.

currency_code
Type: enum
Possible values:
[
"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
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
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
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
Type: boolean

This attribute indicates whether the checkout is completed or not.

is_coupon_allowed
Type: boolean

This attribute indicates if coupons are allowed for this checkout.

has_billing_address
Type: boolean

This attribute indicates the customer needs to provide their billing address or not.

has_shipping_address
Type: boolean

This attribute indicates the customer needs to provide their shipping address or not.

status
Type: enum
Possible values:
[
"UNPAID", "PENDING", "CANCELLED", "PAID", "OVER_PAID", "FULLY_REFUNDED", "PARTIALLY_REFUNDED", "INITIATED", "PARTIALLY_PAID" ]

This attribute tells that what stage the checkout is in.

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
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
Type: enum|null
Default: PAY
Possible values:
[
"PAY", "BOOK", "RENT", "DONATE", "SUBSCRIBE" ]

The checkout pay action.

fee_strategy
Type: enum
Default: DEFAULT
Possible values:
[
"PAYEE", "PAYER", "DEFAULT" ]

The checkout applied transactions processing Fees Strategy.

urls
Type: object

A collection of URLs related to the checkout.

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
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
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
Type: object|null

The checkout payer model details.

name
Type: string
Min: 2
Max: 100

This is the fundamental attribute representing the payer's full legal or preferred name. It's used in all forms of communication and identification. It's crucial for personalization and ensures that all correspondences and documents are correctly addressed.

email
Type: string
Min: 5
Max: 255

The email address is a key point of contact for digital communication. It's used for sending transactional emails, marketing material, and support communications.

phone_number
Type: string

This attribute stores the payer's mobile number. It's essential for direct contact, SMS notifications, and can also be used in cases where email communication is insufficient or inappropriate.

shipping_address_as_billing_address
Type: boolean

This attribute indicating whether the payer's shipping address is identical to their billing address. This simplifies the process for payers who use the same address for both purposes and streamlines data entry and management.

billing_address
Type: object|null

The checkout payer billing address details. This attribute is only required if checkout has billing address.

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
Type: string
Min: 2
Max: 255

This attribute is the primary address line. This is where the first part of the address is written, usually the house number and street name. It's where the mail starts to find where you live or work.

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
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
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
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
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
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
Type: string|null
Max: 30

Not used as much these days, but it's a number where you can receive documents sent over a telephone line.

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
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
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
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
Type: decimal
Min: -90
Max: 90

This stands for latitude. It's a way to tell exactly where the address is on the Earth using GPS. It tells you how far north or south the place is.

lng
Type: decimal
Min: -180
Max: 180

This is the longitude. Like latitude, but it tells you how far east or west the place is. Together with latitude, it can pinpoint any location on the globe.

country
Type: object

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.

code
Type: string

It implies 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
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
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.

name
Type: string

The official name of the country in English. This is the commonly recognized name that would be used in international contexts and is essential for any application that references countries by name.

name_ar
Type: string|null

The name of the country in Arabic. This attribute is particularly useful for applications serving Arabic-speaking users, allowing for a localized experience by presenting country names in the native script.

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.

flag
Type: string|null

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.

shipping_address
Type: object|null

The checkout payer shipping address details. This attribute is only required if checkout has shipping address.

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
Type: string
Min: 2
Max: 255

This attribute is the primary address line. This is where the first part of the address is written, usually the house number and street name. It's where the mail starts to find where you live or work.

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
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
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
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
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
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
Type: string|null
Max: 30

Not used as much these days, but it's a number where you can receive documents sent over a telephone line.

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
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
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
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
Type: decimal
Min: -90
Max: 90

This stands for latitude. It's a way to tell exactly where the address is on the Earth using GPS. It tells you how far north or south the place is.

lng
Type: decimal
Min: -180
Max: 180

This is the longitude. Like latitude, but it tells you how far east or west the place is. Together with latitude, it can pinpoint any location on the globe.

country
Type: object

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.

code
Type: string

It implies 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
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
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.

name
Type: string

The official name of the country in English. This is the commonly recognized name that would be used in international contexts and is essential for any application that references countries by name.

name_ar
Type: string|null

The name of the country in Arabic. This attribute is particularly useful for applications serving Arabic-speaking users, allowing for a localized experience by presenting country names in the native script.

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.

flag
Type: string|null

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.

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
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.

Response sample:
1
{
2
"checkout": {
3 "id": "01hqh45s7826hfwdze8dp1z21f", 4 "payable_id": "01hqh45s7826hfwdze8dp1z21f", 5 "payable_type": "PAYMENT_LINK", 6 "currency_code": "EGP", 7 "paid_amount": 0, 8 "total_amount": 1140, 9 "remaining_amount": 1140, 10 "is_completed": false, 11 "is_coupon_allowed": true, 12 "has_billing_address": true, 13 "has_shipping_address": false, 14 "status": "UNPAID", 15 "error_redirect_url": "https://pyngy.com/payments/error", 16 "success_redirect_url": "https://pyngy.com/payments/success", 17 "pay_action": "PAY", 18 "fee_strategy": "DEFAULT", 19
"urls": {
20 "url": "https://pay.payiano.com/checkouts/01hqh45s7826hfwdze8dp1z21f", 21 "qr_code_url": "https://api-pay.payiano.com/v1/checkouts/01hqh45s7826hfwdze8dp1z21f/qrcode" 22 }, 23 "paid_at": null, 24
"payer": {
25 "name": "Mohsen Ali", 26 "email": "mohsen@gawaab.com", 27 "phone_number": "+201000333000", 28 "shipping_address_as_billing_address": true, 29
"billing_address": {
30 "country_code": "EG", 31 "line_one": "7th Makram Ebid, Nasr City", 32 "line_two": "Building 174, apartment 12", 33 "city": "Cairo", 34 "state": "Nasr City", 35 "zip_code": "11321", 36 "phone_number": "+201000333000", 37 "landline_number": "6546543213216", 38 "fax_number": "5456464646", 39 "note": null, 40 "first_name": "Mohsen", 41 "last_name": "Osama", 42
"location": {
43 "lat": 21.32, 44 "lng": 12.63 45 }, 46
"country": {
47 "code": "EG", 48 "dial_code": "+20", 49 "currency_code": "EGP", 50 "name": "Egypt", 51 "name_ar": "مصر", 52 "lang": "AR", 53 "flag": "🇪🇬" 54 } 55 }, 56
"shipping_address": {
57 "country_code": "EG", 58 "line_one": "7th Makram Ebid, Nasr City", 59 "line_two": "Building 174, apartment 12", 60 "city": "Cairo", 61 "state": "Nasr City", 62 "zip_code": "11321", 63 "phone_number": "+201000333000", 64 "landline_number": "6546543213216", 65 "fax_number": "5456464646", 66 "note": null, 67 "first_name": "Mohsen", 68 "last_name": "Osama", 69
"location": {
70 "lat": 21.32, 71 "lng": 12.63 72 }, 73
"country": {
74 "code": "EG", 75 "dial_code": "+20", 76 "currency_code": "EGP", 77 "name": "Egypt", 78 "name_ar": "مصر", 79 "lang": "AR", 80 "flag": "🇪🇬" 81 } 82 } 83 }, 84 "created_at": "1722572118554", 85 "updated_at": "1722572118554" 86 } 87}