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.
workspaceId: Workspace ID.
eventTrigger: Indicator of the reason an event was triggered. One of api, action, or external.

Event types

Payrails supports several event types that trigger notifications during the workflow lifecycle. Each event provides specific insights into what has happened within the execution or transaction. Here’s an overview of the event types you may encounter in the notifications.

Event Type	Description	Example
`executionCreated`	Occurs when a new execution has been created for a workflow, such as initiating a payment process for an order.	An execution for order `3573894940903` was created, beginning the transaction processing.
`executionActionRequested`	Represents when a specific action, like an authorization, has been requested. It shows the details of what was requested to be executed.	A request was made to authorize a payment for €12.50 using a credit card.
`ruleEngineExecuted`	Indicates that the rule engine has processed a transaction and evaluated applicable rules to determine provider or payment priorities.	A rule evaluated the customer’s country (e.g., `DE`) and operating system (`ios`) for provider selection.
`executionActionCompleted`	Indicates that a specific action in the workflow has been completed, such as a payment authorization. This event signals its success.	A card authorization was processed successfully for a customer order.
`executionActionUpdated`	Indicates the status or result of a previously requested action has been updated, such as an authorization moving from pending to success.	An authorization action was updated to reflect its successful processing.
`networkOffersEnrollmentCompleted`	Signals that a payment instrument (e.g., a card) has successfully enrolled in a network offers program.	A Visa card was successfully enrolled in a rewards program during a transaction.

