Receive status updates of your payment

After a payment has been authorised by the end user, you can poll the GET /payments/{id} endpoint until the payment reaches a terminal status (succeeded/settled or failed), to determine its outcome.

Payment statuses

Status

Description

authorization_required

A payment resource has been created successfully with the create payment endpoint, and must now be authorised.

authorizing

The authorization flow has been initiated.

authorized

The payment has been successfully authorized by your user, and the outcome of the payment is pending an update from the provider.

succeeded

The payment has been successfully executed by the provider (that is, the user's bank).

failed

The payment was not successful.
Additional fields on the payment will be set in this case, see below.

settled*

The payment has arrived in your merchant account. (only for payments where the beneficiary.type is merchant_account).

The status transitions of a successful payment will be as follows:

Authorization required -> Authorizing -> Authorized -> Successful -> Settled

The status transitions of a failed payment can be the following:

Option 1: Authorization required -> Authorizing -> Failed
Option 2: Authorization required -> Authorizing -> Authorized -> Failed

Image illustrating the valid status transitions of a payment.Image illustrating the valid status transitions of a payment.

Image illustrating the valid status transitions of a payment.

Failed Status

If a payment is in the failed status, you can find more details about when and why the payment failed, from the following additional fields that will be populated on the payment:

Field Name

Description

failure_stage

The status of the payment at the point of failure.

Values:

  • authorization_required
  • authorizing
  • authorized

failure_reason

The reason why the payment failed. [1]

Values:

  • canceled
  • expired
  • authorization_failed: The payment authorization could not be submitted to the provider
  • provider_rejected: The payment was rejected by the provider for an unspecified reason.
  • unsupported_action: The payment could not be completed as it requires an action not support by the client.

[1] We will add to the list of possible reasons returned on this field. You shouldn't expect this field to always contain one of the listed values. Make sure to handle any undocumented values as a generic failure reason.


Did this page help you?