Notifications

This page describes how our Notifications work and what they include.

Many of the actions executed during a workflow can involve calls to external providers, which is prone to timeouts and long-running processes. For that reason, Payrails sends notifications to your server when the execution of the requested actions finishes.

Make sure you configured your server to Receive notifications before checking this guide.

All notifications follow the same schema:

  • event: Type of event that happened.
  • time: Date and time when the event happened.
  • details: Event-specific details about the event.

Action-specific details object

Every possible action on an Execution has its own different fields that are relevant. In the following table, we'll show you the possible fields that can be inside the details object of each notification.

📘

The actionId in each notification corresponds to the one you received in the response to the action you performed on the Execution.

FieldTypeDescriptionExample
actionEnumType of action that was completed.One of: authorize, confirm, capture, cancel, refund.
actionIdUUIDIdentifier of the action, also returned at the start of it.”b0c28520-eca0-4be6-8771-99c43144bdaf”
actionMetaObjectAdditional information provided as meta fields about the specific action. Note that these are the meta fields that are immutable per action and populated separately than the meta under execution object."actionMeta": { "customer": { "deliveryAddress": "Street A ****" } }
successBooleanFlag indicating if the entire action was successful.true
errorsArrayIf success=false, this array contains the errors occured. The structure of the items is explained below in this document.[]
executionObjectSummary of the Execution for which the action was executed. Its structure is described in a table below.-
amountAmountTotal amount of the execution. If it contains multiple payments, it’s the sum of all of them.”{”currency”: “EUR”, ”value”: “10”}”
paymentCompositionArrayList of payment attempts in the execution. Its structure is described in a table below.-

execution details

The structure of the execution object mentioned above is described in the following table.

FieldTypeDescriptionExample
idUUIDIdentifier of the Execution. For more details, you can use this ID in the Get an execution by ID API.”b0c28520-eca0-4be6-8771-99c43144bdaf”
workflowCodeStringCode of the workflow that was executed.”payment-acceptance”
merchantReferenceStringMerchant-specific identifier for the execution.”order-12345”
holderReferenceStringMerchant-specific identifier for the holder that owns the execution.”user-12345”
holderIdUUIDIdentifier of the Holder that owns the execution. For more details, you can use this ID in the Get a holder by ID API.”b0c28520-eca0-4be6-8771-99c43144bdaf”
metaObjectAdditional information provided as meta fields about the execution provided as context.{}

paymentComposition details

The structure of each item of the paymentComposition array mentioned above is described in the following table.

FieldTypeDescriptionExample
successBooleanFlag indicating if the particular payment attempt was successful.true
errorsArrayIf success=false, this array contains the errors occurred in this payment attempt. The structure of the items is explained below in this document.[]
operationTypeEnumType of the operation executed. Usually same as the action type. Possible values are described here.”Authorize”
operationResultEnumPayrails mapped result for the operation. Possible values are described here.”Success”
integrationTypeEnumType of integration used to communicate with the provider.”api”
paymentMethodCodeStringCode of the payment method used by the customer.”card”
paymentInstrumentIdUUIDIdentifier of the Instrument stored in Payrails. Only returned if storeInstrument was true. To get more details about it, you can use the Get an instrument by ID API.”a4a7ed2d-bdcc-46a3-a9f2-701b5d7924b0”
paymentInstrumentObjectSummary of the Instrument used for the operation. To get the complete information, you can use the Get an instrument by ID API.{}
storeInstrumentBooleanFlag indicating if the operation requested to store the Instrument for future usage.true
paymentIdUUIDIdentifier of the payment attempt in Payrails. For more details, you can use the Get payment by ID API.”b0c28520-eca0-4be6-8771-99c43144bdaf"
amountAmountAmount of the specific payment attempt. Can be different than the total if there are many.”{”currency”: “EUR”, ”value”: “10”}”
providerIdUUIDIdentifier of the provider that was used for the payment attempt. For more details, you can use the Get provider by ID API.”b0c28520-eca0-4be6-8771-99c43144bdaf”
providerConfigIdUUIDIdentifier of the specific configuration that was used in the provider for the payment. For more details, you can use the Provider config by ID API.”b0c28520-eca0-4be6-8771-99c43144bdaf”
operationProviderReferenceStringIdentifier of the operation in the provider. Keep in mind that some providers have a different identifier for each capture, refund, etc.”operation-12345”

Provider-specific details

During the processing of a requested action, Payrails calls external providers in the format they are expecting, and then processes their response to be able to get a result for your action.

When processing their response, we extract the most important fields and map them to their own fields on our side. For example, we extract the identifier of the payment in the provider and put it in the operationProviderReference field for you.

However, sometimes you want to include certain provider-specific fields to your notifications payloads. You can ask our team to add any response field to the providerResponseAdditionalFields object inside each item in the paymentComposition array in your notification payload.

