Transaction Updates
Details on the different ways to update transactions in Canopy, including performing immediate updates and scheduling updates for future times, as well as important considerations and related API references.
Introduction
More details about what a transaction is and what types of transactions are available can be found here.
Once created, some properties of a transaction can be updated. At the moment, only updating the status and the amount of a transaction is allowed. The list of statuses that a transaction can have, as well as a description of each status, can be found here.
How to update transactions
Canopy provides two ways to update transactions: one that allows the straight away update of the transaction and another that allows scheduling the update operation at a future time. Both functionalities can be accessed through the API using Postman.
Immediate transaction updates
The first way to update a transaction, taking effect immediately, can be performed by using the following endpoint:
PUT /accounts/{{account_id}}/line_items/{{transaction_id}}
This endpoint can be used to update a given transaction synchronously, at request time. In this case, the desired changes are applied to the transaction as soon as the request is fulfilled.
Request format
The payload of the request to synchronously update a transaction contains two attributes: the new status (line_item_status) and the new amount (original_amount_cents) of the transaction to be updated. Both attributes can be omitted. If the new status is missing, the line item status will be updated by default to VALID. If a new amount is not provided, the transaction amount won't change. A request payload example can be found below.
{
"line_item_status": "INVALID",
"original_amount_cents": 200
}
Response format
Regarding the response provided by the API, it contains comprehensive information about the updated transaction, reflecting the changes that have been applied.
Check the API Reference for additional details.
Schedule transaction updates
The second method to update a transaction involves scheduling the update operation at a later time and can be accessed by calling the following endpoint:
PUT /accounts/{account_id}/line_items/{transaction_id}/schedule
This endpoint provides the asynchronous version, allowing the user to choose when to perform the update.
Request format
The request payload closely mirrors that of the endpoint used to update transactions at request time but introduces an optional effective_at attribute. By means of this attribute, it is possible to specify the moment when the transaction should be updated. If it is not included in the payload, the operation will be scheduled at the time of the request and executed around one minute later. A sample request payload is provided below.
{
"line_item_status": "INVALID",
"original_amount_cents": 200,
"effective_at": "2020-07-20T09:11:28+00:00"
}
Response format
The response encompasses a message confirming that the update operation was scheduled at the time specified in the request. Also, the response includes a Location header that mentions a URL to query the status of the operation (i.e., an endpoint that can be used to retrieve the line item).
Check the API Reference for additional details.
Nice-to-knows
When you want to update a transaction, regardless of the selected method to perform this operation, you must take into account the fact that a transaction cannot be changed if the transaction is already in a final state.
For example, in the case of VALID payments, their status cannot be updated to PENDING.
Another aspect worth mentioning is the fact that if the status of a VALID payment needs to be updated to INVALID or DECLINED or VOID, the pattern to use is a payment reversal -- this ensures that immutability of a borrower's transaction history is not violated.
When scheduling a transaction update, the provided effective_at should be newer than the account certified time.
Related Articles
Updated 6 months ago