Payout Item

View as Markdown

When we collect a payment on your behalf, we add the money you've collected to your GoCardless balance, minus any fees paid. Periodically (usually every working day), we take any positive balance in your GoCardless account, and pay it out to your nominated bank account.

Other actions in your GoCardless account can also affect your balance. For example, if a customer charges back a payment, we'll deduct the payment's amount from your balance, but add any fees you paid for that payment back to your balance.

The Payout Items API allows you to view, on a per-payout basis, the credit and debit items that make up that payout's amount. Payout items can only be retrieved for payouts created in the last 6 months. Requests for older payouts will return an HTTP status 410 Gone.

Get all payout items in a single payout#

GET/payout_items

Returns a cursor-paginated list of items in the payout.

This endpoint only serves requests for payouts created in the last 6 months. Requests for older payouts will return an HTTP status 410 Gone.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/payout_items?payout=PO123 HTTP/1.1

@client.payout_items.list(params: {payout: "PO123"})

client.payout_items.list(params={'payout': 'PO123'})

const payoutItems = await client.payoutItems.list({ payout: "P0123" });

// List the first three payout items for a payout
const limitedPayoutItems = await client.payoutItems.list({ payout: "P0123", limit: "3" });

$client->payoutItems()->list([
  'params' => ['payout' => 'PO123']
]);

client.payoutItems().all().withPayout("PO123").execute();

payoutItemsListParams := gocardless.PayoutItemListParams{
  Payout: "PO123",
}

payoutItemsListResult, err := client.PayoutItems.List(ctx, payoutItemsListParams)
for _, payoutItem := range payoutItemsListResult.PayoutItems {
    fmt.Println(payoutItem.Amount)
}

var itemsRequest = new GoCardless.Services.PayoutItemListRequest()
{
    Payout = "PO123"
};

var response = client.PayoutItems.All(itemsRequest);
foreach (GoCardless.Resources.PayoutItem item in response)
{
    Console.WriteLine(item.Amount);
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "payout_items": [
    {
      "amount": "4.0",
      "type": "gocardless_fee",
      "taxes": [{
        "amount": "1.0",
        "currency": "GBP",
        "destination_amount": "1.1",
        "destination_currency": "EUR",
        "exchange_rate": "1.11205",
        "tax_rate_id": "FR_VAT_1"
      }],
      "links": {
        "payment": "PM456"
      }
    },
    {
      "amount": "1000.0",
      "type": "payment_paid_out",
      "taxes": [],
      "links": {
        "payment": "PM123"
      }
    },
    {
      "amount": "-24.0",
      "type": "gocardless_fee",
      "taxes": [{
        "amount": "4.0",
        "currency": "EUR",
        "destination_amount": "4.0",
        "destination_currency": "EUR",
        "exchange_rate": null,
        "tax_rate_id": "FR_VAT_1"
      }],
      "links": {
        "payment": "PM123"
      }
    },
    {
      "amount": "30.0",
      "type": "payment_paid_out",
      "taxes": [],
      "links": {
        "payment": "PM456"
      }
    },
    {
      "amount": "-500.0",
      "type": "payment_refunded",
      "taxes": [],
      "links": {
        "payment": "PM789"
      }
    },
    {
      "amount": "4.0",
      "type": "gocardless_fee",
      "taxes": [{
        "amount": "1.0",
        "currency": "GBP",
        "destination_amount": "1.1",
        "destination_currency": "EUR",
        "exchange_rate": "1.11205",
        "tax_rate_id": "FR_VAT_1"
      }],
      "links": {
        "payment": "PM456"
      }
    },
    {
      "amount": "-1.0",
      "type": "app_fee",
      "taxes": [],
      "links": {
        "payment": "PM456"
      }
    }
  ],
  "meta": {
    "cursors": { "before": null, "after": null },
    "limit": 50
  }
}

GET https://api.gocardless.com/payout_items?payout=PO456 HTTP/1.1

HTTP/1.1 410 Gone
Content-Type: application/json
{
    "error": {
      "documentation_url": "https://developer.gocardless.com/api-reference#payout_items_data_archived",
      "message": "Payout items for payouts created more than 6 months ago are archived. Please contact support if you require access to this data.",
      "type": "invalid_api_usage",
      "errors": [
        {
          "reason": "payout_items_data_archived",
          "message": "Payout items for payouts created more than 6 months ago are archived. Please contact support if you require access to this data."
        }
      ],
      "code": 410,
      "request_id": "deadbeef-0000-4000-0000-444400004444"
    }
}

Response 200

Successful response

payout_itemsarray

4 properties

amountstring

The positive (credit) or negative (debit) value of the item, in fractional currency; the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place.

For accuracy, we store some of our fees to greater precision than we can actually pay out (for example, a GoCardless fee we record might come to 0.5 pence, but it is not possible to send a payout via bank transfer including a half penny).

To calculate the final amount of the payout, we sum all of the items and then round to the nearest currency unit.

typestring

The type of the credit (positive) or debit (negative) item in the payout (inclusive of VAT if applicable). One of:

payment_paid_out (credit)
payment_failed (debit): The payment failed to be processed.
payment_charged_back (debit): The payment has been charged back.
payment_refunded (debit): The payment has been refunded to the customer.
refund (debit): A refund sent to a customer, not linked to a payment.
refund_funds_returned (credit): The refund could not be sent to the customer, and the funds have been returned to you.
gocardless_fee (credit/debit): The fees that GoCardless charged for a payment. In the case of a payment failure or chargeback, these will appear as credits. Will include taxes if applicable for merchants.
app_fee (credit/debit): The optional fees that a partner may have taken for a payment. In the case of a payment failure or chargeback, these will appear as credits.
revenue_share (credit/debit): A share of the fees that GoCardless collected which some partner integrations receive when their users take payments. Only shown in partner payouts. In the case of a payment failure or chargeback, these will appear as credits.
surcharge_fee (credit/debit): 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. Will include taxes if applicable for merchants.

payment_paid_outpayment_failedpayment_charged_backpayment_refundedrefundgocardless_feeapp_feerevenue_sharesurcharge_feerefund_funds_returned

taxesarray

An array of tax items beta

Note: VAT applies to transaction and surcharge fees for merchants operating in the UK and France.

6 properties

amountstring

The amount of tax applied to a fee in fractional currency; the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD

destination_amountstring

The amount of tax to be paid out to the tax authorities in fractional currency; the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place.

When currency and destination_currency don't match this will be null until the exchange_rate has been finalised.

destination_currencystring

ISO 4217 code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR” for French merchants and “GBP” for British merchants.

exchange_ratestring

The exchange rate for the tax from the currency into the destination currency.

Present only if the currency and the destination currency don't match and the exchange rate has been finalised.

You can listen for the payout's tax_exchange_rates_confirmed webhook to know when the exchange rate has been finalised for all fees in the payout.

tax_rate_idstring

The unique identifier created by the jurisdiction, tax type and version

linksobject

3 properties

paymentstring

Unique identifier, beginning with "PM".

mandateobject

refundobject

metaobject

2 properties

limitinteger

cursorsobject

2 properties

beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject