Payin Errors

Payin errors fall into two categories:

• Synchronous errors — returned immediately as an HTTP error response when your API request is invalid or cannot be processed.
• Asynchronous errors — occur during background payment processing, after the API has accepted your request. These surface on the payin object itself via latest_error and status_details.reason.

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": "payin",
      "resource_id": "f1fde464-a8bc-4579-9f29-f21047316709",
      "message": "payin created successfully"
    }
  ]
}

Each object in the errors array has three fields:

• code — identifies the type of error (see table below).
• source — 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 — a human-readable explanation of the error.

Optionally, for the case when you sent a request to create a payin 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 payin was created but the first action fails, you will receive the ID of the created payin.

Asynchronous ErrorsCopy URL

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

• on the latest_error field of the payin
• if the payin reached the status FAILED, additional detail is available in the status_details.reason field of the payin

Latest ErrorCopy URL

The latest_error field contains the latest error that occurred during the processing of the payin. 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 resolved through the actions you or the customer take on the payin.

Retryable ErrorsCopy URL

When a payin reaches a FAILED state, check next_actions.completion_paths to determine your options. If retry_payment is present, the payment can be reattempted without creating a new payin — otherwise you will need to create a new payin.

Retry LimitsCopy URL

The following retry limits apply per payment within the associated mandate's validity window:

• Up to 10 retries in total
• Up to 5 retries within any 24-hour period

Once the total retry limit has been reached, retry_payment will no longer appear in next_actions.

When to RetryCopy URL

Not all failures warrant an immediate retry. Use the latest_error code to guide your approach.

For PAYER_ACCOUNT_INSUFFICIENT_FUNDS, an immediate retry is unlikely to succeed — contact the customer or allow time for sufficient funds to become available before reattempting.

For transient failures such as PAYMENT_SETTLEMENT_BANK_UNAVAILABLE, no customer action is required. You can retry after a short delay or once the issue has resolved.

Retryable Error CodesCopy URL

Errors that may produce a retry_payment action include:

See Payin Retry for the API call.