Guides
Go to payrails.com
Start typing to search…

Payout Workflow Events

Learn more about of payout events and webhook notifications.

Overview

The Payout Workflow system generates events at key stages of the payout lifecycle. These events provide detailed information about execution states, action requests, completions, and updates. Events are triggered when lookup operations are requested/completed, payout operations are requested/completed, and when payout status transitions occur.

Event Types

  1. Execution Created (executionCreated)

Triggered when: A new payout execution is created and initialized.

Payload Structure:

{
  "id": "uuid",
  "workflow": "payout",
  "workflowExecutionId": "string",
  "workflowActionId": "uuid",
  "workspaceId": "uuid",
  "eventType": "executionCreated",
  "details": {
    "request": {
      "merchantReference": "string",
      "workspaceId": "uuid",
      "holderReference": "string", 
      "initialActions": [
        {
          "action": "lookup",
          "body": {
            "amount": {
              "value": "number",
              "currency": "string"
            },
            "meta": {}
          }
        }
      ],
      "meta": {},
      "scope": {
        "holderReference": "string",
        "clientId": "string", 
        "iat": "number",
        "exp": "number"
      }
    },
    "response": {
      "id": "uuid",
      "workspaceId": "uuid", 
      "merchantReference": "string",
      "workflow": {
        "code": "payout",
        "version": "number"
      },
      "createdAt": "ISO8601 timestamp",
      "meta": {},
      "amount": {
        "value": "number",
        "currency": "string"
      },
      "links": {
        "self": "string URL",
        "lookup": {
          "href": "string URL",
          "method": "POST"
        },
        "payout": {
          "href": "string URL", 
          "method": "POST"
        }
      },
      "initialResults": [
        {
          "action": "lookup",
          "body": {
            "name": "lookup",
            "actionId": "uuid",
            "workspaceId": "uuid",
            "executedAt": "ISO8601 timestamp",
            "data": {
              "paymentCompositionOptions": [
                {
                  "paymentMethodCode": "string",
                  "providerCode": "string",
                  "fees": {
                    "value": "number",
                    "currency": "string"
                  }
                }
              ]
            },
            "links": {
              "execution": "string URL",
              "authorize": {
                "href": "string URL",
                "method": "POST"
              }
            }
          }
        }
      ]
    }
  },
  "createdAt": "ISO8601 timestamp",
  "eventTrigger": "api"
}

Example:

{
  "id": "evt_123e4567-e89b-12d3-a456-426614174000",
  "workflow": "payout",
  "workflowExecutionId": "123e4567-e89b-12d3-a456-426614174000",
  "workflowActionId": "00000000-0000-0000-0000-000000000000",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "executionCreated",
  "details": {
    "request": {
      "merchantReference": "payout-12345",
      "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
      "holderReference": "[email protected]",
      "initialActions": [
        {
          "action": "lookup",
          "body": {
            "amount": {
              "value": 10000,
              "currency": "USD"
            }
          }
        }
      ],
      "meta": {
        "orderId": "order-789"
      }
    },
    "response": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
      "merchantReference": "payout-12345", 
      "workflow": {
        "code": "payout",
        "version": 1
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "links": {
        "self": "<https://api.payrails.com/v1/payout/executions/123e4567-e89b-12d3-a456-426614174000>",
        "lookup": {
          "href": "<https://api.payrails.com/v1/payout/executions/123e4567-e89b-12d3-a456-426614174000/lookup>",
          "method": "POST"
        },
        "payout": {
          "href": "<https://api.payrails.com/v1/payout/executions/123e4567-e89b-12d3-a456-426614174000/payout>", 
          "method": "POST"
        }
      }
    }
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "eventTrigger": "api"
}
  1. Action Requested(executionActionRequested)

Triggered when: A lookup or payout action is requested via API.

Payload Structure:

{
  "id": "uuid",
  "workflow": "payout",
  "workflowExecutionId": "string",
  "workflowActionId": "uuid",
  "workspaceId": "uuid",
  "eventType": "executionActionRequested",
  "details": {
    "action": "string", // "lookup" or "payout"
    "actionId": "uuid",
    "request": {
      // Lookup request
      "amount": {
        "value": "number",
        "currency": "string"
      },
      "meta": {},
      // OR Payout request  
      "instrumentId": "uuid",
      "amount": {
        "value": "number",
        "currency": "string"
      },
    }
  },
  "createdAt": "ISO8601 timestamp",
  "eventTrigger": "api"
}

Example:

Lookup Action Requested:

{
  "id": "evt_456e7890-e89b-12d3-a456-426614174111",
  "workflow": "payout",
  "workflowExecutionId": "123e4567-e89b-12d3-a456-426614174000",
  "workflowActionId": "456e7890-e89b-12d3-a456-426614174111",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "executionActionRequested",
  "details": {
    "action": "lookup",
    "actionId": "456e7890-e89b-12d3-a456-426614174111",
    "request": {
      "amount": {
        "value": 5000,
        "currency": "EUR"
      },
      "meta": {
        "description": "Freelancer payment"
      },
    }
  },
  "createdAt": "2024-01-15T10:31:00.000Z",
  "eventTrigger": "api"
}

Payout Action Requested:

{
  "id": "evt_789e1234-e89b-12d3-a456-426614174222",
  "workflow": "payout",
  "workflowExecutionId": "123e4567-e89b-12d3-a456-426614174000",
  "workflowActionId": "789e1234-e89b-12d3-a456-426614174222",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "executionActionRequested",
  "details": {
    "action": "payout",
    "actionId": "789e1234-e89b-12d3-a456-426614174222", 
    "request": {
      "instrumentId": "333e4567-e89b-12d3-a456-426614174333",
      "amount": {
        "value": 5000,
        "currency": "EUR"
      }
    }
  },
  "createdAt": "2024-01-15T10:32:00.000Z",
  "eventTrigger": "api"
}
  1. Action Completed (executionActionCompleted)

Triggered when: A lookup or payout action is completed (successfully or with error).

Payload Structure:

{
  "id": "uuid",
  "workflow": "payout",
  "workflowExecutionId": "string",
  "workflowActionId": "uuid",
  "workspaceId": "uuid",
  "eventType": "executionActionCompleted",
  "details": {
    "action": "string", // "lookup" or "payout"
    "actionId": "uuid",
    "actionMeta": {},
    "success": "boolean",
    "errors": [
      {
        "code": "string",
        "message": "string", 
        "details": "string",
        "retryable": "boolean"
      }
    ],
    "execution": {
      "workflowCode": "payout",
      "id": "string",
      "merchantReference": "string",
      "holderReference": "string", 
      "holderId": "uuid",
      "meta": {},
      "requiredAction": {
        "type": "string",
        "links": {}
      }
    },
    "amount": {
      "value": "number",
      "currency": "string"
    },
    "completedAt": "ISO8601 timestamp"
  },
  "createdAt": "ISO8601 timestamp",
  "eventTrigger": "api"
}

Example:

Successful Lookup Completed:

{
  "id": "evt_456e7890-e89b-12d3-a456-426614174111",
  "workflow": "payout",
  "workflowExecutionId": "123e4567-e89b-12d3-a456-426614174000",
  "workflowActionId": "456e7890-e89b-12d3-a456-426614174111",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "executionActionCompleted",
  "details": {
    "action": "lookup",
    "actionId": "456e7890-e89b-12d3-a456-426614174111",
    "errors": [],
    "execution": {
      "workflowCode": "payout",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "merchantReference": "payout-12345",
      "holderReference": "[email protected]",
      "holderId": "999e8888-e89b-12d3-a456-426614174999",
      "meta": {
        "description": "Freelancer payment"
      }
    },
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "completedAt": "2024-01-15T10:31:00.000Z"
  },
  "createdAt": "2024-01-15T10:31:00.000Z",
  "eventTrigger": "api"
}

Failed Payout Completed:

{
  "id": "evt_789e1234-e89b-12d3-a456-426614174222",
  "workflow": "payout",
  "workflowExecutionId": "123e4567-e89b-12d3-a456-426614174000",
  "workflowActionId": "789e1234-e89b-12d3-a456-426614174222",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "executionActionCompleted",
  "details": {
    "action": "payout", 
    "actionId": "789e1234-e89b-12d3-a456-426614174222",
    "success": false,
    "errors": [
      {
        "code": "INSUFFICIENT_FUNDS",
        "message": "Insufficient funds in merchant account",
        "details": "Available balance: $25.00, Required: $50.00",
        "retryable": false
      }
    ],
    "execution": {
      "workflowCode": "payout",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "merchantReference": "payout-12345",
      "holderReference": "[email protected]",
      "holderId": "999e8888-e89b-12d3-a456-426614174999",
      "meta": {}
    },
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "completedAt": "2024-01-15T10:32:00.000Z"
  },
  "createdAt": "2024-01-15T10:32:00.000Z",
  "eventTrigger": "api"
}
  1. Action Updated (executionActionUpdated)

Triggered when: A payout status transition occurs (from external provider updates).

Payload Structure:

{
  "id": "uuid",
  "workflow": "payout",
  "workflowExecutionId": "string",
  "workflowActionId": "uuid",
  "workspaceId": "uuid",
  "eventType": "executionActionUpdated",
  "details": {
    "action": "transition",
    "actionId": "uuid", 
    "actionMeta": {},
    "success": "boolean",
    "errors": [
      {
        "code": "string",
        "message": "string",
        "details": "string", 
        "retryable": "boolean"
      }
    ],
    "execution": {
      "workflowCode": "payout",
      "id": "string",
      "merchantReference": "string",
      "holderReference": "string",
      "holderId": "uuid",
      "meta": {},
      "requiredAction": {
        "type": "string",
        "links": {}
      }
    },
    "amount": {
      "value": "number",
      "currency": "string"
    },
    "completedAt": "ISO8601 timestamp"
  },
  "createdAt": "ISO8601 timestamp",
  "eventTrigger": "api"
}

Examples: Successful Payout Transition (Paid):

{
  "id": "evt_abc12345-e89b-12d3-a456-426614174444",
  "workflow": "payout",
  "workflowExecutionId": "123e4567-e89b-12d3-a456-426614174000",
  "workflowActionId": "abc12345-e89b-12d3-a456-426614174444",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "executionActionUpdated",
  "details": {
    "action": "transition",
    "actionId": "abc12345-e89b-12d3-a456-426614174444",
    "errors": [],
    "execution": {
      "workflowCode": "payout", 
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "merchantReference": "payout-12345",
      "holderReference": "[email protected]",
      "holderId": "999e8888-e89b-12d3-a456-426614174999",
      "meta": {}
    },
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "completedAt": "2024-01-15T10:45:00.000Z"
  },
  "createdAt": "2024-01-15T10:45:00.000Z",
  "eventTrigger": "api"
}

Failed Payout Transition:

{
  "id": "evt_def67890-e89b-12d3-a456-426614174555",
  "workflow": "payout",
  "workflowExecutionId": "123e4567-e89b-12d3-a456-426614174000",
  "workflowActionId": "def67890-e89b-12d3-a456-426614174555",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "executionActionUpdated",
  "details": {
    "action": "transition",
    "actionId": "def67890-e89b-12d3-a456-426614174555", 
    "success": false,
    "errors": [
      {
        "code": "BANK_ACCOUNT_CLOSED",
        "message": "Destination bank account is closed",
        "details": "Account IBAN: DE89370400440532013000 has been closed by the bank",
        "retryable": false
      }
    ],
    "execution": {
      "workflowCode": "payout",
      "id": "123e4567-e89b-12d3-a456-426614174000", 
      "merchantReference": "payout-12345",
      "holderReference": "[email protected]",
      "holderId": "999e8888-e89b-12d3-a456-426614174999",
      "meta": {}
    },
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "completedAt": "2024-01-15T10:46:00.000Z"
  },
  "createdAt": "2024-01-15T10:46:00.000Z",
  "eventTrigger": "api"
}

Event Trigger Mechanisms

  1. API Triggers

    • Execution Creation: When POST /payout/executions is called
    • Lookup Request: When POST /payout/executions/{id}/lookup is called
    • Payout Request: When POST /payout/executions/{id}/payout is called
    • Transition Signal: When external payout status updates are received

  2. Action Triggers (WorkflowExecutionEventTriggerAction)

    • Initial Actions: When initial actions (like lookup) are executed during execution creation

  3. External Triggers (WorkflowExecutionEventTriggerExternal)

    • Provider Webhooks: When payment providers send status updates
    • External System Events: When external systems trigger workflow changes

Field Definitions

Common Fields

WorkflowExecutionEvent Structure

  • id: UUID identifying the specific event
  • workflow: Workflow type ("payout")
  • workflowExecutionId: String identifying the specific payout execution
  • workflowActionId: UUID identifying the specific action within an execution
  • workspaceId: UUID identifying the merchant workspace
  • eventType: Type of event ("executionCreated", "executionActionRequested", etc.)
  • details: Event-specific payload data
  • createdAt: Timestamp when the event was created
  • eventTrigger: How the event was triggered ("api", "action", "external")

Common Details Fields

  • merchantReference: Merchant-provided reference for the payout
  • holderReference: Reference to the recipient (email, user ID, etc.)
  • amount: Money object with value (in minor currency units) and currency code
  • meta: Free-form metadata object for additional context

Event-Specific Fields

ExecutionCreated Details

  • request: The original execution creation request
  • response: The execution creation response with generated IDs and links

ExecutionActionRequested Details

  • action: The type of action ("lookup", "payout")
  • actionId: UUID identifying the specific action

ExecutionActionCompleted/Updated Details

  • action: The type of action ("lookup", "payout", "transition")
  • actionId: UUID identifying the specific action
  • success: Boolean indicating if the action succeeded
  • errors: Array of error objects if action failed
  • execution: Current execution state information
  • amount: Amount associated with the action
  • completedAt: Timestamp when the action completed

Error Structure

{
  "code": "string",        // Error code (e.g., "INSUFFICIENT_FUNDS")
  "message": "string",     // Human-readable error message  
  "details": "string",     // Additional error details
  "retryable": "boolean"   // Whether the operation can be retried
}

Integration Guide

Listening to Events

Events are stored in the workflow execution events table and can be accessed via:

  1. Polling: Regular queries to fetch new events for executions
  2. Webhooks: Real-time notifications when events occur (if configured)
  3. Event Stream: Streaming interface for real-time event consumption

Event Processing Best Practices

  1. Idempotency: Process events idempotently using the event ID
  2. Ordering: Events are ordered by createdAt timestamp
  3. Filtering: Filter events by eventType, action, or trigger as needed
  4. Error Handling: Always check the success field and errors array
  5. Retries: Respect the retryable flag in error objects

Updated about 12 hours ago