Payout

View as Markdown

Payouts represent transfers from GoCardless to a creditor. Each payout contains the funds collected from one or many payments. All the payments in a payout will have been collected in the same currency. Payouts are created automatically after a payment has been successfully collected.

List payouts#

GET/payouts

Returns a cursor-paginated list of your payouts.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/payouts HTTP/1.1

@client.payouts.list

@client.payouts.list(params: { creditor_bank_account: "BA123" })

@client.payouts.list.records.each { |payout| puts payout.inspect }

client.payouts.list().records

client.payouts.list(params={"status": "pending"}).records

const payouts = await client.payouts.list();

// List all payouts with a given status.
await client.payouts.list({ status: "pending" });

$client->payouts()->list();

$client->payouts()->list([
  "params" => ["creditor" => "CR123"]
]);

import com.gocardless.services.PayoutService.PayoutListRequest.Status;

for (Payout payout : client.payouts().all().withStatus(Status.PENDING).execute()) {
  System.out.println(payout.getId());
}

payoutListParams := gocardless.PayoutListParams{}
payoutListResult, err := client.Payouts.List(ctx, payoutListParams)
for _, payout := range payoutListResult.Payouts {
    fmt.Println(payout.Amount)
}

var payoutRequest = new GoCardless.Services.PayoutListRequest()
{
    Currency = GoCardless.Services.PayoutListRequest.PayoutCurrency.EUR,
};

var payoutListResponse = client.Payouts.All(payoutRequest);
foreach (GoCardless.Resources.Payout payout in payoutListResponse)
{
    Console.WriteLine(payout.Amount);
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "payouts": [{
    "id": "PO123",
    "amount": 1000,
    "arrival_date": "2014-06-27",
    "deducted_fees": 10,
    "currency": "GBP",
    "created_at": "2014-06-20T13:23:34.000Z",
    "payout_type": "merchant",
    "reference": "ref-1",
    "status": "pending",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.11667"
    },
    "tax_currency": "GBP",
    "metadata":{ "key": "value" },
    "links": {
      "creditor_bank_account": "BA123",
      "creditor": "CR123"
    }
  }],
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 50
  }
}

Response 200

Successful response

payoutsarray

13 properties

idstring

Unique identifier, beginning with "PO".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount in minor unit (e.g. pence in GBP, cents in EUR).

deducted_feesobject

Fees that have already been deducted from the payout amount in minor unit (e.g. pence in GBP, cents in EUR), inclusive of tax if applicable.
For each late_failure_settled or chargeback_settled action, we refund the transaction fees in a payout. This means that a payout can have a negative deducted_fees value.
This field is calculated as (GoCardless fees + app fees + surcharge fees) - (refunded fees)
If the merchant is invoiced for fees separately from the payout, then deducted_fees will be 0.

currencystring

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

AUDCADDKKEURGBPNZDSEKUSD

referencestring

Reference which appears on the creditor's bank statement.

statusstring

One of:

pending: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider.
paid: the payout has been sent to the your bank. FX payouts will become paid after we emit the fx_rate_confirmed webhook.
bounced: the payout bounced when sent, the payout can be retried.

pendingpaidbounced

payout_typestring

Whether a payout contains merchant revenue or partner fees.

merchantpartner

arrival_datestring

Date the payout is due to arrive in the creditor's bank account. One of:

yyyy-mm-dd: the payout has been paid and is due to arrive in the creditor's bank account on this day
null: the payout hasn't been paid yet

linksobject

2 properties

creditorstring

ID of creditor who will receive this payout, i.e. the owner of the creditor_bank_account.

creditor_bank_accountstring

ID of bank account which this will be sent to.

fxobject

4 properties

exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

AUDCADDKKEURGBPNZDSEKUSD

tax_currencystring

ISO 4217 code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR”, “GBP”, for French or British merchants, this will be null if tax is not applicable beta

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. Note: This should not be used for storing PII data.

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

Get a single payout#

GET/payouts/{payout_id}

Retrieves the details of a single payout. For an example of how to reconcile the transactions in a payout, see this guide.

Path Parameters

Name	Type	Description
`payout_id`required	string	The payout id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/payouts/PO123 HTTP/1.1

@client.payouts.get("PO123")

client.payouts.get("PO123")

const payout = await client.payouts.find("PO123");

$client->payouts()->get("PO123");

client.payouts().get("PO123").execute();

payout, err := client.Payouts.Get(ctx, "PO123")

