The Retrieve Payout Transaction endpoint on
Payiano returns complete details for a
specific payout transaction identified by its unique ID. The
response includes transaction metadata, payout amount, recipient
information, payout method (e.g., bank transfer,
e-wallet, or InstaPay), current
status, and any related identifiers or configuration.
This endpoint is ideal for verifying transaction status, reviewing
payout details, or conducting reconciliation and compliance checks.
It provides finance and operations teams with secure, real-time
access to transaction-level data for improved accuracy and transparency.
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission payout.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 payout 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 payout transaction. This ULID is
automatically created by our system and is used to uniquely identify
and track each payout transaction in our database.
Query parameters:
identify_by
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.
Response
200
Response schema:
application/json
Response body:
transaction
transaction
Type: object
The payout transaction model details.
id
id
Type: ulid
Length: 26
The unique ID assigned to each payout 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 payout transaction. This ULID is
automatically created by our system and is used to uniquely identify
and track each payout transaction in our database.
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each payout transaction. It's
primary role is to distinguish one payout transaction from another, ensuring
that each payout transaction can be individually tracked and managed without
any confusion.
Please note that duplicate values are not allowed. Only alpha-numeric
characters, dashes, and underscores are allowed: [A-Za-z0-9-_].
The reference_id
value is used to Identify Resource when you consume any payout transaction endpoint with sending identify_by
query parameter with value reference_id.
Including it in every payout request helps ensure idempotency and prevents accidental duplicate processing. It’s highly recommended to always include this parameter when initiating a payout.
status
status
Type: enum
Possible values:
["pending","failed","success"]
This attribute indicates the current status of the payout transaction.
receiver_amount
receiver_amount
Type: object
Contains detailed information about the amount received by the payout
beneficiary. Similar to sender_amount, it breaks down the base amount,
any fees, total amount, and currency code.
base_amount
base_amount
Type: decimal
The payout amount before any receiving-side fees or deductions.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
fee_amount
fee_amount
Type: decimal
The fee amount charged on the receiving end, if applicable.
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 final amount credited to the receiver after all deductions.
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:
["EGP"]
The three-character ISO-4217 Currency Code that identifies the currency for the payout transaction receiver amount. Your business
should be eligible to use the selected currency code.
sender_amount
sender_amount
Type: object
Contains detailed information about the amount sent by the company
during payout. It includes the base transaction amount, applicable
fees, total amount, and the currency code.
base_amount
base_amount
Type: decimal
The base payout amount before any fees are applied.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
fee_amount
fee_amount
Type: decimal
The total fee applied to the transaction, if any.
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 total amount after fees, representing the actual payout deducted
from the sender’s balance. 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:
["EGP"]
The three-character ISO-4217 Currency Code that identifies the currency for the payout transaction sender amount. Your business
should be eligible to use the selected currency code.
source_type
source_type
Type: enum
Possible values:
["balance"]
This attribute indicates the source type of the payout transaction.
source_details
source_details
Type: object
Provides information about the source of funds for the payout transaction,
including details of the originating balance or account.
balance
balance
Type: object
The payment balance used as the source of funds for this payout transaction.
It identifies which company balance or wallet the payout was debited from.
id
id
Type: ulid
Length: 26
The unique ID assigned to each balance 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 balance. This ULID is
automatically created by our system and is used to uniquely identify
and track each balance 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 balance. Your business
should be eligible to use the selected currency code.
receiver_type
receiver_type
Type: enum
Possible values:
["recipient"]
This attribute indicates the receiver type of the payout transaction.
receiver_details
receiver_details
Type: object
Contains information about the payout recipient, including the destination
account and related configuration details used to process the transaction.
recipient
recipient
Type: object
Describes the recipient details associated with an existing payout
transaction, including the configured payment method and destination
information.
type
type
Type: enum
Possible values:
["ach","ewallet","instapay"]
Specifies the payout recipient type. This determines how the destination is
configured (e.g., ACH, e-wallet, or InstaPay).
details
details
Type: object
Describes the recipient details associated with an existing payout
transaction, including the configured payment method and destination
information.
ach
ach
Type: object
This attribute defines the recipient's ACH (Automated Clearing House)
bank account information used for local transfers. It is required when
the payout method type is set to ach. The structure is country
specific and must match the banking format of the recipient's
country.
country_code
country_code
Type: string
Specify the unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country where the payout recipient bank is located. This code is part of the standard
international country codes set by the ISO .
bank_code
bank_code
Type: string
A short code identifying the recipient's bank. This value must correspond
to one of the supported bank codescodes for the selected country_code. For example, MISR for Banque Misr
in Egypt or NBE for National Bank of Egypt. Bank codes are typically
returned in uppercase and should be submitted as-is.
holder_name
holder_name
Type: string
Min: 2
Max: 70
The full legal name of the bank account holder, exactly as registered with
the bank. This name will be used for validation by banking partners and
should match the account record.
number_type
number_type
Type: enum
Possible values:
["iban","account_number"]
Indicates the format of the bank account number — iban for international
accounts ( e.g. Egypt, EU, KSA ) or account_number for local accounts
in non-IBAN countries ( e.g. US, India ). This determines which field is
required in number_details.
number_details
number_details
Type: object
Contains the bank account number details. The structure of this object changes
dynamically based on the selected number_type. Only one key should exist,
matching the number_type value, and each key contains the fields required
for that specific account format.
iban
iban
Type: object
Used when number_type is iban. Contains the IBAN
number, a globally recognized format that includes the country code, bank
identifier, and account number.
number
number
Type: string
Max: 34
The full IBAN number. Example: EG380019000500000000263180002
account_number
account_number
Type: object
Used when number_type is account_number. Contains the recipient's
local bank account number. Common in countries where IBAN is not applicable
or used as an alternative, such as Egypt, the United States, or India.
number
number
Type: string
Min: 4
Max: 30
The local bank account number. Example: 263180002
ewallet
ewallet
Type: object
This attribute defines payout configuration for recipients using Meeza
compatible e-wallets such as Vodafone Cash, Etisalat Cash, and Orange
Money. Required when the payout method is set to e-wallet.
phone_number
phone_number
Type: string
The phone number registered to the recipient’s e-wallet account.
It must follow international format (e.g., +201000320310) and belong
to a supported provider like Vodafone, Etisalat, or Orange.
holder_name
holder_name
Type: string
Min: 2
Max: 70
The full name of the e-wallet account holder as registered with the
e-wallet provider. This name is used to verify the recipient's identity
and ensure accurate delivery of funds.
instapay
instapay
Type: object
Defines recipient details for payouts via InstaPay, using a registered mobile
number or InstaPay Payment Number (IPN) linked to a bank account in Egypt.
ipn
ipn
Type: string
The InstaPay Payment Number (IPN) of the recipient. This is typically a
registered mobile number or a virtual payment identifier used to receive
funds through the InstaPay network in Egypt.
completed_at
completed_at
Type: datetime|null
Indicates the timestamp when the payout transaction was successfully completed
and finalized. This field is null until the transaction reaches a terminal
state such as failed or success.
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.
created_at
created_at
Type: datetime
The created datetime of the payout 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 payout 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.