GoCardless Embed
Reconciling payouts
In this step of the GoCardless Embed guide you will use GoCardless' webhooks and API to reconcile your payouts.
GoCardless will pay out payments to the payout bank account you added earlier in this guide. When this happens, a “payout” record will be created which represents the transfer of funds.
We will generally send a single payout each day for each currency you collect in. However, we may split the funds into multiple payouts if there are a very large number of payments to pay out.
When a payout is sent, you will receive a webhook with resource_type “payouts” and action “paid”. In addition, for each payment that has been paid out, we will 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 detailed reconciliation, 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 payments and add the money collected to their GoCardless balance - that’s a credit. But there can also be debits against that balance - for example deductions for chargebacks.
When we make a payout, we bundle up all of the outstanding credits and debits into it and reset the creditor’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 currency the payment was taken in.a
type(which explains the reason for the credit or debit) andlinksto any relevant resources (usually a payment,links.payment).
The types of payout items in the GoCardless Embed product are:
Type | Description | Credit or debit | Links |
|---|---|---|---|
Payment paid out ( | A payment was successfully collected from a payer and is being passed on to your payout account. | Credit |
|
Payment failed ( | A payment appeared to have been collected from a payer 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 payer, but then the payer contacted their bank to reverse the transaction, so it is being deducted | Debit |
|
Payment refunded ( | A payment was successfully collected from a payer, and then partially or fully refunded at your request, so the refunded amount is being deducted | Debit |
|
Payer refunded ( | A refund was sent to a payer, 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 payer, so the refunded amount is being credited. | Credit |
|
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 |
Refund issued for Andrew's payment, collected last week |
| -€5.00 |
Bianca's payment from last week, which was charged back |
| -€10.00 |
Total | +€5.00 |
With the Payout Items API, you can look inside a payout and see the transactions that make it up, allowing you to explain transactions on the payer’s bank statement.
When you receive a “payout paid” webhook (resource_type “payouts” and action “paid”), you can then query the Payout Items API:
1require 'vendor/autoload.php';
2
3function processPayoutEvent($event) {
4 $client = new \GoCardlessPro\Client([
5 'access_token' => $_ENV["GOCARDLESS_ACCESS_TOKEN"],
6 'environment' => \GoCardlessPro\Environment::SANDBOX
7 ]);
8
9 $payoutId = $event->links['payout'];
10
11 $payout = $client->payouts()->get($payoutId);
12 echo $payout->amount;
13
14 $payoutItems = $client
15 ->payoutItems()
16 ->all(["params" => ["payout" => $payoutId]]);
17
18 foreach ($payoutItems as $payoutItem) {
19 echo $payoutItem->amount;
20 echo $payoutItem->type;
21 echo $payoutItem->links->payment;
22 }
23}For full details on the Payout Items API, head over to our reference documentation.
What's Next?
Your integration is complete. Please contact us to help you take your integration live.