A bank payroll represents a payroll on your bank account, which is in itself a list of bank transactions that, unlike a wire transaction, does not require the transaction's recipient to be previously authorized. Instead, you may assign transactions to a bank payroll with recipients that have not yet been authorized, and authorize all of them at once when the payroll is enrolled on the bank.
The flow of a bank payroll is the following:
- Create a bank payroll by calling the 'Create one' endpoint.
- Passing the created bank payroll's id to the request body of the endpoint for the creation of a bank transaction, which will then make said transaction associated to the payroll, instead of enqueuing it on the bank.
- Repeat 2. for each transaction that you wish to be associated with said payroll.
- Once you have the payroll associated with all the transactions wanted, you may call the 'Enroll one' endpoint, which will then enroll said payroll on the bank.
- If there are transactions that have recipients that have not yet been authorized, the bank payroll will move on to have status:
pending_validation, so you must call the 'Authorize all payroll recipients' endpoint for authorizing all of the payroll's recipients. To do this, you must pass, on the request's body, the token and the verification code that should have been sent to your bank account's registered email.
- If there are errors with the transactions provided, the payroll will move on to have status:
enroll_failed. If the payroll is with this status, you may remove it and thereafter try to enroll it again with the correct data.
- Once all recipients are authorized, the payroll will move on to have status:
enrolled. While the payroll is with this status, you may do one of two actions:
- Remove the payroll.
- Authorize the payroll.
- If you choose to remove the payroll by calling the 'Remove one' endpoint, it will then be removed from the bank and return to status:
draft, so you may modify it by associating new transactions.
- If you choose to authorize the payroll by calling the 'Authorize one' endpoint with your token on the request's body, the payroll will then be authorized on the bank, and move on to have status:
You may also enroll several payrolls, and then call the bank account's 'Authorize all enrolled payrolls' endpoint, which will authorize all currently enrolled payrolls on your bank account.
Note: In order to not immediately enroll a bank recipient on the bank, and merely create it as draft so it can be used on a payroll and then be authorized later along with all of the other draft recipients, you must pass the parameter
transition: null on the request's body when creating a recipient.
A bank payroll may have the following status:
- draft: The default status of a bank payroll when created. While in this status, you may modify the payroll as you wish.
- pending_validation: The payroll has recipients that must be authorized for the payroll to be fully enrolled on the bank.
- enroll_failed: The payroll has transactions that contained errors, and so it can't be authorized.
- enrolled: The payroll has been successfully enrolled on your bank.
- authorized: The payroll was successfully authorized and completed by your bank.
- declined: The payroll was declined by your bank.
A bank payroll may also have the following transitions, which indicate whether the payroll is currently moving between status:
- ➡️ enroll: The payroll is currently being enrolled on your bank.
- ⬅️ delete: The payroll is currently being removed from your bank.
- 💹 authorize: The payroll is currently being authorized on your bank.
- ⭕ null: The payroll is not currently moving between status.