# Managing Payments Source: https://docs.gocardless.com/docs/collect-payments/managing-payments/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. > **Warning:** > **Verification Required** It's worth noting that we will only start sending payouts once your user > has verified their account - we'll send them emails reminding them to do this, but you might want > to flag this in your UI, especially when they first connect their account, and perhaps afterwards > until they receive their first payout. We've made a suggestion about communicating this to your > users in our ["User experience" guide](/docs/partner-integrations/getting-your-users-verified). 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"](/docs/getting-started/stay-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](/docs/api-reference/payout-item#get-all-payout-items-in-a-single-payout). ### 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. > **Info:** > 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 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 (`payment_paid_out`) | A payment was successfully collected from a customer and is being passed on to your user | Credit | `links.payment` | | Payment failed (`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 | `links.payment` | | Payment charged back (`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 | `links.payment` | | Payment refunded (`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 | `links.payment` , `links.mandate` | | GoCardless fee (`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 | `links.payment` | | App fee (`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 | `links.payment` | | Revenue share (`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 `gocardless_fee`, but they will appear in partner payouts when they receive the commission. | Credit/Debit | `links.payment` | | Customer refunded (`refund`) | A refund was sent to a customer, 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 customer, so the refunded amount is being credited. | Credit | `links.payment` , `links.mandate` | | Surcharge fee (`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 | `links.payment` | 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 | | App fee for payment collected from Nick | `gocardless_fee` | -€0.20 | | App fee for payment collected from Nick | `app_fee` | -€1.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 | | Refund of GoCardless fee for charged back payment | `gocardless_fee` | +€0.10 | | Refund of app fee for charged back payment | `app_fee` | +€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: ```php \$event->links['organisation']])->firstOrFail(); \$client = new \\GoCardlessPro\\Client([ 'access_token' => \$user->gocardless_access_token, 'environment' => \\GoCardlessPro\\Environment::SANDBOX ]); \$payout_id = \$event->links['payout']; \$payout = \$client->payouts()->get(\$payout_id); echo \$payout->amount; \$payout_items = \$client ->payoutItems() ->all(["params" => ["payout" => \$payout_id]]); foreach (\$payout_items as \$payout_item) \ ``` ```python import os from myinvoicingapp.models import User #... def process_payout_event(self, event): user = User.object.get(gocardless_organisation_id=event['links']['organisation']) client = gocardless_pro.Client( access_token=user.gocardless_access_token, environment='sandbox' ) payout_id = event['links']['payout'] payout = client.payouts.get(payout_id) print payout.amount payout_items = client.payout_items.all( params=\ ).records for payout_item in payout_items: print payout_item.amount print payout_item.type print payout_item.links.payment ``` ```ruby require 'gocardless_pro' def process_payment_paid_out(event) user = User.find_by(gocardless_organisation_id: event.links.organisation) client = GoCardlessPro::Client.new( access_token: user.gocardless_access_token, environment: :sandbox ) payout_id = event.links.payout payout = client.payouts.find(payout_id) puts payout.amount client.payout_items.all(params: \).each do |payout_item| puts payout_item.amount puts payout_item.type puts payout_item.links.payment end end ``` ```java package com.myInvoicingApp; public class PayoutsWebhookHandler \ \} \} ``` ```javascript const handlePayoutPaidEvent = async (eventResource) => \; for await (let payoutItem of client.payoutItems.all(payoutItemsRequest)) \ \}; ``` ```c# public void HandlePayoutPaidEvent(GoCardless.Resources.Event eventResource) \; var payoutItems = client.PayoutItems.All(payoutItemsRequest); foreach (GoCardless.Resources.PayoutItem payoutItem in payoutItems) \ \} ``` ```go package main "context" "fmt" "http" gocardless "github.com/gocardless/gocardless-pro-go/v6" ) func main() \ client, err := gocardless.New(config) if err != nil \ parseEvent := func(event gocardless.Event) \ payoutItems, err := client.PayoutItems().All(ctx, payoutListParams) for _, payoutItem := range payoutItems \ \} http.HandleFunc("/webhookEndpoint", func(w http.ResponseWriter, r *http.Request) \)) wh.ServeHTTP(w, r) \}) \} ``` For full details on the Payout Items API, head over to our [reference documentation](/docs/api-reference/payout-item). > **Info:** > **VAT Notice** GoCardless has been instructed by the relevant authorities to start charging VAT on > its fees. For more details and recommendations, head over to our > [guidelines](/docs/tutorials/handling-tax) ### Reconciling Payouts with Events When a payout is created not only does it have an event created for it, but all payments and refunds within that payout have events created for them too. If you know the payout's ID, you can fetch all of these events using two API requests. The first step is to find the "paid" event for the Payout you're interested in. You can do this by filtering events based on the ID of the payout and the action, which is "paid": ```http GET https://api.gocardless.com/events?payout=PY123&action=paid ``` To find child events for a payout, filter for events with a `parent_event` equal to the Payout's paid event: ```http GET https://api.gocardless.com/events?parent_event=EV123 ``` This will return a paginated list of all child events for payments and refunds associated with the payout. If you'd also like to return the associated payments or refunds, you can scope the request to a resource_type and include those resources: ```http GET https://api.gocardless.com/events?parent_event=EV123&resource_type=payments&include=payment GET https://api.gocardless.com/events?parent_event=EV123&resource_type=refunds&include=refund ``` ## What's next? #### [Payout Items API Reference](/docs/api-reference/payout-item) Full reference for the Payout Items API, including all item types. #### [FX Payments](/docs/collect-payments/managing-payments/fx) Reconcile payouts where payments were collected in a foreign currency. #### [Handling Tax](/docs/tutorials/handling-tax) GoCardless VAT guidance and recommendations for your integration. #### [Webhooks Overview](/docs/getting-started/stay-up-to-date-with-webhooks) Configure a webhook endpoint to receive payout and payment events in real time.