How to automate payouts via API
This article explains how to automate payouts using Kiflo API. Please read first this article to understand What is the payout process?
Target audience
This article is written for developers.
Automating payouts is a four steps process:
- Create payouts: Create payouts at regular intervals (ex: every month, or every quarter) for all partners with pending rewards
- Validate payouts: Change statuses from Pending to Validate to make payouts visible to partners. Optionally ask them to also validate payouts and upload invoices.
- Send payments: Export payouts from Kiflo to send payments manually or via your bank API.
- Mark payouts as paid: Change statuses from Accepted to Paid to let partners know they will receive the funds soon.
Create payouts
Endpoint: https://docs-api.kiflo.com/#8581c78d-b6de-4095-a0fb-332510e35bae
The first step is to create payouts for all partners with pending rewards. Payouts are created with the status Draft by default and are not visible to partners.
Frequency
You must define the frequency at which you need to create payouts. It can be every month, every quarter, or even every time a reward is generated.
Parameters
When creating payouts you must set the following parameters:
| Parameter | Description | Optional | Example |
|---|---|---|---|
| partnerIds | List of partner IDs for whom you want to create payouts. Don't set this parameter if you want to create payouts for ALL partners. In any case, payouts are not created for partners without pending rewards. | Yes | [42] |
| currency | The currency of rewards that must be included in payouts. If set, only rewards in that currency are included in payouts. Don't set it to create payouts for all currencies. | Yes | EUR |
| rewardType | The type of rewards that must be included in payouts. If set, only rewards with this type are included in payouts. Don't set it to create payouts for all types of rewards. | Yes | Cash |
| rewardStatus | The status of rewards that must be included in payouts. If set, only rewards with this status are included in payouts. Don't set it to create payouts for all Pending and Accepted rewards. In any case, rewards already Paid or Rejected are NOT included in payouts. | Yes | Accepted |
| fromDate | Only include rewards generated after this date (ISO 8601). | Yes | 2024-01-01T00:00:00Z |
| toDate | Only include rewards generated before this date (ISO 8601) | Yes | 2024-02-01T00:00:00Z |
| threshold | The amount of pending rewards per partner that must be reached to generate the payout for that partner. | Yes | 1500 |
| properties | Additional list of JSON property to be included in ALL payouts. | Yes |
Important notice
The upper parameters are used to select rewards to be included in payouts. In case there is no reward matching these criteria for one partner, no payout is created for this partner.
Examples
Create payouts for all partners for January 2024 (timezone: UTC+1):
{
"fromDate": "2023-12-31T23:00:00Z",
"toDate": "2024-01-31T23:00:00Z"
}
Create payouts for a specific partner for all rewards waiting to be paid:
{
"partnerIds": [42]
}
Create payouts for Q1 2024 for all partners who must be paid in Euro (timezone: UTC+1):
{
"currency": "EUR",
"fromDate": "2023-12-31T23:00:00Z",
"toDate": "2024-03-31T23:00:00Z"
}
Validate payouts
Endpoint: https://docs-api.kiflo.com/#960f506c-d759-493e-b366-84d8f9863a5b
Draft payouts must be validated to be visible to partners. Optionally you can ask partners to upload invoices or review rewards including in payouts.
Payouts must be validated one by one.
Parameters
When creating payouts you must set the following parameters:
| Parameter | Description | Optional |
|---|---|---|
| shouldValidateRewards | Determine whether the partner must validate rewards in the new payout. If True, the payout status goes from Draft to Pending. | Yes |
| shouldAttachInvoice | Determine whether the partner must validate rewards in the new payout. If True, the payout status goes from Draft to Pending. | Yes |
If both parameters are False, the payout status goes from Draft to Ready and is ready to be paid.
Examples
Validate one payout and ask the partner to upload an invoice:
{
"shouldValidateRewards": true,
"shouldAttachInvoice": true
}
Validate one payout, without requiring any additional actions from the partner:
{
"shouldValidateRewards": false,
"shouldAttachInvoice": false
}
Send payments
All payouts with the status Ready are ready to be paid. They are Ready when either:
- They have been validated in the previous step without asking for additional actions from partners; OR
- Partners have accepted the payouts after uploading the invoices or reviewing the rewards
You cannot send payments from Kiflo directly. You must export payouts using the list payouts endpoint: https://docs-api.kiflo.com/#1f0165a1-0287-4d9d-a0d2-0ef5f9469cd8
And filter returned payouts by status, date, or partner, depending on which payouts you want to pay.
Then, connect to your bank or payment platform and trigger payments according to their instructions.
Mark payouts as paid
Endpoint: https://docs-api.kiflo.com/#2f51f111-8706-4e93-8cf9-074a3d8d891d
When payments are sent, payouts must be marked as paid. Manually change their status from Ready to Paid and partners are notified using the referenced endpoint.
Payouts must be marked as paid one by one.