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 workflowVersion
that 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 2baseUrl
with your API base URL- Update the
workspaceId
with your actual workspace ID
Parameters Reference
Parameter | Description | Required |
---|---|---|
x-idempotency-key | Unique identifier to prevent duplicate requests | Yes |
providerConfigId | ID of your configured payout provider | Yes |
workflowVersion | Version number of the created workflow | Yes |
workspaceId | Your merchant workspace identifier | Yes |
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.
Updated about 12 hours ago