Processing payments is a complex and long chain of interactions between many actors involved, and there's a long list of things that can go wrong there. Thankfully, our team at Payrails has seen a lot in their years of experience and is here to help you navigate this complex field.

One of the main challenges we have is to understand exactly what happened in a payment transaction. Unfortunately, there's not yet a standard of responses from PSPs, and each of them has its own way to inform you about these results. For example, some of them opt for a numeric list of possible responses, others choose to inform you through HTTP status codes, others through a string field, and a big etcetera.

Payrails comes to your help here! Every time we integrate a new PSP, we work together with them to map from their list of response codes to ours, so that we can provide you with only one list of possible results regardless of which PSP was used for processing the transaction.

These response codes can be found in the result field of each of your Payment Operations. For example, here's how the Get an execution by ID response would look for a failed execution because of blocked instrument:

{
  "id": "fe67fc45-ce47-4fc8-a283-22d03ae68b77",
  "status": [
    ...
    {
      "code": "authorizeFailed",
      "time": "2022-04-22T17:53:36.814Z",
      "errors": [
        {
          "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
          "code": "workflow.action.failed",
          "detail": "The execution of the requested workflow action failed",
          "docUrl": "https://docs.payrails.com/docs/error-codes#workflow.action.failed",
          "reason": {
            "category": "Instrument",
            "result": "BlockedInstrument",
            "source": "Customer",
            "detail": "LostInstrument"
          }
        }
      ]
    }
  ],
  ...
}

And here's the notification for the same execution:

{
  "event": "executionActionCompleted",
  "time": "2022-04-22T17:53:36.814Z",
  "details": {
    "action": "authorize",
    "execution": {
      "workflowCode": "d5454c2f-ae5e-44f3-8edf-f6dad64f005f",
      "id": "fe67fc45-ce47-4fc8-a283-22d03ae68b77",
      "merchantReference": "order_3573894940903"
    },
    "success": false,
    "errors": [
      {
        "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
        "code": "workflow.action.failed",
        "detail": "The execution of the requested workflow action failed",
        "docUrl": "https://docs.payrails.com/docs/error-codes#workflow.action.failed",
        "reason": {
          "category": "Instrument",
          "result": "BlockedInstrument",
          "source": "Customer",
          "detail": "LostInstrument"
        }
      }
    ]
  }
}

Result Categories

Before listing down the list of all possible result codes, you must know that the fields source and detail under the reason struct are optional, meaning they will be filled/provided based on the result itself. Below is a list of all possible result codes from Payrails, grouped by category with their descriptions and possible optional fields:

Success

Since successful payments are by definition not encountering errors, you'll usually find the results under the Success category listed in the operationResult field as there won't be an error struct attached. In such cases the success flag will be set to true in the response you receive.

Pending

Next, also a type of happy path but with some type of pending action before they can be completed.

Redirect

Next, also a type of happy path but with some type of pending action, namely redirection, before they can be completed.

Unknown

Let's discuss the most worrying ones next, the ones where we don't know what actually happened. Any of these results should be considered a high priority to alert and analyze as soon as possible.

Connection

Next, equally important to analyze and optimize if possible, are the connection and timeout-related codes.

Operation

Next, let's look at the payment rejection results, which depending on the provider and other factors, may go from completely generic to very specific.

Instrument

Next, a special type of payment rejections, the payment instrument related rejections.

Configuration

Next, we have the parameter or configuration errors. These could be similar to the rejections but could be caused by a problem with formatting, missing required parameters, etc.

PayerAuthentication

Next, we have the payer authentication error, which can either arise from a missing or incorrect PIN or a 3DS check that didn't occur. It's important to distinguish these ones, that are payer specific, from the server credentials authentication errors.