Payment Errors

When processing payments there are two types of errors that can occur: synchronous errors that you get back as an http response to your requests and errors that happens during asynchronous processing.

This guide will walk you through the following:

1. Synchronous Errors that you get back as an http response to your requests
2. Asynchronous Errors that happens during asynchronous processing.

Synchronous ErrorsCopy URL

All API error responses follow a consistent format that includes details about what went wrong:

{
  "errors": [
    {
      "code": "error_code",
      "source": {
        "parameter": "field_name"
      },
      "title": "Description of what went wrong"
    }
  ],
  "successes": [
    {
       "resource_type": "payment",
       "resource_id": "f1fde464-a8bc-4579-9f29-f21047316709",
       "message": "payment_session successfully created"
    }]
}

The errors array contains all the errors that occurred during the request. The code can be one of:

• invalid_action: The action you are trying to perform is not valid for the current state of the payment session.
• unauthorized: The request is missing authentication credentials or the provided credentials are invalid.
• bad_request: The request is malformed or contains invalid parameters.
• invalid_error_url: The error URL provided is not valid.
• invalid_success_url: The success URL provided is not valid.
• invalid_reference: The reference provided is not valid.
• invalid_description: The description provided is not valid.
• invalid_request: The request is invalid or malformed. Check Source and Title to understand what's wrong.
• invalid: Similar to invalid_request
• invalid_payee_account_identifier: The payee account identifier provided is not valid.
• invalid_payer_email: The payer email provided is not valid.
• invalid_amount: The amount provided is not valid.
• invalid_currency: The currency provided is not valid.
• invalid_line_items.amount_cents: The amount_cents provided in line items is not valid.
• missing_amount_or_line_items: The request is missing either the amount or line items. You must provide one of them.
• missing_currency_or_line_items: The request is missing either the currency or line items. You must provide one of them.
• invalid_amount_cents: The amount_cents provided is not valid.
• invalid_bank_account: There's something wrong with the banked bank account you're trying to use for this payment.
• invalid_payee_name: The payee name provided is not valid.
• not_found: You're trying to use a resource that doesn't exist or has been deleted (e.g. bank account, mandate, etc.).
• session_not_found: The payment session you're trying to access doesn't exist or has been deleted.
• invalid_payee: The payee provided is not valid.
• invalid_expiration: The expiration date provided is not valid.
• invalid_expiration_format: The expiration date provided is not valid.
• invalid_business: There is something wrong with the configuration of the business you're trying to use to create the payment.
• invalid_idempotency_key: The idempotency key provided is not valid. This could mean that you try to reuse an idempotency key that was already used for a different request.
• decoding: The request body could not be decoded. This could mean that the request body is not valid JSON or that the request body is too large.
• internal: An internal error occurred while processing your request.
• method_not_allowed: The HTTP method used for the request is not allowed for the endpoint you're trying to access.

Source is the specific field or parameter that caused the error. It can be a path to a specific field in the request body, or a general description of the issue. Title is a human readable explanation of the error

Optionally, for the case when you sent a request to create a Payment session with a list of actions to be taken on it you can also receive a list of successes in the response. This list contains the actions that were successfully executed. For example, if the payment session was created, but the first action fails you will receive the id of the created payment session.

Asynchronous ErrorsCopy URL

Asynchronous errors are errors that happen during background processing of the payment. These errors an surface in two ways:

• on the latest_error field of the payment session
• if the payment reached the state failed on the state_reason field of the payment session

Latest ErrorCopy URL

The latest_error field contains the latest error that occurred during the processing of the payment. This field is updated when a new error occurs. The latest_error field is only present if there was an error during processing. It can also be reset to null if the error is resolve through the actions you or the customer take on the payment session.