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
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}