var payoutResponse = await client.Payouts.GetAsync("PO0123");
GoCardless.Resources.Payout payout = payoutResponse.Payout;

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "payouts": {
    "id": "PO123",
    "amount": 1000,
    "arrival_date": "2014-06-27",
    "deducted_fees": 10,
    "currency": "GBP",
    "created_at": "2014-06-20T13:23:34.000Z",
    "payout_type": "merchant",
    "reference": "ref-1",
    "status": "pending",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.11667"
    },
    "tax_currency": "GBP",
    "metadata":{ "key": "value" },
    "links": {
      "creditor_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Response 200

Successful response

payoutsobject

13 properties

idstring

Unique identifier, beginning with "PO".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount in minor unit (e.g. pence in GBP, cents in EUR).

deducted_feesobject

currencystring

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

AUDCADDKKEURGBPNZDSEKUSD

referencestring

Reference which appears on the creditor's bank statement.

statusstring

One of:

pending: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider.
paid: the payout has been sent to the your bank. FX payouts will become paid after we emit the fx_rate_confirmed webhook.
bounced: the payout bounced when sent, the payout can be retried.

pendingpaidbounced

payout_typestring

Whether a payout contains merchant revenue or partner fees.

merchantpartner

arrival_datestring

Date the payout is due to arrive in the creditor's bank account. One of:

yyyy-mm-dd: the payout has been paid and is due to arrive in the creditor's bank account on this day
null: the payout hasn't been paid yet

linksobject

2 properties

creditorstring

ID of creditor who will receive this payout, i.e. the owner of the creditor_bank_account.

creditor_bank_accountstring

ID of bank account which this will be sent to.

fxobject

4 properties

exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

AUDCADDKKEURGBPNZDSEKUSD

tax_currencystring

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. Note: This should not be used for storing PII data.

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

Update a payout#

PUT/payouts/{payout_id}

Updates a payout object. This accepts only the metadata parameter.

Path Parameters

Name	Type	Description
`payout_id`required	string	The payout id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

PUT https://api.gocardless.com/payouts/PO123 HTTP/1.1
Content-Type: application/json
{
  "payouts": {
    "metadata": {
      "key": "value"
    }
  }
}

@client.payouts.update(
  "PO123",
  params: {
    metadata: { key: "value" }
  }
)

client.payouts.update("PO123", params={
  "metadata": {"key": "value"}
})

const payout = await client.payouts.update(
  "PO123",
  {
    metadata: {
      key: "value"
    }
  }
);

$client->payouts()->update("PO123", [
  "params" => ["metadata" => ["key" => "value"]]
]);

client.payouts().update("PO123")
  .withMetadata("key", "value")
  .execute();

payoutUpdateParams := gocardless.PayoutUpdateParams{
  Metadata: map[string]string{"key": "value"},
}

payout, err := client.Payouts.Update(ctx, "PO123", payoutUpdateParams)

var payoutRequest = new GoCardless.Services.PayoutUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"key", "value"}
    }
};

var payoutResponse = await client.Payouts.UpdateAsync("PO123", payoutRequest);

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "payouts": {
    "id": "PO123",
    "amount": 1000,
    "arrival_date": "2014-06-27",
    "deducted_fees": 10,
    "currency": "GBP",
    "created_at": "2014-06-20T13:23:34.000Z",
    "payout_type": "merchant",
    "reference": "ref-1",
    "status": "pending",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.11667"
    },
    "tax_currency": "GBP",
    "metadata":{"key":"value"},
    "links": {
      "creditor_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Request Body

payoutsobject

1 properties

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Response 200

Successful response

payoutsobject

13 properties

idstring

Unique identifier, beginning with "PO".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount in minor unit (e.g. pence in GBP, cents in EUR).

deducted_feesobject

currencystring

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

AUDCADDKKEURGBPNZDSEKUSD

referencestring

Reference which appears on the creditor's bank statement.

statusstring

One of:

pending: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider.
paid: the payout has been sent to the your bank. FX payouts will become paid after we emit the fx_rate_confirmed webhook.
bounced: the payout bounced when sent, the payout can be retried.

pendingpaidbounced

payout_typestring

Whether a payout contains merchant revenue or partner fees.

merchantpartner

arrival_datestring

Date the payout is due to arrive in the creditor's bank account. One of:

yyyy-mm-dd: the payout has been paid and is due to arrive in the creditor's bank account on this day
null: the payout hasn't been paid yet

linksobject

2 properties

creditorstring

ID of creditor who will receive this payout, i.e. the owner of the creditor_bank_account.

creditor_bank_accountstring

ID of bank account which this will be sent to.

fxobject

4 properties

exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

AUDCADDKKEURGBPNZDSEKUSD

tax_currencystring

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. Note: This should not be used for storing PII data.

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