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.

Field	Type	Description	Example
`action`	Enum	Type of action that was completed.	One of: `authorize`, `confirm`, `capture`, `cancel`, `refund`.
`actionId`	UUID	Identifier of the action, also returned at the start of it.	`”b0c28520-eca0-4be6-8771-99c43144bdaf”`
`success`	Boolean	Flag indicating if the entire action was successful.	`true`
`errors`	Array	If `success=false`, this array contains the errors occured. The structure of the items is explained below in this document.	`[]`
`execution`	Object	Summary of the Execution for which the action was executed. Its structure is described in a table below.	-
`amount`	Amount	Total amount of the execution. If it contains multiple payments, it’s the sum of all of them.	`”{”currency”: “EUR”, ”value”: “10”}”`
`paymentComposition`	Array	List 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.

Field	Type	Description	Example
`id`	UUID	Identifier of the Execution. For more details, you can use this ID in the Get an execution by ID API.	`”b0c28520-eca0-4be6-8771-99c43144bdaf”`
`workflowCode`	String	Code of the workflow that was executed.	`”payment-acceptance”`
`merchantReference`	String	Merchant-specific identifier for the execution.	`”order-12345”`
`holderReference`	String	Merchant-specific identifier for the holder that owns the execution.	`”user-12345”`
`holderId`	UUID	Identifier 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”`
`meta`	Object	Additional information 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.

Field	Type	Description	Example
`success`	Boolean	Flag indicating if the particular payment attempt was successful.	`true`
`errors`	Array	If `success=false`, this array contains the errors occurred in this payment attempt. The structure of the items is explained below in this document.	`[]`
`operationType`	Enum	Type of the operation executed. Usually same as the action type. Possible values are described here.	`”Authorize”`
`operationResult`	Enum	Payrails mapped result for the operation. Possible values are described here.	`”Success”`
`integrationType`	Enum	Type of integration used to communicate with the provider.	`”api”`
`paymentMethodCode`	String	Code of the payment method used by the customer.	`”card”`
`paymentInstrumentId`	UUID	Identifier 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”`
`paymentInstrument`	Object	Summary of the Instrument used for the operation. To get the complete information, you can use the Get an instrument by ID API.	`{}`
`storeInstrument`	Boolean	Flag indicating if the operation requested to store the Instrument for future usage.	`true`
`paymentId`	UUID	Identifier of the payment attempt in Payrails. For more details, you can use the Get payment by ID API.	`”b0c28520-eca0-4be6-8771-99c43144bdaf"`
`amount`	Amount	Amount of the specific payment attempt. Can be different than the total if there are many.	`”{”currency”: “EUR”, ”value”: “10”}”`
`providerId`	UUID	Identifier 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”`
`providerConfigId`	UUID	Identifier 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”`
`operationProviderReference`	String	Identifier 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.

Field	Type	Description	Example
`id`	UUID	Identifier of the error in Payrails system. Please share this value when working with our team debugging the error.	`”b0c28520-eca0-4be6-8771-99c43144bdaf”`
`title`	String	Machine-friendly code for this error type.	`”execution.payment-method.failed”`
`detail`	String	Human-friendly detailed description of the error.	`”The payment method produced a non-successful status.”`
`meta`	Object	Additional information useful for the context of the error.	`{}`

Examples

Success

{
  "action": "authorize",
  "actionId": "9a72c5a3-8894-435f-aea6-8b305a4dc29f",
  "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
}

Action-specific details object

execution details

paymentComposition details

Provider-specific details

errors details

Examples

Success

Failure

`execution` details

`paymentComposition` details

`errors` details