The Create Payout Account endpoint on Payiano allows your company to register
secure payout destinations for transferring funds to vendors, partners, service providers, or employees.
These accounts support various payout methods including local bank transfers, mobile wallets,
and real-time payment solutions like InstaPay.
By setting up payout accounts, your business can automate outbound payments—such as commissions,
withdrawals, or settlements—while maintaining clear control, traceability, and full compliance
with your financial operations.
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission payout.accounts.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.account.created
Request
Request body schema:
application/json
Query parameters:
includes
includes
Type: array_of_enums|null
Possible values:
["account.recipient"]
A list of additional payout account 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.
Request body:
name
required
name
required
Type: string
Min: 1
Max: 100
A unique and descriptive name for the payout account. This name helps identify the account in your
system, especially when managing multiple payout recipients such as vendors, employees, or partners.
For example, you might use 'Vendor Main Bank Account' or 'Employee Payroll Wallet'.
Please note that duplicate values are not allowed. Only alpha-numeric
characters, dashes, underscores, and spaces are allowed: [A-Za-z0-9-_ ].
recipient
required
recipient
required
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 contains ACH (Automated Clearing House) configuration used to
define the recipient's local bank transfer details. This object is required
when the payout method is ACH.
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 is located. This code is part of the standard
international country codes set by the ISO .
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.
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.
is_active
is_active
Type: boolean
Default: true
This value indicates whether the payout account is active or not. This flag can be used
to control the payout account's availability in runtime environments or listings without
deleting or removing the payout account from records. A true value means the payout account
is active and functioning, while a false value implies that the payout account is
deactivated or not in use.
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each payout account. It's
primary role is to distinguish one payout account from another, ensuring
that each payout account 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 account endpoint with sending identify_by
query parameter with value reference_id.
description
description
Type: string|null
Max: 1000
Optional text to describe the payout account in more detail. You can include information about
the account’s intended usage, payment method, or recipient. For example: “Used for monthly
vendor settlements via InstaPay” or “Payroll account for contract employees.”
This field helps teams understand the context or restrictions associated with the account.
Response
201
Response schema:
application/json
Response body:
account
account
Type: object
The payout account model details.
id
id
Type: ulid
Length: 26
The unique ID assigned to each payout account 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 account. This ULID is
automatically created by our system and is used to uniquely identify
and track each payout account in our database.
name
name
Type: string
Min: 1
Max: 100
A unique and descriptive name for the payout account. This name helps identify the account in your
system, especially when managing multiple payout recipients such as vendors, employees, or partners.
For example, you might use 'Vendor Main Bank Account' or 'Employee Payroll Wallet'.
Please note that duplicate values are not allowed. Only alpha-numeric
characters, dashes, underscores, and spaces are allowed: [A-Za-z0-9-_ ].
is_active
is_active
Type: boolean
Default: true
This value indicates whether the payout account is active or not. This flag can be used
to control the payout account's availability in runtime environments or listings without
deleting or removing the payout account from records. A true value means the payout account
is active and functioning, while a false value implies that the payout account is
deactivated or not in use.
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each payout account. It's
primary role is to distinguish one payout account from another, ensuring
that each payout account 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 account endpoint with sending identify_by
query parameter with value reference_id.
description
description
Type: string|null
Max: 1000
Optional text to describe the payout account in more detail. You can include information about
the account’s intended usage, payment method, or recipient. For example: “Used for monthly
vendor settlements via InstaPay” or “Payroll account for contract employees.”
This field helps teams understand the context or restrictions associated with the account.
recipient
recipient
Type: object
The payout recipient model details.
id
id
Type: ulid
Length: 26
The unique ID assigned to each payout recipient 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 recipient. This ULID is
automatically created by our system and is used to uniquely identify
and track each payout recipient in our database.
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
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 contains ACH (Automated Clearing House) configuration used to
define the recipient's local bank transfer details. This object is required
when the payout method is ACH.
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 is located. This code is part of the standard
international country codes set by the ISO .
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.
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.
created_at
created_at
Type: datetime
The created datetime of the payout recipient.
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 recipient.
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.
is_deleted
is_deleted
Type: boolean
Default: false
This value indicates whether the payout account is deleted or not. This flag can be used to
control the payout account's availability in runtime without actual deleting or removing the
payout account from records. A true value means the payout account is deleted, while a false
value implies that the payout account is not deleted and functioning.
created_at
created_at
Type: datetime
The created datetime of the payout account.
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 account.
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.
deleted_at
deleted_at
Type: datetime|null
The deleted datetime of the payout account.
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"account": {3"id": "01jzkbcqdk1pasnm9hxmwf4wjh",4"name": "Vendor Main Bank Account",5"is_active": true,6"reference_id": "7c0e6b41-00db-374e-9d0f-541109ea5d45",7"description": "Primary bank account for weekly vendor payments via ACH.",8"recipient": {9"id": "01jzpk5q40pwfjx56mskdecs70",10"type": "ach",11"details": {12"ach": {13"country_code": "EG"14},15"ewallet": {16"phone_number": null17},18"instapay": {19"ipn": null20}21},22"created_at": "1752031747985",23"updated_at": "1752031747985"24},25"is_deleted": false,26"created_at": "1751922385803",27"updated_at": "1751922385803",28"deleted_at": null29}30}