If you still need more details or the entire raw request and response for an operation, you can use the Get Payment Operation Logs endpoint, because we store the raw request and responses we do to the providers.

errors details

Our notifications can describe errors in two different ways:

  • errors array in the top-level describes the general result of the action executed.
  • errors array in each of the items in the paymentComposition array describes the specific errors in each payment attempt. This is especially useful if your workflow generates many payments per execution.

The structure of any of those error items is the described in the following table.

FieldTypeDescriptionExample
idUUIDIdentifier of the error in Payrails system. Please share this value when working with our team debugging the error.”b0c28520-eca0-4be6-8771-99c43144bdaf”
titleStringMachine-friendly code for this error type.”execution.payment-method.failed”
detailStringHuman-friendly detailed description of the error.”The payment method produced a non-successful status.”
metaObjectAdditional information useful for the context of the error.{}

Examples

Success

{
  "action": "authorize",
  "actionId": "9a72c5a3-8894-435f-aea6-8b305a4dc29f",
  "actionMeta": {
    "customer": {
        "deliveryAddress": "Street A ******"
      }
    },
  "amount": {
    "currency": "EUR",
    "value": "24.00"
  },
  "execution": {
    "holderReference": "customer123",
    "holderId": "9d113e2a-35a0-40e1-828b-35a18ac35b41",
    "id": "f8c36786-008d-4352-a0cf-b799955dbfc2",
    "merchantReference": "order_3573894940903",
    "meta": {
      "order": {
        "reference": "order_3573894940903"
      },
      "customer": {
        "reference": "1231905323475",
        "country": {
          "code": "DE"
        }
      },
      "clientContext": {
        "ipAddress": "217.110.239.132",
        "osType": "ios"
      }
    },
    "workflowCode": "payment-acceptance"
  },
  "paymentComposition": [
    {
      "operationType": "Authorize",
      "amount": {
        "currency": "EUR",
        "value": "24.00"
      },
      "integrationType": "api",
      "operationResult": "Success",
      "operationProviderReference": "provider-reference-example",
      "providerId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
      "providerConfigId": "1e308624-e5ce-4cvc-9a8a-61d482172817",
      "paymentId": "c9e1a8ea-a0de-42bd-bcfd-46d3f437b5fe",
      "paymentInstrumentId": "",
      "storeInstrument": true,
      "paymentMethodCode": "card",
      "success": true,
      "paymentInstrument": {
        "tokens": [
          {
            "type": "psp",
            "reference": "provider-token",
            "meta": {
              "holderReference": "provider-customer-reference"
            }
          }
        ]
      }
    }
  ],
  "success": true
}

Failure

{
  "action": "authorize",
  "actionId": "d31d96a5-979b-4f0b-bc31-a20e820e1816",
  "amount": {
    "currency": "EUR",
    "value": "24.00"
  },
  "errors": [
    {
      "detail": "The payment method produced a non-successful status.",
      "id": "4a8fe381-6a77-4810-b72d-4cc00e5606c5",
      "title": "execution.payment-method.failed"
    }
  ],
  "execution": {
    "holderReference": "customer123",
    "holderId": "9d113e2a-35a0-40e1-828b-35a18ac35b41",
    "id": "f8c36786-008d-4352-a0cf-b799955dbfc2",
    "merchantReference": "order_3573894940903",
    "meta": {
      "order": {
        "reference": "order_3573894940903"
      },
      "customer": {
        "reference": "1231905323475",
        "country": {
          "code": "DE"
        }
      },
      "clientContext": {
        "ipAddress": "217.110.239.132",
        "osType": "ios"
      }
    },
    "workflowCode": "payment-acceptance"
  },
  "paymentComposition": [
    {
      "errors": [
        {
          "detail": "The payment method produced a non-successful status.",
          "id": "4a8fe381-6a77-4810-b72d-4cc00e5606c5",
          "title": "execution.payment-method.failed"
        }
      ],
      "operationResult": "InsufficientBalance",
      "operationType": "Authorize",
      "success": false,
      "amount": {
        "currency": "EUR",
        "value": "24.00"
      },
      "integrationType": "api",
      "operationProviderReference": "provider-reference-example",
      "providerId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
      "providerConfigId": "1e308624-e5ce-4cvc-9a8a-61d482172817",
      "paymentId": "c9e1a8ea-a0de-42bd-bcfd-46d3f437b5fe",
      "paymentInstrumentId": "a4a7ed2d-bdcc-46a3-a9f2-701b5d7924b0",
      "storeInstrument": true,
      "paymentMethodCode": "card",
      "paymentInstrument": {
        "tokens": [
          {
            "type": "psp",
            "reference": "provider-token",
            "meta": {
              "holderReference": "provider-customer-reference"
            }
          }
        ]
      }
    }
  ],
  "success": false
}