The Create Payout Transaction endpoint on
Payiano enables companies to initiate
and manage secure outbound payments to vendors, partners,
service providers, or employees. It supports multiple payout
methods, including local bank transfers, mobile wallets, and
real-time payment channels such as InstaPay.
This endpoint streamlines financial operations by automating
disbursements like settlements, commissions, and withdrawals,
while ensuring transparency, traceability, and compliance with
company payment policies. Each transaction is securely processed
and can be monitored via the Payiano dashboard or API webhooks.
Use this API to build reliable payout workflows that reduce manual
effort and eliminate processing errors, empowering your business to
scale seamless, real-time financial transfers.
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.create
Webhook Events
These webhook events will be fired when this endpoint is called, the system will automatically send a notification to the designated webhook URLs.
payout.transaction.created
Request
Request body schema:
application/json
Query parameters:
Request body:
amount
required
amount
required
Type: object
This attribute describes the required amount to be withdrawn.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
value
required
value
required
Type: decimal
Min: 1
Max: 9999999
This attribute describes the required amount to be withdrawn.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
currency_code
required
currency_code
required
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.
source
required
source
required
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
required
id
required
Type: ulid
Length: 26
The unique ID assigned to each payment 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 payment balance. This ULID is
automatically created by our system and is used to uniquely identify
and track each payment balance in our database.
receiver
required
receiver
required
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
This attribute is used to define the recipient’s payout destination based on
the selected payment method. Only one method (e.g., ACH, e-wallet, or
InstaPay) is allowed per request. This ensures accurate routing of the payout
to the intended destination.
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
required
country_code
required
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
required
bank_code
required
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
required
holder_name
required
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_details
required
number_details
required
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
required
number
required
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
required
number
required
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
required
phone_number
required
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
required
holder_name
required
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
required
ipn
required
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.
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.
Response
201
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.