Poll for payment status

Learn how to poll the payment resource to get the status of the payment.

The application can poll the payment resource to see if the status has been modified. This allows the application to know if the payment was successful or not.

curl -H "Authorization: Bearer ${access_token}" \
https://pay-api.truelayer.com/v2/single-immediate-payments/dcc3e785-76d3-415c-8bd7-553f17f49c4a

The payment resource may exist in different states according to the progress of the transaction:

StatusTerminalDescription
initiated-The payment resource has been created, but the user has not yet authorised the payment. The initial API response will always have this status if the API call is successful.
cancelledTerminalThe user has cancelled the payment through their bank portal. This may also happen for some bank UIs if the user clicks the Back button in their browser.
authorisation_failedTerminalThe user attempted to authorise the payment with the bank, but failed to do so successfully
executing-The user has successfully authorised the payment using the bank portal, but the payment has not yet executed.
rejectedTerminalThe user authorised the payment, but the bank rejected it after this.
executedTerminalThe funds have left the remitter’s account and will arrive in the beneficiary’s account. This is a terminal state.
expired [1]TerminalA payment was not authorised within the expiry of the initiation.

The executing and executed/rejected states may be very close. A bank may respond to the payment submission indicating the payment has already been executed. However, it is also possible for a payment to be queued within the bank for a short period of time. In that case, the payment status will initially be executing, and then may be updated to executed after polling for a status check.

Note that after a payment has been executed, it may take some time for it to be settled, although for transactions executed via Faster Payments in the UK, this normally happens very quickly.

If the remitter was specified, remitter details will also be included in the response.

{
  "result": {
    "single_immediate_payment_id": "dcc3e785-76d3-415c-8bd7-553f17f49c4a",
    "status": "initiated",
    "initiated_at": "2020-10-13T10:01:23.381802",
    "amount_in_minor": 120000,
    "currency": "GBP",
    "provider_id": "eg-provider",
    "scheme_id": "payment_scheme",
    "fee_option_id": "split_fee",
    "beneficiary": {
      "account": {
        "type": "sort_code_account_number",
        "sort_code": "234567",
        "account_number": "23456789"
      },
      "name": "Financial Services Ltd"
    },
    "remitter": {
      "account": {
        "type": "sort_code_account_number",
        "sort_code": "987654",
        "account_number": "98765432"
      },
      "name": "Mike Smith"
    },
    "references": {
      "type": "separate",
      "beneficiary": "FinServ-1a2b3c4d",
      "remitter": "FS-1000001"
    }
  }
}

The submitted and executed states occur close together. A bank may respond to the payment submission indicating the payment has already been executed. However, it is also possible for a payment to be queued within the bank for a short period of time. Then the payment status will initially be submitted, and may be later updated to executed after polling for a status check.

After a payment has been executed, it may take some time for it to be settled. For transactions executed through Faster Payments, the settlement period is shorter.

To see all known states of your payment and trace your payment with the timestamps, add /statuses to the end of the request.

[1] The expired status is not yet available and will be coming soon.


Did this page help you?