Payment traces

After making a payment to a beneficiary, if that beneficiary does not receive the funds, then it is possible for you to request to trace where the funds are.

You can initiate a trace request through both the User Interface (UI) and the API, depending on your preference. The UI provides a straightforward, user-friendly way to submit trace requests manually, while the API offers a more automated approach, ideal for users looking to integrate this functionality into their own systems. Both methods ensure efficient handling of trace requests within the platform.

The trace process is basically to reach out to every step of the payment flow and find out if they have anything outstanding that is holding up the payment.

It is not possible for a trace to be "unsuccessful" as such, but it is possible that we chase corresponding banks, and they do not respond.

Before you initiate a trace for a payment

To trace a payment, your payment must meet certain conditions:

• The payment must be less than 6 months old while initiating a trace from UI and must be less than 13 months old while initiating a trace from API.
• The payment status must be processed.
• The payment must not be through the Faster Payments or SEPA Instant schemes (the GBP and EUR instant payment schemes). If you attempt to initiate a trace on payments through these schemes, you will still be allowed to initiate a trace, but the trace status will go directly from Requested to Unsuccessful.
• You cannot initiate a trace for a payment, for which there is an active recall or trace request, or if the payment has already been successfully recalled or traced.

You can follow the progress of the trace request via the Client Portal or by using one of the GET traces endpoints.

We will make up to three attempts to trace the payment. This includes the initial trace request and then two additional chasers (five working days apart), if we have not received a response. If the third attempt is unsuccessful, we advise you to contact your client and/or the counterparty's bank directly.

Making a trace request

To initiate a trace, a POST request should be sent to the api/v1/traces endpoint, described in details here to initiate a trace for a payment.

Content specifications body

Request

POST /api/v1/traces

{  
  "paymentId": "3f811c2c-b36a-44ec-9476-33a6584174c5",  
}

Response

{          
"traceId": "f54dd915-7a8a-495f-8531-38e85190fa44",
"paymentId": "f3c7d915-7a8a-495f-8531-38e85190fa44",
"contractReferenceNumber": "010F213241160002"
"status": "Requested", 
"statusReason": null, 
"valueDate": "2023-11-14T00:00:00+00:00"
to: {
      name: 'recipient name', 
      accountIdentifier: "ibanoraccount"
    },
from: {
      name: 'sender name', 
      accountIdentifier: "ibanoraccount"
    },
"amount":
"Currency":
"paymentDetails": 
"createdAt": "2023-07-05T08:01:30.8893207+00:00",
"modifiedAt": "2023-07-06T10:31:30.8893207+00:00",
}

Get details of a trace request

To retrieve the details of a single trace request, use the endpoint api/v1/traces/{trace-id}, where {trace-id} refers to the Id of the trace, received in the response to your trace request. Here is the link to the technical reference of the endpoint: api/v1/traces/{trace-id}

Content specifications body

Request

GET/api/v1/traces/c312fafc-f4cf-4042-9b32-8c5117874bb8

Response

{          
"traceId": "c312fafc-f4cf-4042-9b32-8c5117874bb8",
"paymentId": "f3c7d915-7a8a-495f-8531-38e85190fa45",
"contractReferenceNumber": "010F213241160002"
"status": "Requested", 
"statusReason": null, 
"valueDate": "2023-11-14T00:00:00+00:00"
to: {
      name: 'recipient name', 
      accountIdentifier: "ibanoraccount"
    },
from: {
      name: 'sender name', 
      accountIdentifier: "ibanoraccount"
    },
"amount":
"Currency":
"paymentDetails": 
"createdAt": "2023-07-05T08:01:30.8893207+00:00",
"modifiedAt": "2023-07-06T10:31:30.8893207+00:00",
}

Get details of all traces

To retrieve the details of all traces, use the endpoint api/v1/traces endpoint. Here is the link to the technical reference of the endpoint: Get a collection of traces.

Content specifications header

Request

GET/api/v1/traces?PageNumber=1&PageSize=2

Response

{
    "result": [
        {
         "traceId": "f54dd915-7a8a-495f-8531-38e85190fa44",
        "paymentId": "f3c7d915-7a8a-495f-8531-38e85190fa44",
        "contractReferenceNumber": "010F213241160002"
        "status": "Requested", 
        "statusReason": null, 
        "valueDate": "2023-11-14T00:00:00+00:00"
        to: {
            name: 'recipient name', 
            accountIdentifier: "ibanoraccount"
            },
        from: {
            name: 'sender name', 
            accountIdentifier: "ibanoraccount"
            },
         "amount":
        "Currency":
        "paymentDetails": [] 
        "createdAt": "2023-07-05T08:01:30.8893207+00:00",
        "modifiedAt": "2023-07-06T10:31:30.8893207+00:00",
        },
        {          
        "traceId": "1891f972-7916-4606-9bb5-f9a006d12345",
        "paymentId": "28fb9281-94b5-4533-b192-ebb056f3e6de",
        "contractReferenceNumber": "010F213241160123"
        "status": "In progress", 
        "statusReason": null, 
        "valueDate": "2023-11-14T00:00:00+00:00"
        to: {
            name: 'recipient name', 
            accountIdentifier: "ibanoraccount"
            },
        from: {
            name: 'sender name', 
            accountIdentifier: "ibanoraccount"
            },
      "amount":
        "Currency":
        "paymentDetails": [] 
        "createdAt": "2023-07-05T08:01:30.8893207+00:00",
        "modifiedAt": "2023-07-06T10:31:30.8893207+00:00",
        }
    ],
    "pageInfo": {
        "currentPage": 1,
        "pageSize": 50,
        "rowCount": 2
    }
}

Status of a trace request

To only get the status of a specific trace request, use the endpoint /api/v1/trace/{trace-id}/status, where {trace-id} refers to the ID of the trace, received in the response to your trace request. Here is the link to the technical reference of the endpoint: Get status of a trace.

Content specification header

Request

GET/api/v1/traces/1891f972-7916-4606-9bb5-f9a006d12345/status

Response

{  
  "status": "Requested"  
}

Cancel a trace request

To cancel a specific trace request, use the endpoint /api/v1/trace/{trace-id}/cancel, where {trace-id} refers to the ID of the trace, received in the response to your trace request. Here is the link to the technical reference of the endpoint: Cancel a trace.

Content specification header

Request

PUT/api/v1/traces/1891f972-7916-4606-9bb5-f9a006d12345/cancel

Response

{          
"traceId": "f54dd915-7a8a-495f-8531-38e85190fa44",
"paymentId": "f3c7d915-7a8a-495f-8531-38e85190fa44",
"contractReferenceNumber": "010F213241160002",
"status": "Cancelled", 
"statusReason": null,
"valueDate": "2023-11-14T00:00:00+00:00",
to: {
      name: 'recipient name', 
      accountIdentifier: "ibanoraccount"
    },
from: {
      name: 'sender name', 
      accountIdentifier: "ibanoraccount"
    },
"amount":
"Currency":
"paymentDetails": [] 
"createdAt": "2023-07-05T08:01:30.8893207+00:00",
"modifiedAt": "2023-07-06T10:31:30.8893207+00:00",
}