The Payiano retrieve transaction endpoint offers a
detailed look into individual transactions processed through
Payiano. This feature is crucial for businesses that
need to drill down into the specifics of each payment or refund. With this
endpoint, you can:
Access Detailed Information:
Get comprehensive details about a specific transaction, including the
payer's information, payment method, date, amount, and any associated
fees or refunds.
Verify Payment Status:
Quickly confirm the status of a transaction, such as completed, pending,
or failed, which is essential for managing customer inquiries and ensuring
accurate record-keeping.
Understand Transaction Context:
Gain insights into the context of each transaction, such as the related
payment link, any messages or notes attached to the payment, and the
transaction's impact on your balance.
This detailed view not only helps in addressing specific queries but also
plays a critical role in financial auditing, customer service, and managing
refunds or disputes. The retrieve transaction endpoint is a key tool for
maintaining transparency and trust in financial dealings, ensuring every
transaction can be reviewed and understood in full detail.
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission transactions_view
Request
Request body schema:
application/json
Path parameters:
id
required
id
required
Type: ulid
Length: 26
The unique ID assigned to each transaction 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 transaction. This ULID is
automatically created by our system and is used to uniquely identify
and track each transaction in our database.
A list of additional transaction 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:
transaction
transaction
Type: object
The transaction model details.
id
id
Type: ulid
Length: 26
The unique ID assigned to each transaction 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 transaction. This ULID is
automatically created by our system and is used to uniquely identify
and track each transaction in our database.
currency_code
currency_code
Type: enum
Possible values:
["EGP"]
The three-character ISO-4217 Currency Code that identifies the currency for the transaction. Your business
should be eligible to use the selected currency code.
amount
amount
Type: decimal
The amount value that needs to be collected for the transaction. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
status
status
Type: enum
Possible values:
["UNPAID","PENDING","CANCELLED","EXPIRED","PAID"]
This attribute tells that what stage the transaction is in.
payment_source
payment_source
Type: object
This attribute is designed to accommodate different payment methods,
uniquely identifying the method used to complete a payment. Please
note that only one payment source is permitted per request.
basata
basata
Type: object
Basata is a payment option ideal for people who like or need to pay
with cash at actual stores instead of online.
inquiry_code
inquiry_code
Type: integer
This code can be used at any Basata partner location, including
convenience stores, banks, or ATMs that support Basata services
to complete a payment. You can simulate a complete transaction payment through our Pay Order POS terminal flow to test this service effectively. This allows for a hands-on experience to ensure that the payment process is efficient and user-friendly at actual retail locations.
card
card
Type: object
The card payment method allows customers to complete transactions
using their credit or debit cards.
number
number
Type: string
The card number represents the primary account number (PAN) of
the card used for the transaction. For security purposes, the number
is partially masked, displaying only the last four digits and
the card type.
expiry_month
expiry_month
Type: string
This field indicates the month when the card expires, represented as
a numeric value ( e.g '1' for January ).
expiry_year
expiry_year
Type: string
This field indicates the year when the card expires, represented as a
numeric value ( e.g '39' for 2039 ).
is_stored
is_stored
Type: boolean
This boolean field specifies whether the card information is stored
for future transactions. A value of true indicates the card details
are saved, while false indicates they are not.
brand
brand
Type: string
The brand field identifies the card brand ( e.g Visa,
Mastercard ). This helps in categorizing the card type
and processing the transaction accordingly.
scheme
scheme
Type: string
This field denotes the card scheme, which usually matches the brand ( e.g
Visa, Mastercard ). This helps
in categorizing the card type and processing the transaction accordingly.
funding_method
funding_method
Type: string
The funding method specifies whether the card is a credit, debit,
or prepaid card.
damen
damen
Type: object
Damen is a payment method that utilizes offline reference numbers
to process transactions, providing a simple solution to complete purchases.
reference_number
reference_number
Type: string
This reference number can be utilized at a variety of designated offline
payment points, such as convenience stores, kiosks, or bank branches that
are integrated with the Damen network. You can simulate a complete transaction payment through our Pay Order POS terminal flow to test this service effectively. This allows for a hands-on experience to ensure that the payment process is efficient and user-friendly at actual retail locations.
ewallet
ewallet
Type: object
Ewallet is a digital wallet payment method that allows customers
to make transactions using their mobile devices. This method provides a
convenient and secure way for users to pay for goods and services without
the need for physical cards or cash.
urls
urls
Type: object
This attribute contains URLs related to the ewallet transaction,
providing links necessary for completing the payment process.
qr_code_url
qr_code_url
Type: url
This attribute contains the URL for the QR code associated with
the ewallet transaction. The QR code can be scanned with your
ewallet application to facilitate quick and secure payments.
It can be scanned with any Voddafone Cash, Etisalat Cash or any
other Egyption Meeza Ewallet application.
payer
payer
Type: object
This attribute contains details about the individual making the payment.
This ensures that the payment can be correctly attributed and processed.
phone_number
phone_number
Type: string
This attribute represents the mobile number of the payer. This number
is used to identify the ewallet account from which the payment will be
made.
fawry
fawry
Type: object
Fawry is a payment method that utilizes offline reference
numbers to facilitate transactions.
reference_number
reference_number
Type: string
This reference number can then be used to complete the payment at various
offline locations, such as convenience stores, post offices, or ATMs that
support Fawry services. You can simulate a complete transaction payment through our Pay Order POS terminal flow to test this service effectively. This allows for a hands-on experience to ensure that the payment process is efficient and user-friendly at actual retail locations.
maxab
maxab
Type: object
Maxab is a payment option ideal for people who like or need to pay
with cash at actual stores instead of online.
inquiry_code
inquiry_code
Type: integer
This code can be used at any Maxab partner location, including
convenience stores, banks, or ATMs that support Maxab services
to complete a payment. You can simulate a complete transaction payment through our Pay Order POS terminal flow to test this service effectively. This allows for a hands-on experience to ensure that the payment process is efficient and user-friendly at actual retail locations.
opay
opay
Type: object
OPay is a payment method that utilizes offline reference numbers
to process transactions, providing a simple solution to complete purchases.
reference_number
reference_number
Type: string
This reference number can be utilized at a variety of designated offline
payment points, such as convenience stores, kiosks, or bank branches that
are integrated with the OPay network. You can simulate a complete transaction payment through our Pay Order POS terminal flow to test this service effectively. This allows for a hands-on experience to ensure that the payment process is efficient and user-friendly at actual retail locations.
sadad
sadad
Type: object
Sadad is a payment option ideal for people who like or need to pay
with cash at actual stores instead of online.
inquiry_code
inquiry_code
Type: integer
This code can be used at any Sadad partner location, including
convenience stores, banks, or ATMs that support Sadad services
to complete a payment. You can simulate a complete transaction payment through our Pay Order POS terminal flow to test this service effectively. This allows for a hands-on experience to ensure that the payment process is efficient and user-friendly at actual retail locations.
This attribute is the identifier for the Payment Method. Each name is unique
ensuring there's no confusion between different Payment Methods.
is_active
is_active
Type: boolean
Default: true
This value indicates whether the payment method is active or not. This flag can be used
to control the payment method's availability in runtime environments or listings without
deleting or removing the payment method from records. A true value means the payment method
is active and functioning, while a false value implies that the payment method is
deactivated or not in use.
provider
provider
Type: object
The provider is the entity or service that facilitates or processes payments.
This could be a bank, a digital wallet service, a credit card company, or any
other financial service that enables transactions. Providers are integral to the
functioning of payment systems as they are responsible for the actual processing
of transactions. They ensure that payments are securely and efficiently processed,
from the point of sale to the final settlement. In Payiano's
system, each Payment Method is associated with a provider to clarify which service
is handling the transactions for that specific method.
The attribute is a unique identifier or label that clearly specifies
which payment processing service is associated with a particular Payment Method.
This could be names like paypal or fawry. It's essential for
distinguishing between different providers, especially when offering multiple
payment options to customers. The name helps in identifying the provider quickly
and accurately, both for internal reference and for informing customers about the
available Payment Methods. This clarity is crucial for efficient payment management
and for maintaining transparency with customers about who is handling their transactions.
expires_at
expires_at
Type: datetime|null
It indicates when the transaction becomes invalid. It ensures
payments are made within a specified timeframe, useful for
time-sensitive offers. It informs both the payer and the recipient
about the exact deadline until which the payment can be processed.
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.
paid_at
paid_at
Type: datetime|null
This attribute indicates when the transaction 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.
marked_as_paid_at
marked_as_paid_at
Type: datetime|null
This attribute records the time a transaction was marked as paid. It is
intended for marking transactions as paid strictly for testing purposes
and is used in all environments except for production. Using
this attribute in a production environment is strictly prohibited as it
can disrupt the payment system. Employing it in production might lead to
charges for which payments have not actually been received. Please note
that this attribute is retrievable in all environments except production
.
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
The checkout payer model details.
name
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
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
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
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
billing_address
Type: object|null
The checkout payer billing address details. This attribute is only
required if checkout has 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
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
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
Not used as much these days, but it's a number where you can receive documents
sent over a telephone line.
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
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
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
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
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
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.
name
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
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
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
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
shipping_address
Type: object|null
The checkout payer shipping address details. This attribute is only
required if checkout has 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
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
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
Not used as much these days, but it's a number where you can receive documents
sent over a telephone line.
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
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
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
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
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
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.
name
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
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
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
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
created_at
Type: datetime
The created datetime of the transaction.
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 transaction.
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.