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.
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.
We'll only make a payout when a merchant's balance is positive. Imagine that a merchant's balance
is zero, and they make a refund of £5.00. Their balance is now -£5.00. They then collect
payment of £10.00. Their balance is +£5.00, so we'll send them a payout, which will bundle up
the refund and the successful payment into its Payout Items.
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) and links to 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 (payment_paid_out)
A payment was successfully collected from a payer and is being passed on to your payout account.
Credit
links.payment
Payment failed (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
links.payment
Payment charged back (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
links.payment
Payment refunded (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
links.payment, links.mandate
Payer refunded (refund)
A refund was sent to a payer, not related to any particular payment, so the refunded amount is being deducted.
Debit
links.mandate
Refund funds returned (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
links.payment, links.mandate
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
payment_paid_out
+€20.00
Refund issued for Andrew's payment, collected last week
payment_refunded
-€5.00
Bianca's payment from last week, which was charged back
payment_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: