Set Up Your Payout Workflow

This guide walks you through the steps required to configure the payout workflow for your merchant account.

Prerequisites

In order to start making payouts, below are the steps to cover. In the next section, we will explain how to set up each step.

  • Access to the Integrations page in your Payrails Portal,
  • Valid API credentials from the providers you want to do the payout with, with the appropriate permissions,
  • A configured payout provider.

Setup Steps

Step 1: Configure your payout provider

In this step, you will configure the provider in Payrails system, so that we can make requests to the providers on behalf of your account.

Navigate to the Integrations page in Payrails Portal and set up your payout configuration. The page will navigate you to provide the necessary fields depending on which provider you choose to work with. Note that currently only bank account payout methods are supported.

Once you configured your provider, you will be provided a providerConfigId which will be used in next step.

Step 2: Create a payout workflow configuration

In order to process a payout request, you need to create a payout workflow configuration. You will use the Create workflow configuration API with the workflowCode : payout. Below is a prepared payload of how you can configure your payout workflow. The providerID is the value you will obtain once you configure the provider in Step 1.

{
  "lookup": {
    "payoutMethodOptions": {
      "resolvedRulesets": [
        {
          "trigger": {
            "on": "determinePayoutMethodOptions",
            "filter": {
              "payoutMethodType": "bankAccount"
            }
          },
          "defaultAction": {
            "type": "setPriority",
            "params": {
              "priority": 1
            }
          }
        }
      ]
    }
  },
  "payout": {
    "providerOptions": {
      "resolvedRulesets": [
        {
          "trigger": {
            "on": "determineProviderOptions",
            "filter": {
              "providerConfigId": "138af103-0bf4-4cf7-a855-4c624c27f892"
            }
          },
          "defaultAction": {
            "type": "setPriority",
            "params": {
              "priority": 1
            }
          }
        }
      ]
    }
  }
}

Once you have completed this step, you will receive workflowVersion, which you will use in the next step.

Step 3: Set your workflow version as Default Payout Workflow

Our workflows have a versioning feature so that you can work in parallel on as many versions as you need, without touching the default version, which is live.

Once you create your configuration version in previous step, you will have to set it as default, so that the configuration of this version will be executed when you are creating a payout request.

You will use Update the default workflow configuration API, with workflowCode: payout, and with the workflowVersionthat you have received in the previous step. Below is a prepared payload of how you can set your workflow configuration version as your default payout workflow:

{
  "version": "1",
  "workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a"
}

Important: Replace the following placeholders:

  • workflowVersion with the version number returned from Step 2
  • baseUrl with your API base URL
  • Update the workspaceId with your actual workspace ID

Parameters Reference

ParameterDescriptionRequired
x-idempotency-keyUnique identifier to prevent duplicate requestsYes
providerConfigIdID of your configured payout providerYes
workflowVersionVersion number of the created workflowYes
workspaceIdYour merchant workspace identifierYes

Next Steps

Once completed, your payout workflow will be active and ready to process bank account payouts according to the configured rules and priorities. In order to make payout, you will make API calls to create workflow executions.