Amend
Introduction
The Amend API module enables the application to retrieve and amend transaction information. The ability to amend a transaction is needed for two reasons: 1) If the receiver's name needs to be amended to match the name on the receiver's identification for the payout of the transaction; and 2) if further data is needed to release a HOLD, after funds have been transferred. It is important for the customer to keep the information on the transaction record updated for compliance and validation reasons, otherwise the transaction may not be able to be picked up by the receiver or deposited to an account.
API sequence
The 'Amend API' module comprises of four synchronous endpoints. There are two use cases for Amending funds and the API sequence is as follows:
'Amend Receiver Name' allows the application to modify the reciever's name, after the funds have been transferred. This is important if the customer has made a mistake when entering the values at time of transferring funds and later needs to modify the receiver name on the transactionId resource. The Amend Reciever Name comprises of a two API call sequence: 'Retrieve a Transaciton' and 'Modify Reicever Name'. In this model, the application will typically retrieve the transacitonId resource and surface the transaction information in the UI. The application can then modify the resource with the new receiver name.
- Retrieve a transaction by transactionId |
GET /amend/v1/transactions/{transactionId}
GET /amend/v1/transactions/{transactionId}The application can use transactionId as a path parameter to retrieve the transaction for amend. The endpoint responds with a transaction summary and current status.
OR
- Retrieve a transaction by reference number |
GET /amend/v1/transactions/?referenceNumber={referenceNumber}
The application can use a reference number as a query parameter to retrieve the transaction for amend. The endpoint responds with a transaction summary and current status.
- Modify Receiver's Name |
PATCH /amend/v1/transactions/{transactionId}/receiver/name
PATCH /amend/v1/transactions/{transactionId}/receiver/name
The application must pass the corrected values in the receive name fields.
The
endpoint will respond with a success and modify the transactionId resource with the new receiver name.
Typically the application will develop an "Amend" feature within a wider transaction history UI experience. Once the transaction is retrieved, we recommend a transaction summary to be displayed back in the UI of the application. This helps the customer to validate the transaction details to be amended, before executing the amend.
API Sequence Diagram
'Amend Receiver Additional Data' allows the application to amend the `transactionId` resource with additional information about the receiver. This is important if the transction is on HOLD and further data on the reiceve customer is needed to clear the HOLD and release the transaciton. The Amend Reciever Additional data comprises of a two API call sequence: 'Retrieve a Transaciton' and 'Modfy Receiver Additional Data'. In this model, the application will typically retrieve the transacitonId resource and surface the transaction information in the UI. The application can then modify the recorce with the new reicever additional data.
- Retrieve a transaction by transactionId |
GET /amend/v1/transactions/{transactionId}
GET /amend/v1/transactions/{transactionId}The application can use transactionId as a path parameter to retrieve the transaction for amend. The endpoint responds with a transaction summary and current status.
OR
- Retrieve a transaction by reference number |
GET /amend/v1/transactions/?referenceNumber={referenceNumber}
The application can use a reference number as a query parameter to retrieve the transaction for amend. The endpoint responds with a transaction summary and current status.
- Modify Receiver's Additional Data |
PATCH /amend/transactions/{transactionId}/receiver/additional-data
PATCH /amend/transactions/{transactionId}/receiver/additional-data
The application must pass the new values in the receive perosonal detials fields.
The
endpoint will respond with a success and modify the transactionId resource with additional information about the receiver.
Typically the application will develop an "Amend" feature within a wider transaction history UI experience. Once the transaction is retrieved, we recommend a transaction summary to be displayed back in the UI of the application. This helps the customer to validate the transaction details to be amended, before executing the amend.
API Sequence Diagram
Endpoints
| Name | METHOD | URL | Description |
|---|---|---|---|
| Retrieve a Transaction | GET | /amend/v1//transaction/{transactionId} | Look up a transaction for amend using transactionId as a path parameter |
| Retrieve a Transaction | GET | /amend/v1/transactions/?referenceNumber={referenceNumber} | Look up a transaction for amend using referenceNumber as a query parameter |
| Amend Receiver's Name | PATCH | /amend/v1//transactions/{transactionId}/receiver/name | The application can call the 'Modify Receiver Name' endpoint to modify the transactionId resource with new Receiver name details |
| Amend Receiver's Additional Data | PATCH | /amend/v1/transactions/{transactionId}/receIver/additional-data | The application can call the 'Modify Receive Additional Information' endpoint to modify the transactionId resource with additional information about the receiver |
Example user journey
1 - Retreive a transaction
Look up and retrieve the transaction to be amended by reference number or transaction ID.
2 - Transaction summary
3 - Amend the receivers name
4 - Amend confirmation
Updated about 1 month ago
