Payouts: Reconciling Payouts
Reconciling payouts
Periodically (usually once every working day), we’ll pay out payments your user has collected to their nominated bank account. When this happens, a “payout” record will be created which represents the transfer of funds.
We’ll generally send a single payout each day for each currency a user collects in. However, we may split the funds into multiple payouts if there are a very large number of payments to payout.
A payout will not necessarily only contain payments collected through your integration - it may contain others if your user is also using our API, the Dashboard or another integration.
When a payout is sent to your user, you’ll receive a webhook with resource_type “payouts” and action “paid”. In addition, for each payment that has been paid out, we’ll send webhooks with resource_type “payments” and action “paid_out”. The links[payout] attribute of that webhook will include the ID of the payout the payment appears in.
For more details on handling webhooks, see the “Staying up-to-date with webhooks” section earlier in this guide.
For the majority of integrations, that’ll be enough. But some integrations (for example, accountancy software) will want to go further in understanding exactly what makes up a payout. If you want to do more complex reconciliation (for example to build a business’s accounts), the best way to understand what’s inside a payout is to use the Payout Items API.
Using the Payout Items API
The Payout Items API lets you see the individual transactions that made up the total amount of a payout.
You can think of a payout in terms of credits and debits. When we collect payment on your user’s behalf, we add the money collected to their GoCardless balance - that’s a credit. But there can also be debits against that balance - for example, GoCardless’ fees, app fees that you charge for using your integration or deductions for chargebacks.
When we make a payout, we bundle up all of the outstanding credits and debits into it and reset the user’s balance to zero.
For each item in a payout, we expose an amount (which will be positive for credit, or negative for a debit) and will be in the customer's currency (i.e the currency the payment was taken in), a type (which explains the reason for the credit or debit) and links to any relevant resources (usually a payment, links.payment).
There are ten types of payout items:
Type | Description | Credit or debit | Links |
|---|---|---|---|
Payment paid out ( | A payment was successfully collected from a customer and is being passed on to your user | Credit |
|
Payment failed ( | A payment appeared to have been collected from a customer successfully, but then the bank told us that it had in fact failed, so it is being deducted | Debit |
|
Payment charged back ( | A payment was successfully collected from a customer, but then the customer contacted their bank to reverse the transaction, so it is being deducted | Debit |
|
Payment refunded ( | A payment was successfully collected from a customer, and then partially or fully refunded at your user's request, so the refunded amount is being deducted | Debit |
,
|
GoCardless fee ( | GoCardless deducted its transaction fee from an incoming payment or refunded its transaction fee when payment failed or was charged back | Credit/Debit |
|
App fee ( | Partner integrations can add an "app fee" on top of GoCardless's fees. GoCardless deducted such a fee from an incoming payment or refunded it when payment failed or was charged back | Credit/Debit |
|
Revenue share ( | GoCardless paid out a commission to a partner for a successful payment or deducted it for a late failure or chargeback. Partner integrations can receive a share of GoCardless' fees when users collect payments through their integration. These do not appear in merchant payouts, since they are part of the | Credit/Debit |
|
Customer refunded ( | A refund was sent to a customer, not related to any particular payment, so the refunded amount is being deducted. | Debit |
|
Refund Funds returned ( | A refund made at your request, and previously deducted from a payout failed to reach the customer, so the refunded amount is being credited. | Credit |
,
|
Surcharge fee ( | GoCardless deducted a surcharge fee as the payment failed or was charged back, or refunded a surcharge fee as the bank or customer cancelled the chargeback. | Credit/Debit |
|
To see how these can fit together in the real world, let’s imagine a payout as an example:
Description | Type | Amount |
|---|---|---|
Payment successfully collected from Nick |
| +€20.00 |
App fee for payment collected from Nick |
| -€0.20 |
App fee for payment collected from Nick |
| -€1.00 |
Refund issued for Andrew's payment, collected last week |
| -€5.00 |
Bianca's payment from last week, which was charged back |
| -€10.00 |
Refund of GoCardless fee for charged back payment |
| +€0.10 |
Refund of app fee for charged back payment |
| +€0.50 |
Total | +€4.40 |
With the Payout Items API, you can look inside a payout and see the transactions that make it up, allowing you to, for example, “explain” transactions on your user’s bank statement.
When you receive a “payout paid” webhook (resource_type “payouts” and action “paid”), you can then query the Payout Items API:
1<?php
2require 'vendor/autoload.php';
3
4$user = User::where(['gocardless_organisation_id' => $event->links['organisation']])->firstOrFail();
5
6$client = new \GoCardlessPro\Client([
7 'access_token' => $user->gocardless_access_token,
8 'environment' => \GoCardlessPro\Environment::SANDBOX
9]);
10
11$payout_id = $event->links['payout'];
12
13$payout = $client->payouts()->get($payout_id);
14echo $payout->amount;
15
16$payout_items = $client
17 ->payoutItems()
18 ->all(["params" => ["payout" => $payout_id]]);
19
20foreach ($payout_items as $payout_item) {
21 echo $payout_item->amount;
22 echo $payout_item->type;
23 echo $payout_item->links->payment;
24}For full details on the Payout Items API, head over to our reference documentation.