The Update Payout Account endpoint in Payiano allows your company
to modify existing payout accounts used for disbursing funds to vendors, employees,
or partners. You can update payout details such as the account name, beneficiary information,
payout method (e.g. bank transfer, mobile e-wallet, InstaPay), or any associated metadata
to reflect the most accurate and up-to-date payout configurations.
Keeping payout accounts updated ensures accurate fund routing, compliance with financial policies,
and a smoother experience for all recipients.
In the Payiano system, it's important to note a key operational rule
regarding record updates. If a payout account record has been soft deleted, without being
permanently removed from the database, any updates to this record are forbidden.
This restriction ensures data integrity and consistency, as modifying a soft-deleted
record could lead to confusion or inaccuracies in the system management.
To update a soft-deleted payout account, the record must first be
restored. Restoration reverts the record's deleted status,
making it once again eligible for updates and modifications. This policy is crucial for
maintaining a clear and accurate representation of the payout account record, while still
retaining the flexibility to recover and revise previously soft-deleted payout account as
needed. By enforcing this rule, the Payiano system ensures a streamlined
and coherent management process, balancing flexibility with control.
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.update
Request
Request body schema:
application/json
Path parameters:
account_id
required
account_id
required
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.
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.
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
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.
Response
200
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_id
recipient_id
Type: ulid
The unique identifier of the payout recipient. This value links the
payout account to the correct recipient, ensuring funds are routed
to the intended destination.
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 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.
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_id": "01jzpk5q40pwfjx56mskdecs70",9"recipient": {10"id": "01jzpk5q40pwfjx56mskdecs70",11"type": "ach",12"details": {13"ach": {14"country_code": "EG",15"bank_code": "MISR",16"holder_name": "Tarek Gamal",17"number_type": "iban",18"number_details": {19"iban": {20"number": "EG380019000500000000263180002"21}22}23}24},25"created_at": "1752031747985",26"updated_at": "1752031747985"27},28"is_deleted": false,29"created_at": "1751922385803",30"updated_at": "1751922385803",31"deleted_at": null32}33}