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 payment.transactions.view
Request
Request body schema:
application/json
Path parameters:
transaction_id
required
transaction_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 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:
transaction
transaction
Type: object
The full transaction record including amount, status,
payment method, and timestamps.
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.
payee_amount
payee_amount
Type: object
This attributes describes the financial details for the payee, the recipient of
the transaction.
base_amount
base_amount
Type: decimal
The original transaction amount before any fees are applied. This is
the gross amount intended 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.
currency_code
currency_code
Type: enum
Possible values:
JSON
["EGP"]
This attribute specifies the currency in which the transaction was created
and the payee will receive funds. This currency may differ from the
payer_amount.currency_code in cases involving currency conversion.
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.
fee_amount
fee_amount
Type: decimal
The total fee amount deducted from the payer.base_amount as part of the
transaction processing. This may include platform fees, payment provider charges,
or other service fees. In some cases, such as when the fees are applied to the
payer, a promotion or campaign offers free processing fees, this value may be
zero. 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
This attribute specifies the net amount that the payee will receive after any
applicable fees have been deducted from the payer.base_amount. This value
reflects the actual amount transferred to the payee, taking into account any fees
or adjustments. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
payer_amount
payer_amount
Type: object
This attribute describes the financial details for the payer, the entity making
the payment for the transaction.
base_amount
base_amount
Type: decimal
The original transaction amount before any fees are applied. This is
the gross amount intended to be collected by the payer for the transaction.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
currency_code
currency_code
Type: enum
Possible values:
JSON
["EGP"]
This attribute specifies the actual currency that the transaction will
be processed with. It may differ from the payee_amount.currency_code
if the payer chooses a payment provider that processes the payment in a
different currency than the one required by the payee. For instance, if
the transaction is originally listed in EGP but the payer opts to use
a payment provider that charges in USD like PayPal,
this attribute will reflect the USD currency code.
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.
fee_amount
fee_amount
Type: decimal
The total fee amount added to the payee_amount.base_amount as part of
the transaction processing. This may include platform fees, payment provider
charges, or other service fees. In some cases, such as when the fees are
applied to the payee, or a promotion offers free processing fees, this
value may be zero. 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
This attribute specifies the net amount that the payer will pay, which may
differ from the payer_amount.base_amount due to fees or currency conversion.
It represents the actual amount charged to the payer for the transaction.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
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_cash
basata_cash
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.
masked_number
masked_number
Type: string|null
The field 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.
holder_name
holder_name
Type: string|null
Min: 2
Max: 26
The field represents the name of the cardholder as it appears on the card.
This is used to identify the owner of the payment method in a transaction.
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|null
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|null
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|null
The funding method specifies whether the card is a credit, debit,
or prepaid card.
damen_cash
damen_cash
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_cash
fawry_cash
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.
opay_cash
opay_cash
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.
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
Indicates whether the payment method is currently active. Set to
true to enable the payment method and make it available in
listings and operations; set to false to deactivate it
without removing it from the system.
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.
collected_at
collected_at
Type: datetime|null
This attribute indicates when the transaction was collected.
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.
fees
fees
Type: array_of_objects
This attribute specifies the fees associated with the transaction.
id
id
Type: ulid
Length: 26
The unique ID assigned to each transaction fee 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 fee. This ULID is
automatically created by our system and is used to uniquely identify
and track each transaction fee in our database.
type
type
Type: enum
Possible values:
JSON
["processing_fee"]
This attribute specifies the type of fee associated with transaction.
fee_strategy
fee_strategy
Type: enum
Possible values:
JSON
["payee","payer","payiano"]
The transaction fee strategy defines how the fee is calculated and
applied to the transaction.
payee_amount
payee_amount
Type: object
This attributes describes the financial details for the payee, the recipient of
the transaction.
base_amount
base_amount
Type: decimal
The original transaction amount before any fees are applied. This is
the gross amount intended 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.
currency_code
currency_code
Type: enum
Possible values:
JSON
["EGP"]
This attribute specifies the currency in which the transaction was created
and the payee will receive funds. This currency may differ from the
payer_amount.currency_code in cases involving currency conversion.
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.
fee_amount
fee_amount
Type: decimal
The total fee amount deducted from the payer.base_amount as part of the
transaction processing. This may include platform fees, payment provider charges,
or other service fees. In some cases, such as when the fees are applied to the
payer, a promotion or campaign offers free processing fees, this value may be
zero. 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
This attribute specifies the net amount that the payee will receive after any
applicable fees have been deducted from the payer.base_amount. This value
reflects the actual amount transferred to the payee, taking into account any fees
or adjustments. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
payer_amount
payer_amount
Type: object
This attribute describes the financial details for the payer, the entity making
the payment for the transaction.
base_amount
base_amount
Type: decimal
The original transaction amount before any fees are applied. This is
the gross amount intended to be collected by the payer for the transaction.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
currency_code
currency_code
Type: enum
Possible values:
JSON
["EGP"]
This attribute specifies the actual currency that the transaction will
be processed with. It may differ from the payee_amount.currency_code
if the payer chooses a payment provider that processes the payment in a
different currency than the one required by the payee. For instance, if
the transaction is originally listed in EGP but the payer opts to use
a payment provider that charges in USD like PayPal,
this attribute will reflect the USD currency code.
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.
fee_amount
fee_amount
Type: decimal
The total fee amount added to the payee_amount.base_amount as part of
the transaction processing. This may include platform fees, payment provider
charges, or other service fees. In some cases, such as when the fees are
applied to the payee, or a promotion offers free processing fees, this
value may be zero. 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
This attribute specifies the net amount that the payer will pay, which may
differ from the payer_amount.base_amount due to fees or currency conversion.
It represents the actual amount charged to the payer for the transaction.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
payer
payer
Type: object
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 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.