File status change event
Trigger: A file transitions from one processing status to another.
Tip: Webhooks may be updated from time to time and it is important to consider the Versioning and Backward Compatibility guidelines when developing your solution. We recommend that your handler ignores new fields it is not expecting; any new fields that may be added will provide new information, which may be safely ignored.
Webhook Message Details
This Webhook notifies you of any file status changes.
The following event type is possible:
| Webhook Event Type | Description |
| FileStatusUpdated | A file is initially QUEUED (awaiting processing) and may transition from intermediary statuses to a final status. You may configure Webhook notifications as required, to be notified when files transition to specific statuses. |
File statuses
Tip: Files are referred to as
Import when they are initially passed to Nuapay and validations are carried out. Successfully processed Import files (COMPLETE or COMPLETE WITH ERROR) are then mapped to an Export file. This is the file that is passed to Clearing for processing, where the actual settlement of funds occurs. Export files may transition to ACCEPTED or PARTIALLY_ACCEPTED.It is possible to receive a Webhook notification for files that transition to any of the following statuses:
| Status | Description |
|---|---|
| PENDING | The collection date is in the future and the file has not yet been selected for processing. |
| PENDING SETTLEMENT | The export file has been passed to Clearing but an acknowledgement has not yet been received. |
| ACCEPTED | An export file has been passed to Clearing and an Acknowledgement (ACK) has been received. |
| PARTIALLY_ACCEPTED | An export file has been passed to Clearing and a partial Acknowledgement (ACK) has been received. |
| COMPLETE | All transactions in the Import file have been successfully processed. |
| COMPLETE_WITH_ERRORS | Some but not all transactions in the import file have been successfully processed. |
| REJECTED | There were errors in the import file and it has not been possible to process it. |
You may configure your notifications to be triggered for any of these statuses or for all. Configure your Webhooks as required via the Nuapay Console.
Webhook Event Message Details
The following table describes the details of the Webhook notification:
| Parent | Parameter | Type | Mandatory/Optional | Description |
|---|---|---|---|---|
| root | eventTimestamp | number | Mandatory | The Unix epoch timestamp |
| root | eventType | string | Mandatory | Always set to FileStatusUpdated. |
| root | resourceReference | string | optional | The business reference of the resource: Message ID. |
| root | resourceReferenceType | string | optional | The business reference of the resource: the actual Message ID. |
| root | resourceUri | string | Mandatory | The URI of the file resource. |
| root | resourceType | string | Mandatory | This is the type of the resource to which the URI is related. In this case it is a File resource. |
| root | reasonCode | string | optional | Always null for files. |
| root | resourceOwner | string | Mandatory | This is the identifier of the merchant resource to which this notification is linked. |
| root | resourceRemittanceInformation | string | optional | Always null for files. |
JSON Sample
The following is an example of a File Status Update event JSON:
Headers:
| POST | http://example.com/webhooks |
| Content-Type: | application/json;charset=UTF-8 |
| x-signature: | 123ab01d030dee864fb44cc65a3be52ae591f46cde8d14d3e72fbc3790e4a304 |
| Content-Length: | 261 |
| X-Request-Id: | dc645679-71a5-498d-bb29-ec027948c7c1 |
JSON Request Body
{
"eventTimestamp": 1501169079000,
"eventType": "FileStatusUpdated",
"resourceReference": "202310171191612G08-05",
"resourceReferenceType": "MessageId",
"resourceUri": "/files/j29pwvl5bx",
"resourceType": "File",
"reasonCode": null,
"resourceOwner": "tc47ygrg72",
"resourceRemittanceInformation": null
}