Each event contains metadata about the execution, action, or rule involved in the transaction process, allowing you to track the progress and details of each step in the workflow.

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”`
`actionMeta`	Object	Additional 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 ****" } }`
`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 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.

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”`
`operationResultProviderDetails`	Object	Object containing the raw fields from the provider on which we based our decision for the `operationResult`. More info here.	{}
`integrationType`	Enum	Type of integration used to communicate with the provider.	`”api”`
`paymentMethodCode`	String	Code of the payment method used by the customer.	`”card”`
`accountFundingTransaction`	Boolean	Indicates whether the payment was an Account Funding Transaction. For example, loading a prepaid card, topping up a wallet, or funding a person-to-person (P2P) money transfer.	`false`
`acquirerMID`	String	Merchant Identifier (MID) on the acquirer that processed the payment.	`"245243"`
`acquirerReference`	String	Acquirer Reference Number (ARN) assigned to the payment by the issuer.	`"1233524535345"`
`retrievalReference`	String	Retrieval Reference Number (RRN) assigned to the payment by the issuer.	`"8657867867867"`
`authorizationCode`	String	The acquirer authorization code if the payment was authorized.	`"50"`
`acquirerAccountCode`	String	Account Code on the acquirer that processed the payment.	`"MI21"`
`acquirerCountryCode`	String	Country Code on the acquirer that processed the payment.	`"NL"`
`paymentInstrumentId`	UUID	Identifier of the Instrument stored in Payrails. Only returned if `storeInstrument` was `true`. For more details, you can check the `paymentInstrument` object.	`”a4a7ed2d-bdcc-46a3-a9f2-701b5d7924b0”`
`paymentInstrument`	Object	Summary of the Instrument used for the operation.	`{}`
`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 check the provider object.	`”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”`
`provider`	Object	Summary of the provider used for the operation. To get the complete information, you can use the Get provider by ID API.	`{}`
`providerReference`	String	Identifier of the top-level payment in the provider.	`”payment-12345”`
`operationProviderReference`	String	Identifier of the operation in the provider. Remember that some providers have a different identifier for each capture, refund, etc.	`”operation-12345”`
`threeDS`	Object	Encapsulates various parameters related to 3DS authentication. 3D Secure	`{}`

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 obtain a result for your action.

When processing their response, we extract and map the most important fields to our unified fields and result codes. In addition, you can still find the most critical fields about the operation in the provider, for example:

operationProviderReference is the identifier of the operation in the provider's system
operationResultProviderDetails is an object with the fields we based our calculation of the unified operationResult from Payrails on

For example, the following extract of our notification body explains how we reached the InsufficientBalance Payrails result based on three different fields from Hyperpay's response that we share in the additionalData section. Additionally, if the provider gives us a human-readable description of the decline reason, it will appear in the message field.

{
  "operationResult": "InsufficientBalance", //Payrails result
  "operationResultProviderDetails": {
    "message": "transaction declined (amount exceeds credit)", //provider message
    "additionalData": { //provider fields involved in the result calculation
      "result.code": "800.100.155",
      "resultDetails.ExtendedDescription": "No sufficient funds",
      "resultDetails.response.acquirerMessage": ""
    }
  },
  ... other fields ...
}

The keys in the additionalData are the JSON Paths to the fields in the response body. So Hyperpay's response looked something like this:

{
  "result": {
    "code": "800.100.155",
    "description": "transaction declined (amount exceeds credit)"
  },
  "resultDetails": {
    "ExtendedDescription": "No sufficient funds",
    "clearingInstituteName": "MADA via Postilion",
    "ConnectorTxID1": "90002550",
    "ConnectorTxID3": "|51|1008|929292||81374134||",
    "ConnectorTxID2": "299630|1231231232|123123123",
    "AcquirerResponse": "51"
  },
   ... other fields ...
}

In addition to this, sometimes you want to include even more specific provider-specific fields in 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 details in this page.

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",
         "operationResultProviderDetails": {
           "additionalData": {
             "result.code": "000.100.000",
             "resultDetails.extendedDescription": "Paid"
            },
           "message": "the instrument is marked as lost"
         },
         "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",
         "accountFundingTransaction":false,
         "acquirerMID":"245243",
         "acquirerReference":"1233524535345",
         "retrievalReference":"8657867867867",
         "authorizationCode":"50",
         "acquirerAccountCode:":"MI21",
         "acquirerCountryCode":"NL",
         "success":true,
         "provider":{
            "id":"5eb08624-ecce-4cbc-9a8a-61d484172815",
            "name":"checkout",
            "displayName":"Checkout.com",
            "type":"Payment",
            "status":"active",
            "configSchema":"{\"required\":[\"accountDetails\",\"credentials\"],\"definitions\":{\"PspCheckoutAccountDetails\":{\"required\":[\"processingChannelId\"],\"properties\":{\"processingChannelId\":{\"title\":\"Processing channel ID\",\"minLength\":1,\"pattern\":\"^pc_.+$\",\"type\":\"string\"}},\"type\":\"object\"},\"PspCheckoutCredentials\":{\"required\":[\"clientId\",\"clientSecret\"],\"properties\":{\"clientId\":{\"title\":\"Client ID\",\"description\":\"Client ID used to authenticate requests to the Checkout API\",\"minLength\":1,\"type\":\"string\"},\"clientSecret\":{\"title\":\"Client Secret\",\"description\":\"Client Secret used to authenticate requests to the Checkout API\",\"minLength\":1,\"type\":\"string\",\"format\":\"secret\"},\"hmacKeys\":{\"title\":\"HMAC keys\",\"description\":\"HMAC keys used to authenticate notifications from the Checkout API\",\"pattern\":\"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$\",\"items\":{\"type\":\"string\"},\"type\":\"array\",\"format\":\"secret\"}},\"type\":\"object\"}},\"properties\":{\"accountDetails\":{\"$ref\":\"#/definitions/PspCheckoutAccountDetails\",\"title\":\"Account details\"},\"credentials\":{\"$ref\":\"#/definitions/PspCheckoutCredentials\",\"title\":\"Checkout credentials\"}},\"type\":\"object\"}",
            "createdAt":"2021-01-05T10:20:00.000Z",
            "updatedAt":"2022-06-14T11:50:00.000Z"
         },
         "threeDS":{
            "authenticationValue":"AAABAVIREQAAAAAAAAAAAAAAAAA=",
            "challenged":true,
            "dsTransId":"5ed5d1d0-982f-45f4-97a1-68651ac429d0",
            "eci":"05",
            "enrolled":"Y",
            "exemptionApplied":"none",
            "exemptionIndicator":"none",
            "transStatus":"Y",
            "version":"2.2.0"
         },
         "paymentInstrument":{
            "id":"b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
            "holderId":"788c7c09-a490-4603-915a-e2a957a6cca1",
            "createdAt":"2022-04-22T17:53:36.814Z",
            "updatedAt":"2022-04-22T17:53:36.814Z",
            "paymentMethod":"card",
            "displayName":"Visa **** 1111",
            "description":"Personal card.",
            "fingerprint":"739abff0-406a-4d32-8cfb-701e12be5848",
            "status":"created",
            "futureUsage":"CardOnFile",
            "networkTransactionReference":"987654321234567",
            "data":{
               "network":"visa",
               "bin":"411111",
               "suffix":"1111",
               "expiryMonth":"10",
               "expiryYear":"2026",
               "holderName":"John Doe"
            },
            "meta":{
               "communityCode":"GAP",
               "userKey":"9890124569"
            },
            "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": [
    {
      "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"
      }
    }
  ],
  "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": [
        {
          "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"
          }
        }
      ],
      "operationResult": "BlockedInstrument",
      "operationResultDetail": "LostInstrument",
      "operationResultProviderDetails": {
        "additionalData": {
          "result.code": "800.100.999",
          "resultDetails.extendedDescription": "Lost instrument"
        },
        "message": "the instrument is marked as lost"
      },
      "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
}

Event types

Action-specific details object

📘

execution details

paymentComposition details

Provider-specific details

errors details

Examples

Success

Failure

`execution` details

`paymentComposition` details

`errors` details