Vendor bank account

Registers, lists and updates the accounts that receive the payments of the vendor's expenses. A vendor can have several accounts, but always exactly one main account (main_account: true). The first account registered is the main one; to change the main account, promote another account.

Accounts are not subject to the analysis lock: they can be registered and updated with the vendor in any status and are not required to submit the analysis.

Register a bank account

Available on

Profile	Host	Required permission
Manager	manager-api	Write
Consultant	consultant-api	Active integration

Base URL for each host: Environments (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/bank_account

METHOD

POST

Path parameters

Parameter	Type	Description
vendor_key	string	Vendor key (UUID).

Request body — Pix by key

{
    "transfer_type": "pix",
    "pix_key": "44555666000181",
    "main_account": true
}

Request body — TED

{
    "transfer_type": "ted",
    "financial_institution_code": "341",
    "account_branch": "0001",
    "account_number": "123456",
    "account_digit": "7"
}

Body attributes

Field	Type	Required	Description
transfer_type	string	Yes	pix or ted.
pix_key	string	Conditional	Pix key, from 1 to 77 characters. Only with transfer_type = pix, and without the account details.
financial_institution_code	string	Conditional	Bank COMPE code, exactly 3 digits (341), not all zeros.
account_branch	string	Conditional	Branch, exactly 4 digits, not all zeros.
account_number	string	Conditional	Account number, from 1 to 20 digits, not all zeros.
account_digit	string	Conditional	Account check digit, exactly 1 digit.
main_account	boolean	No	Makes this the main account, demoting the previous one. Default: false. The vendor's first account is always the main account.

Valid combinations:

• pix with pix_key and no account details.
• pix with the four account details and no pix_key (Pix to the account).
• ted with the four account details.

With account details, the API identifies the bank by financial_institution_code and returns the ISPB in the response.

Response

STATUS

201

Response body

{
    "bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c",
    "transfer_type": "ted",
    "main_account": false,
    "status": "active",
    "financial_institution_code": "341",
    "financial_institution_ispb": "60701190",
    "account_branch": "0001",
    "account_number": "123456",
    "account_digit": "7"
}

Response attributes

Field	Type	Description
bank_account_key	string	Account key (UUID).
transfer_type	string	pix or ted.
main_account	boolean	Main account.
status	string	active or inactive.
pix_key	string	Pix key. Present only when provided.
financial_institution_code	string	Bank COMPE code. Present only with account details.
financial_institution_ispb	string	Bank ISPB, 8 digits. Present only with account details.
account_branch	string	Branch. Present only with account details.
account_number	string	Account number. Present only with account details.
account_digit	string	Account check digit. Present only with account details.

Fields without a value do not come as null: they are omitted from the response.

Update a bank account

Promotes an account to main account or changes its status. At least one of the two fields is required.

Available on

Profile	Host	Required permission
Manager	manager-api	Write
Consultant	consultant-api	Active integration

Base URL for each host: Environments (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/bank_account/{bank_account_key}

METHOD

PUT

Request body

{
    "main_account": true
}

Field	Type	Required	Description
main_account	boolean	No	Only true is accepted: promotes this account and demotes the current main account. false returns 400 (VRG000074).
status	string	No	inactive deactivates the account; active reactivates it.

Response

STATUS

200

The updated account, with the same structure as on registration.

List bank accounts

Available on

Profile	Host	Required permission
Manager	manager-api	Read
Consultant	consultant-api	Active integration

Base URL for each host: Environments (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/bank_account

METHOD

GET

Query parameters

Parameter	Type	Required	Description
limit	integer	No	Items per page, from 0 to 1000. Default: 10.
page	integer	No	Page, starting at 0. Default: 0.

Returns all accounts, active and inactive, from newest to oldest.

Response

STATUS

200

Response body

{
    "data": [
        {
            "bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c",
            "transfer_type": "pix",
            "main_account": true,
            "status": "active",
            "pix_key": "44555666000181"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

Errors

STATUS

400

code	When it happens
VRG000059	pix_key sent with transfer_type = ted.
VRG000028	pix_key sent together with account details.
VRG000048	transfer_type = pix without pix_key and without the four account details.
VRG000019	transfer_type = ted without the four account details.
VRG000021	financial_institution_code does not match any bank.
VRG000074	main_account: false sent on update.
VRG000078	You tried to promote to main an account that is inactive, or one being deactivated in the same call.
VRG000075	You tried to deactivate the main account while there is another active account. Promote another account first.

Example

{
  "title": "Pix Key Or Account Data Required",
  "description": "For a pix transfer, either pix_key or the full account data (financial_institution_code, account_branch, account_number, account_digit) must be provided.",
  "translation": "Para uma transferencia pix, e necessario informar a pix_key ou os dados completos da conta (financial_institution_code, account_branch, account_number, account_digit).",
  "code": "VRG000048"
}

STATUS

404

code	When it happens
VRG000014	The vendor_key does not exist or the vendor is not visible to you.
VRG000073	The bank_account_key does not belong to this vendor.

Authentication, permission and host errors: see API Errors.

Next step

Signer group, or go to the analysis submission.