Event

View as Markdown

Events are stored for all webhooks. An event refers to a resource which has been updated, for example a payment which has been collected, or a mandate which has been transferred. Event creation is an asynchronous process, so it can take some time between an action occurring and its corresponding event getting included in API responses. See here for a complete list of event types.

List events#

GET/events

Returns a cursor-paginated list of your events.

Important: This endpoint will no longer return events older than 18 months, including when filtering by resource. This takes effect no sooner than 1 August 2026 in sandbox environments, and no sooner than 1 October 2026 in live environments.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

@client.events.list

@client.events.list(params: { resource_type: "payments" })

@client.events.list.records.each { |event| puts event.inspect }

client.events.list().records

client.events.list(params={"resource_type": "payments"}).records

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

// List all events of a given resource type.
const paymentEvents = await client.events.list({ resource_type: "payments" });

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

$client->events()->list([
  "params" => ["resource_type" => "payments"]
]);

import com.gocardless.services.EventService.EventListRequest.ResourceType;

for (Event event : client.events().all().withResourceType(ResourceType.PAYMENTS).execute()) {
  System.out.println(event.getAction());
}

eventListParams := gocardless.EventListParams{
  ResourceType: "payments",
}

eventListResult, err := client.Events.List(ctx, eventListParams)
for _, event := range eventListResult.Events {
    fmt.Println(event.Action)
}

var eventRequest = new GoCardless.Services.EventListRequest()
{
    ResourceType = GoCardless.Services.EventListRequest.EventResourceType.Payments
};

var eventListResponse = client.Events.All(eventRequest);
foreach (GoCardless.Resources.Event eventResource in eventListResponse)
{
    Console.WriteLine(eventResource.Action);
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 50
  },
  "events":[
    {
      "id": "EV123",
      "created_at": "2014-04-08T17:01:06.000Z",
      "resource_type": "mandates",
      "action": "cancelled",
      "details": {
        "origin": "bank",
        "cause": "bank_account_disabled",
        "description": "Customer's bank account closed",
        "scheme": "bacs",
        "reason_code": "ADDACS-B"
      },
      "metadata": {},
      "resource_metadata": { "order_id": "123" },
      "links": {
        "mandate": "MD123"
      }
    },
    {
      "id": "EV456",
      "created_at": "2014-04-08T17:01:06.000Z",
      "resource_type": "payments",
      "action": "cancelled",
      "details": {
        "origin": "bank",
        "cause": "mandate_cancelled",
        "description": "The mandate for this payment was cancelled at a bank branch.",
        "scheme": "bacs",
        "reason_code": "ADDACS-B"
      },
      "metadata": {},
      "resource_metadata": { "order_dispatch_date": "2014-05-22" },
      "links": {
        "payment": "PM123",
        "parent_event": "EV123"
      }
    }
  ]
}

GET https://api.gocardless.com/events?resource_type=payments&include=payment HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "after": null,
      "before": null
    },
    "limit": 50
  },
  "events":[
    {
      "id": "EV456",
      "created_at": "2014-04-08T17:01:06.000Z",
      "resource_type": "payments",
      "action": "cancelled",
      "details": {
        "origin": "bank",
        "cause": "mandate_cancelled",
        "description": "The mandate for this payment was cancelled at a bank branch.",
        "scheme": "bacs",
        "reason_code": "ADDACS-B"
      },
      "metadata": {},
      "resource_metadata": { "order_dispatch_date": "2014-05-22" },
      "links": {
        "payment": "PM123",
        "parent_event": "EV123"
      }
    }
  ],
  "linked": {
    "payments": [
      {
        "id": "PM123",
        "created_at": "2014-05-08T17:01:06.000Z",
        "charge_date": "2014-05-15",
        "amount": 100,
        "description": null,
        "currency": "GBP",
        "status": "paid_out",
        "reference": "WINEBOX001",
        "metadata": {
          "order_dispatch_date": "2014-05-22"
        },
        "amount_refunded": 0,
        "links": {
          "mandate": "MD123",
          "creditor": "CR123"
        }
      }
    ]
  }
}

Response 200

Successful response

eventsarray

10 properties

idstring

Unique identifier, beginning with "EV".

created_atstring

Fixed timestamp, recording when this resource was created.

resource_typestring

The resource type for this event. One of:

billing_requests
creditors
exports
instalment_schedules
mandates
payer_authorisations
payments
payouts
refunds
scheme_identifiers
subscriptions
outbound_payments
payment_account_transactions

billing_requestscreditorscustomersexportsinstalment_schedulesmandatesorganisationsoutbound_paymentspayer_authorisationspaymentspayment_account_transactionspayoutsrefundsscheme_identifierssubscriptions

actionstring

What has happened to the resource. See Event Types for the possible actions.

customer_notificationsarray

Present only in webhooks when an integrator is authorised to send their own notifications. See here for further information.

4 properties

idstring

The id of the notification.

typestring

See here for a complete list of customer notification types.

mandatoryboolean

Whether or not the notification must be sent.

deadlinestring

Time after which GoCardless will send the notification by email.

detailsobject

11 properties

originstring

Who initiated the event. One of:

bank: this event was triggered by a report from the banks
gocardless: this event was performed by GoCardless automatically
api: this event was triggered by an API endpoint
customer: this event was triggered by a Customer
payer: this event was triggered by a Payer

bankapigocardlesscustomerpayer

causestring

What triggered the event. Note: cause is our simplified and predictable key indicating what triggered the event.

descriptionstring

Human readable description of the cause. Note: Changes to event descriptions are not considered breaking.

schemestring

A bank payment scheme. Set when a bank is the origin of the event.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_coresepa_cor1

reason_codestring

Set when a bank is the origin of the event. This is the reason code received in the report from the customer's bank. See the GoCardless Direct Debit guide for information on the meanings of different reason codes. Note: reason_code is payment scheme-specific and can be inconsistent between banks.

will_attempt_retryboolean

Whether the payment will be retried automatically. Set on a payment failed event.

not_retried_reasonstring

When will_attempt_retry is set to false, this field will contain the reason the payment was not retried. This can be one of:

failure_filter_applied: The payment won't be intelligently retried as there is a high likelihood of failure on retry.
other: The payment won't be intelligently retried due to any other reason.

bank_account_idstring

When we send a creditor new_payout_currency_added webhook, we also send the bank account id of the new account

currencystring

When we send a creditor new_payout_currency_added webhook, we also send the currency of the new account

propertystring

When we send a creditor creditor_updated webhook, this tells you which property on the creditor has been updated

item_countinteger

Count of rows in the csv. This is sent for export events

metadataobject

The metadata that was passed when making the API request that triggered the event (for instance, cancelling a mandate).

This field will only be populated if the details[origin] field is api otherwise it will be an empty object.

resource_metadataobject

The metadata of the resource that the event is for. For example, this field will have the same value of the mandate[metadata] field on the response you would receive from performing a GET request on a mandate.

sourceobject

Audit information about the source of the event.

2 properties

typestring

The type of the event's source.

appusergc_teamaccess_token

namestring

The name of the event's source.

linksobject

24 properties

billing_requeststring

ID of a billing request.

billing_request_flowstring

ID of a billing request flow.

bank_authorisationstring

ID of a bank authorisation.

payment_request_paymentstring

If resource_type is billing_requests, this is the ID of the payment which has been created for Pay by Bank.

mandate_requeststring

This is the id of the mandate request associated to this event

mandate_request_mandatestring

If resource_type is billing_requests, this is the ID of the mandate which has been created.

customerstring

ID of a customer.

customer_bank_accountstring

ID of a customer bank account.

paymentstring

If resource_type is payments, this is the ID of the payment which has been updated.

mandatestring

If resource_type is mandates, this is the ID of the mandate which has been updated.

payer_authorisationstring

ID of a payer authorisation.

payoutstring

If resource_type is payouts, this is the ID of the payout which has been updated.

refundstring

If resource_type is refunds, this is the ID of the refund which has been updated.

subscriptionstring

If resource_type is subscription, this is the ID of the subscription which has been updated.

instalment_schedulestring

If resource_type is instalment_schedule, this is the ID of the instalment schedule which has been updated.

creditorstring

If resource_type is creditor, this is the ID of the creditor which has been updated.

parent_eventstring

If this event was caused by another, this is the ID of the cause. For example, if a mandate is cancelled it automatically cancels all pending payments associated with it; in this case, the payment cancellation events would have the ID of the mandate cancellation event in this field.

previous_customer_bank_accountstring

This is only included for mandate transfer events, when it is the ID of the customer bank account which the mandate is being transferred from.

new_customer_bank_accountstring

This is only included for mandate transfer events, when it is the ID of the customer bank account which the mandate is being transferred to.

new_mandatestring

This is only included for mandate replaced events, when it is the ID of the new mandate that replaces the existing mandate.

organisationstring

If the event is included in a webhook to an OAuth app, this is the ID of the account to which it belongs.

outbound_paymentstring

If resource_type is outbound_payments, this is the ID of the outbound_payment which has been updated.

payment_account_transactionstring

If resource_type is payment_account_transaction, this is the ID of a transaction which has been recorded on the payment account.

scheme_identifierstring

If resource_type is scheme_identifiers, this is the ID of the scheme_identifier which has been updated.

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.

linkedobject

13 properties

billing_requestsarray

A list of billing requests linked to the events returned in the list of events.

16 properties

idstring

Unique identifier, beginning with "BRQ".

purpose_codestring

Specifies the high-level purpose/category of a mandate and/or payment using a set of pre-defined categories. Provides context on the nature and reason for the payment to facilitate processing and compliance. See Billing Request Purpose Codes for the complete list of valid codes.

mortgageutilityloandependant_supportgamblingretailsalarypersonalgovernmentpensiontaxotherbonus_paymentcash_management_transfercard_bulk_clearingcredit_card_paymenttrade_settlement_paymentdebit_card_paymentdividenddeliver_against_paymentepaymentfee_collection_and_interestfee_collectionperson_to_person_paymentgovernment_paymenthedging_transactionirrevocable_credit_card_paymentirrevocable_debit_card_paymentintra_company_paymentinterestlockbox_transactionscommercialconsumerother_paymentpension_paymentrepresentedreimbursement_received_credit_transferreceive_against_paymentsalary_paymentsecuritiessocial_security_benefitsupplier_paymenttax_paymenttradetreasury_paymentvalue_added_tax_paymentwith_holdingcash_management_sweep_accountcash_management_top_accountcash_management_zero_balance_accountcrossborder_mi_paymentsforeign_currency_domestic_transfercash_in_pre_creditcash_out_notes_coinscarrier_guarded_wholesale_valuables

payment_purpose_codestring

Specifies the underlying purpose of the payment. Defines the specific reason or type of service/goods the payment relates to, improving straight-through processing and compliance. See VRP Commercial Payment Purpose Codes for the complete list of valid codes.

payment_context_codestring

Specifies the context or scenario in which the payment is being made. Defines whether the payment is for advance/arrears billing, point of sale transactions, ecommerce, or account transfers. This helps banks and payment processors understand the payment scenario and apply appropriate processing rules and risk controls.

billing_goods_and_services_in_advancebilling_goods_and_services_in_arrearsface_to_face_point_of_saleecommerce_merchant_initiated_paymenttransfer_to_selftransfer_to_third_party

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

One of:

pending: the billing request is pending and can be used
ready_to_fulfil: the billing request is ready to fulfil
fulfilling: the billing request is currently undergoing fulfilment
fulfilled: the billing request has been fulfilled and a payment created
cancelled: the billing request has been cancelled and cannot be used

pendingready_to_fulfilfulfillingfulfilledcancelled

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.

mandate_requestobject

Request for a mandate

12 properties

descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

currencystring

ISO 4217 currency code.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.

sweepingboolean

If true, this billing request would be used to set up a mandate solely for moving (or sweeping) money from one account owned by the payer to another account that the payer also owns. This is required for Faster Payments

verifystring

Verification preference for the mandate. One of:

minimum: only verify if absolutely required, such as when part of scheme rules
recommended: in addition to minimum, use the GoCardless payment intelligence solution to decide if a payer should be verified
when_available: if verification mechanisms are available, use them
always: as when_available, but fail to create the Billing Request if a mechanism isn't available

By default, all Billing Requests use the recommended verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended behaves like minimum.

If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum verification preference.

See Billing Requests: Creating Verified Mandates for more information.

minimumrecommendedwhen_availablealways

linksobject

1 properties

mandatestring

(Optional) ID of the mandate that was created from this mandate request. this mandate request.

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.

consent_typestring

This attribute represents the authorisation type between the payer and merchant. It can be set to one_off, recurring or standing for ACH scheme. And single, recurring and sporadic for PAD scheme. Note: This is only supported for ACH and PAD schemes.

constraintsobject

Constraints that will apply to the mandate_request. (Optional) Specifically required for PayTo and VRP.

5 properties

start_datestring

The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

This is an optional field and if it is not supplied the agreement will be considered open and will not have an end date. Keep in mind the end date must take into account how long it will take the user to set up this agreement via the Billing Request.

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Note: Required for PayTo and VRP.

payment_methodstring

A constraint where you can specify info (free text string) about how payments are calculated. For use when payments vary and cannot be expressed as a fixed amount and frequency. Note: This is only supported for ACH and PAD schemes.

periodic_limitsarray

Caps on the total amount and/or number of payments that can be collected within a repeating period (e.g. no more than a set amount per month), as opposed to max_amount_per_payment which caps a single payment.

Note: Required for VRP, where exactly one periodic limit must be provided. Optional for PayTo.

4 properties

payer_requested_dual_signatureboolean

This attribute can be set to true if the payer has indicated that multiple signatures are required for the mandate. As long as every other Billing Request actions have been completed, the payer will receive an email notification containing instructions on how to complete the additional signature. The dual signature flow can only be completed using GoCardless branded pages.

authorisation_sourcestring

This field is ACH specific, sometimes referred to as SEC code.

This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)

webtelephonepaper

funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

managed will be moved through GoCardless' account, batched, and payed out.
direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.

manageddirect

payment_requestobject

Request for a one-off strongly authorised payment

9 properties

descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

currencystring

ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries only.

schemestring

(Optional) A scheme used for Open Banking payments. Currently faster_payments is supported in the UK (GBP) and sepa_credit_transfer and sepa_instant_credit_transfer are supported in supported Eurozone countries (EUR). For Eurozone countries, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.

amountobject

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

linksobject

1 properties

paymentstring

(Optional) ID of the payment that was created from this payment request.

app_feeobject

The amount to be deducted from the payment as an app fee, to be paid to the partner integration which created the billing request, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

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.

referencestring

A custom payment reference defined by the merchant. It is only available for payments on the PayTo scheme or payments using the Direct Funds settlement model on the Faster Payments scheme.

funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

managed will be moved through GoCardless' account, batched, and payed out.
direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.

manageddirect

subscription_requestobject

Request for a subscription

14 properties

amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly

intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

app_feeobject

The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

countobject

The total number of payments that should be taken by this subscription.

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

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.

linksobject

1 properties

subscriptionstring

(Optional) ID of the subscription that was created from this subscription request.

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember

namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

payment_referencestring

An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the create payment endpoint for more details.

start_datestring

The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date.

retry_if_possibleboolean

On failure, automatically retry payments using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

instalment_schedule_requestobject

Request for an instalment schedule. Has to contain either instalments_with_schedule object or an array of instalments_with_dates objects

10 properties

namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

ISO 4217 currency code. Currently "USD" and "CAD" are supported.

total_amountobject

The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.

payment_referencestring

app_feeobject

instalments_with_datesarray

An explicit array of instalment payments, each specifying at least an amount and charge_date. See create (with dates)

3 properties

amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

charge_datestring

A future date on which the payment should be collected. If the date is before the next_possible_charge_date on the mandate, it will be automatically rolled forwards to that date.

descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

instalments_with_scheduleobject

Frequency of the payments you want to create, together with an array of payment amounts to be collected, with a specified start date for the first payment. See create (with schedule)

4 properties

start_datestring

The date on which the first payment should be charged. Must be on or after the mandate's next_possible_charge_date. When left blank and month or day_of_month are provided, this will be set to the date of the first payment. If created without month or day_of_month this will be set as the mandate's next_possible_charge_date

intervalinteger

Number of interval_units between charge dates. Must be greater than or equal to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly

amountsarray

List of amounts of each instalment, in the lowest denomination for the currency (e.g. cents in USD).

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.

linksobject

1 properties

instalment_schedulestring

(Optional) ID of the instalment_schedule that was created from this instalment schedule request.

retry_if_possibleboolean

On failure, automatically retry payments using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

actionsarray

List of actions that can be performed before this billing request can be fulfilled.

9 properties

typestring

Unique identifier for the action.

choose_currencycollect_amountcollect_customer_detailscollect_bank_accountbank_authorisationconfirm_payer_detailsselect_institution

statusstring

Status of the action

pendingcompleted

requiredboolean

Informs you whether the action is required to fulfil the billing request or not.

completes_actionsarray

Which other action types this action can complete.

requires_actionsarray

Requires completing these actions before this action can be completed.

bank_authorisationobject

Describes the behaviour of bank authorisations, for the bank_authorisation action

2 properties

adapterstring

Which authorisation adapter will be used to power these authorisations (GoCardless internal use only)

open_banking_gateway_pisopen_banking_gateway_aisbankid_aisbank_pay_recurring

authorisation_typestring

What type of bank authorisations are supported on this billing request

paymentmandate

collect_customer_detailsobject

Additional parameters to help complete the collect_customer_details action

2 properties

default_country_codestring

Default customer country code, as determined by scheme and payer location

incomplete_fieldsobject

2 properties

available_currenciesarray

List of currencies the current mandate supports

institution_guess_statusstring

Describes whether we inferred the institution from the provided bank account details. One of:

not_needed: we won't attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature
pending: we are waiting on the bank details in order to infer the institution
failed: we weren't able to infer the institution
success: we inferred the institution and added it to the resources of a Billing Request

not_neededpendingfailedsuccess

resourcesobject

3 properties

customerobject

Embedded customer

9 properties

idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

languagestring

ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the country_code (if supplied) or default to "en".

phone_numberstring

ITU E.123 formatted phone number, including country code.

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.

customer_billing_detailobject

Embedded customer billing detail

13 properties

idstring

Unique identifier, beginning with "CU".

schemesarray

The schemes associated with this customer billing detail

created_atstring

Fixed timestamp, recording when this resource was created.

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

customer_bank_accountobject

Embedded customer bank account, only if a bank account is linked

13 properties

idstring

Unique identifier, beginning with "BA".

created_atstring

Fixed timestamp, recording when this resource was created.

account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_typestring

Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.

savingschecking

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

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

bank_namestring

Name of bank, taken from the bank details.

enabledboolean

Boolean value showing whether the bank account is enabled or disabled.

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.

linksobject

1 properties

bank_account_tokenstring

A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.

payer_name_verification_resultstring

The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.

full: The name provided matches the name held by the bank.
close: The name provided is a close but not exact match to the name held by the bank.
cannot_perform_verification: A verification was attempted but could not be completed. This can happen for a number of reasons, including the account holder's bank not participating in the verification scheme, the account not being eligible for verification (e.g. the account holder has opted out), or the bank details not being resolvable, among others.

fullclosecannot_perform_verification

linksobject

15 properties

customerstring

ID of the customer that will be used for this request

customer_billing_detailstring

ID of the customer billing detail that will be used for this request

creditorstring

ID of the associated creditor.

organisationstring

ID of the associated organisation.

customer_bank_accountstring

(Optional) ID of the customer_bank_account that will be used for this request

bank_authorisationstring

(Optional) ID of the bank authorisation that was used to verify this request.

payment_requeststring

(Optional) ID of the associated payment request

payment_request_paymentstring

(Optional) ID of the payment that was created from this payment request.

mandate_requeststring

(Optional) ID of the associated mandate request

mandate_request_mandatestring

(Optional) ID of the mandate that was created from this mandate request. this mandate request.

subscription_requeststring

(Optional) ID of the associated subscription request

subscription_request_subscriptionstring

(Optional) ID of the subscription that was created from this subscription request.

instalment_schedule_requeststring

(Optional) ID of the associated instalment schedule request

instalment_schedule_request_instalment_schedulestring

(Optional) ID of the instalment_schedule that was created from this instalment schedule request.

payment_providerstring

(Optional) ID of the associated payment provider

fallback_enabledboolean

(Optional) If true, this billing request can fallback from instant payment to direct debit. Should not be set if GoCardless payment intelligence feature is used.

See Billing Requests: Retain customers with Fallbacks for more information.

fallback_occurredboolean

True if the billing request was completed with direct debit.

creditorsarray

A list of creditors linked to the events returned in the list of events.

21 properties

idstring

Unique identifier, beginning with "CR".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The creditor's trading name.

address_line1string

The first line of the creditor's address.

address_line2string

The second line of the creditor's address.

address_line3string

The third line of the creditor's address.

citystring

The city of the creditor's address.

regionstring

The creditor's address region, county or department.

postal_codestring

The creditor's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

can_create_refundsboolean

Boolean indicating whether the creditor is permitted to create refunds.

bank_reference_prefixstring

Prefix for the bank reference of payouts sent to this creditor. For instance, if the creditor's bank_reference_prefix was ACME, the bank reference of a payout sent to that creditor could be ACME-8G7Q8.

This prefix is also used for refunds in EUR and GBP.

linksobject

8 properties

default_aud_payout_accountstring

ID of the bank account which is set up to receive payouts in AUD.

default_gbp_payout_accountstring

ID of the bank account which is set up to receive payouts in GBP.

default_eur_payout_accountstring

ID of the bank account which is set up to receive payouts in EUR.

default_sek_payout_accountstring

ID of the bank account which is set up to receive payouts in SEK.

default_dkk_payout_accountstring

ID of the bank account which is set up to receive payouts in DKK.

default_nzd_payout_accountstring

ID of the bank account which is set up to receive payouts in NZD.

default_cad_payout_accountstring

ID of the bank account which is set up to receive payouts in CAD.

default_usd_payout_accountstring

ID of the bank account which is set up to receive payouts in USD.

scheme_identifiersarray

An array of the scheme identifiers this creditor can create mandates against.

The support address, phone_number and email fields are for customers to contact the merchant for support purposes. They must be displayed on the payment page, please see our compliance requirements for more details.

18 properties

idstring

Unique identifier, usually beginning with "SU".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The name which appears on customers' bank statements. This should usually be the merchant's trading name.

schemestring

The scheme which this scheme identifier applies to.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transfer

referencestring

The scheme-unique identifier against which payments are submitted.

statusstring

The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.

pendingactive

minimum_advance_noticeinteger

The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier.

By default, GoCardless sends these notifications automatically. Please see our compliance requirements for more details.

address_line1string

The first line of the scheme identifier's support address.

address_line2string

The second line of the scheme identifier's support address.

address_line3string

The third line of the scheme identifier's support address.

citystring

The city of the scheme identifier's support address.

regionstring

The scheme identifier's support address region, county or department.

postal_codestring

The scheme identifier's support postal code.

country_codestring

ISO 3166-1 alpha-2 code.

emailstring

Scheme identifier's support email address.

phone_numberstring

Scheme identifier's support phone number.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD

can_specify_mandate_referenceboolean

Whether a custom reference can be submitted for mandates using this scheme identifier.

logo_urlstring

URL for the creditor's logo, which may be shown on their payment pages.

verification_statusstring

The creditor's verification status, indicating whether they can yet receive payouts. For more details on handling verification as a partner, see our "Helping your users get verified" guide. One of:

successful: The creditor's account is fully verified, and they can receive payouts. Once a creditor has been successfully verified, they may in the future require further verification - for example, if they change their payout bank account, we will have to check that they own the new bank account before they can receive payouts again.
in_review: The creditor has provided all of the information currently requested, and it is awaiting review by GoCardless before they can be verified and receive payouts.
action_required: The creditor needs to provide further information to verify their account so they can receive payouts, and should visit the verification flow.

successfulin_reviewaction_required

merchant_responsible_for_notificationsboolean

Boolean value indicating whether the organisation is responsible for sending all customer notifications (note this is separate from the functionality described here). If you are a partner app, and this value is true, you should not send notifications on behalf of this organisation.

mandate_imports_enabledboolean

Boolean value indicating whether creditor has the Mandate Imports functionality enabled.

custom_payment_pages_enabledboolean

Boolean value indicating whether creditor has the Custom Payment Pages functionality enabled.

fx_payout_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

creditor_typestring

The type of business of the creditor. Currently, individual, company, charity, partnership, and trust are supported.

companyindividualcharitypartnershiptrust

instalment_schedulesarray

A list of instalment schedules linked to the events returned in the list of events.

9 properties

idstring

Unique identifier, beginning with "IS".

created_atstring

Fixed timestamp, recording when this resource was created.

total_amountobject

namestring

Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.

currencystring

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

AUDCADDKKEURGBPNZDSEKUSD

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.

statusstring

One of:

pending: we're waiting for GC to create the payments
active: the payments have been created, and the schedule is active
creation_failed: payment creation failed
completed: we have passed the date of the final payment and all payments have been collected
cancelled: the schedule has been cancelled
errored: one or more payments have failed

pendingactivecreation_failedcompletedcancellederrored

payment_errorsobject

If the status is creation_failed, this property will be populated with validation failures from the individual payments, arranged by the index of the payment that failed.

linksobject

Links to associated objects

3 properties

mandatestring

ID of the associated mandate which the instalment schedule will create payments against.

customerstring

ID of the associated customer.

paymentsarray

Array of IDs of the associated payments

mandatesarray

A list of mandates linked to the events returned in the list of events.

16 properties

idstring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

created_atstring

Fixed timestamp, recording when this resource was created.

referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

statusstring

One of:

pending_customer_approval: the mandate has not yet been signed by the second customer
pending_submission: the mandate has not yet been submitted to the customer's bank
submitted: the mandate has been submitted to the customer's bank but has not been processed yet
active: the mandate has been successfully set up by the customer's bank
suspended_by_payer: the mandate has been suspended by payer
failed: the mandate could not be created
cancelled: the mandate has been cancelled
expired: the mandate has expired due to dormancy
consumed: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)
blocked: the mandate has been blocked and payments cannot be created

pending_customer_approvalpending_submissionsubmittedactivefailedcancelledexpiredconsumedblockedsuspended_by_payer

schemestring

Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.

mandate_typestring

Mandate type

bank_debitinstantrecurringvrp_commercialvrp_sweeping

next_possible_charge_datestring

The earliest date that can be used as a charge_date on any newly created payment for this mandate. This value will change over time.

next_possible_standard_ach_charge_datestring

If this is an an ACH mandate, the earliest date that can be used as a charge_date on any newly created payment to be charged through standard ACH, rather than Faster ACH. This value will change over time.

It is only present in the API response for ACH mandates.

payments_require_approvalboolean

Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.

verified_atstring

Timestamp recording when this mandate was verified.

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.

linksobject

4 properties

customer_bank_accountstring

ID of the associated customer bank account which the mandate is created and submits payments against.

creditorstring

ID of the associated creditor.

new_mandatestring

ID of the new mandate if this mandate has been replaced.

customerstring

ID of the associated customer

consent_parametersobject

(Optional) Payto and VRP Scheme specific information

6 properties

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment

periodstring

The repeating period for this mandate

dayweekmonthyearflexible

max_amount_per_periodinteger

The maximum total amount that can be charged for all payments in this period

max_payments_per_periodinteger

The maximum number of payments that can be collected in this period

start_datestring

The date from which payments can be taken

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

authorisation_sourcestring

This field is ACH specific, sometimes referred to as SEC code.

webtelephonepaper

funds_settlementstring

This field will decide how GoCardless handles settlement of funds from the customer.

managed will be moved through GoCardless' account, batched, and payed out.
direct will be a direct transfer from the payer's account to the merchant where invoicing will be handled separately.

manageddirect

consent_typestring

(Optional) Specifies the type of authorisation agreed between the payer and merchant. It can be set to one-off, recurring or standing for ACH, or single, recurring and sporadic for PAD.

one_offsinglerecurringstandingsporadic

outbound_paymentsarray

A list of outbound payments linked to the events returned in the list of events.

13 properties

idstring

Unique identifier of the outbound payment.

created_atstring

Fixed timestamp, recording when the outbound payment was created.

statusstring

One of:

verifying: The payment has been created and the verification process has begun.
pending_approval: The payment is awaiting approval.
scheduled: The payment has passed verification & approval, but processing has not yet begun.
executing: The execution date has arrived and the payment has been placed in queue for processing.
executed: The payment has been accepted by the scheme and is now on its way to the recipient.
cancelled: The payment has been cancelled or was not approved on time.
failed: The payment was not sent, usually due to an error while or after executing.

verifyingpending_approvalscheduledexecutingexecutedcancelledfailed

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

descriptionstring

A human-readable description of the outbound payment

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
Faster Payments - 18 characters, including: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 &-./"

is_withdrawalboolean

Indicates whether the outbound payment is a withdrawal to your verified business bank account.

linksobject

4 properties

creditorstring

ID of the creditor who sends the outbound payment.

customerstring

ID of the customer that receives this outbound payment

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

verificationsobject

Contains details of the verifications performed for the outbound payment

1 properties

recipient_bank_account_holder_verificationobject

Checks if the recipient owns the provided bank account

3 properties

typestring

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee

resultstring

Result of the verification, could be one of

full_match: The verification has confirmed that the account name exactly matches the details provided.
partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
no_match: The verification concludes the provided name does not match the account details.
unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

full_matchpartial_matchno_matchunable_to_match

actual_account_namestring

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

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.

payer_authorisationsarray

A list of payer authorisations linked to the events returned in the list of events.

8 properties

idstring

Unique identifier, beginning with "PA".

created_atstring

Timestamp, recording when this Payer Authorisation was created.

customerobject

All details required for the creation of a Customer.

15 properties

emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

localestring

An IETF Language Tag, used for both language and regional variations of our product.

swedish_identity_numberstring

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

bank_accountobject

All details required for the creation of a Customer Bank Account.

11 properties

account_holder_namestring

account_numberstring

Bank account number - see local details for more information. Alternatively you can provide an iban.

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_number_suffixstring

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

bank_codestring

Bank code - see local details for more information. Alternatively you can provide an iban.

branch_codestring

Branch code - see local details for more information. Alternatively you can provide an iban.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

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

account_typestring

Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.

savingschecking

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.

mandateobject

All details required for the creation of a Mandate.

4 properties

referencestring

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core

payer_ip_addressstring

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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.

incomplete_fieldsarray

An array of fields which are missing and is required to set up the mandate.

3 properties

fieldstring

The root resource.

messagestring

A localised error message

request_pointerstring

The path to the field e.g. "/payer_authorisations/customer/city"

linksobject

IDs of the created resources. Available after the Payer Authorisation is completed.

3 properties

customerstring

Unique identifier, beginning with "CU".

bank_accountstring

Unique identifier, beginning with "BA".

mandatestring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

statusstring

One of:

created: The PayerAuthorisation has been created, and not been confirmed yet
submitted: The payer information has been submitted
confirmed: PayerAuthorisation is confirmed and resources are ready to be created
completed: The PayerAuthorisation has been completed and customer, bank_account and mandate has been created
failed: The PayerAuthorisation has failed and customer, bank_account and mandate is not created

createdsubmittedconfirmedcompletedfailed

payment_account_transactionsarray

A list of payment account transactions linked to the events returned in the list of events.

10 properties

idstring

The unique ID of the payment account transaction.

value_datestring

The date of when the transaction occurred.

referencestring

The reference of the transaction. This is typically supplied by the sender.

descriptionstring

The description of the transaction, if available

counterparty_namestring

The name of the counterparty of the transaction. The counterparty is the recipient for a credit, or the sender for a debit.

linksobject

3 properties

payoutstring

ID of the payout linked to the transaction.

outbound_paymentstring

ID of the outbound_payment linked to the transaction

payment_bank_accountstring

ID of the payment bank account.

currencystring

The currency of the transaction.

GBP

directionstring

The direction of the transaction. Debits mean money leaving the account (e.g. outbound payment), while credits signify money coming in (e.g. manual top-up).

creditdebit

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

balance_after_transactioninteger

Balance after transaction, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

paymentsarray

A list of payments linked to the events returned in the list of events.

15 properties

idstring

Unique identifier, beginning with "PM".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

amount_refundedobject

Amount refunded, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

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

AUDCADDKKEURGBPNZDSEKUSD

descriptionstring

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

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.

statusstring

One of:

pending_customer_approval: we're waiting for the customer to approve this payment
pending_submission: the payment has been created, but not yet submitted to the banks
submitted: the payment has been submitted to the banks
confirmed: the payment has been confirmed as collected
paid_out: the payment has been included in a payout
cancelled: the payment has been cancelled
customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly
failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.
charged_back: the payment has been charged back

pending_customer_approvalpending_submissionsubmittedconfirmedpaid_outcancelledcustomer_approval_deniedfailedcharged_back

linksobject

5 properties

mandatestring

ID of the mandate against which this payment should be collected.

creditorstring

ID of creditor to which the collected payment will be sent.

payoutstring

ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected.

subscriptionstring

ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.

instalment_schedulestring

ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule.

faster_achboolean

This field indicates whether the ACH payment is processed through Faster ACH or standard ACH.

It is only present in the API response for ACH payments.

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

AUDCADDKKEURGBPNZDSEKUSD

retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.

payoutsarray

A list of payouts linked to the events returned in the list of events.

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

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

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.

refundsarray

A list of refunds linked to the events returned in the list of events.

9 properties

idstring

Unique identifier, beginning with "RF".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

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

currencystring

ISO 4217 currency code. This is set to the currency of the refund's payment.

statusstring

One of:

created: the refund has been created
pending_submission: the refund has been created, but not yet submitted to the banks
submitted: the refund has been submitted to the banks
paid: the refund has been included in a payout
cancelled: the refund has been cancelled
bounced: the refund has failed to be paid
funds_returned: the refund has had its funds returned

createdpending_submissionsubmittedpaidcancelledbouncedfunds_returned

referencestring

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

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.

linksobject

2 properties

paymentstring

ID of the payment against which the refund is being made.

mandatestring

ID of the mandate against which the refund is being made.

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

subscriptionsarray

A list of subscriptions linked to the events returned in the list of events.

21 properties

idstring

Unique identifier, beginning with "SB".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

namestring

Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.

start_datestring

end_datestring

Date on or after which no further payments should be created.
If this field is blank and count is not specified, the subscription will continue forever.

Deprecated: This field will be removed in a future API version. Use count to specify a number of payments instead.

intervalobject

Number of interval_units between customer charge dates. Must be greater than or equal to 1. Must result in at least one charge date per year. Defaults to 1.

interval_unitstring

The unit of time between customer charge dates. One of weekly, monthly or yearly.

weeklymonthlyyearly

day_of_monthobject

As per RFC 2445. The day of the month to charge customers on. 1-28 or -1 to indicate the last day of the month.

currencystring

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

monthstring

Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is yearly.

januaryfebruarymarchaprilmayjunejulyaugustseptemberoctobernovemberdecember

countobject

The total number of payments that should be taken by this subscription.

payment_referencestring

Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.

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.

statusstring

One of:

pending_customer_approval: the subscription is waiting for customer approval before becoming active
customer_approval_denied: the customer did not approve the subscription
active: the subscription is currently active and will continue to create payments
finished: all of the payments scheduled for creation under this subscription have been created
cancelled: the subscription has been cancelled and will no longer create payments
paused: the subscription has been paused and will not create payments

pending_customer_approvalcustomer_approval_deniedactivefinishedcancelledpaused

upcoming_paymentsarray

Up to 10 upcoming payments with their amounts and charge dates.

2 properties

charge_datestring

The date on which this payment will be charged.

amountobject

The amount of this payment, in minor unit (e.g. pence in GBP, cents in EUR).

app_feeobject

linksobject

1 properties

mandatestring

ID of the associated mandate which the subscription will create payments against.

retry_if_possibleboolean

On failure, automatically retry payments using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

earliest_charge_date_after_resumestring

The earliest date that will be used as a charge_date on payments created for this subscription if it is resumed. Only present for paused subscriptions. This value will change over time.

parent_plan_pausedboolean

Whether the parent plan of this subscription is paused.

scheme_identifiersarray

A list of scheme identifiers linked to the events returned in the list of events.

18 properties

idstring

Unique identifier, usually beginning with "SU".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The name which appears on customers' bank statements. This should usually be the merchant's trading name.

schemestring

The scheme which this scheme identifier applies to.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transfer

referencestring

The scheme-unique identifier against which payments are submitted.

statusstring

The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.

pendingactive

minimum_advance_noticeinteger

The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier.

By default, GoCardless sends these notifications automatically. Please see our compliance requirements for more details.

can_specify_mandate_referenceboolean

Whether a custom reference can be submitted for mandates using this scheme identifier.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD

address_line1string

The first line of the scheme identifier's support address.

address_line2string

The second line of the scheme identifier's support address.

address_line3string

The third line of the scheme identifier's support address.

citystring

The city of the scheme identifier's support address.

regionstring

The scheme identifier's support address region, county or department.

postal_codestring

The scheme identifier's support postal code.

country_codestring

ISO 3166-1 alpha-2 code.

emailstring

Scheme identifier's support email address.

phone_numberstring

Scheme identifier's support phone number.

customersarray

A list of customers linked to the events returned in the list of events.

18 properties

idstring

Unique identifier, beginning with "CU".

created_atstring

Fixed timestamp, recording when this resource was created.

emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

country_codestring

ISO 3166-1 alpha-2 code.

languagestring

phone_numberstring

ITU E.123 formatted phone number, including country code.

swedish_identity_numberstring

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

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 event#

GET/events/{event_id}

Retrieves the details of a single event.

Path Parameters

Name	Type	Description
`event_id`required	string	The event id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/events/EV123 HTTP/1.1

@client.events.get("EV123")

client.events.get("EV123")

const event = await client.events.find("EV123");

$client->events()->get("EV123");

Event event = client.events().get("EV123").execute();

event, err := client.Events.Get(ctx, "EV123")

var eventResponse = await client.Events.GetAsync("EV0123");
GoCardless.Resources.Event eventResource = eventResponse.Event;

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "events": {
    "id": "EV123",
    "created_at": "2014-04-08T17:01:06.000Z",
    "resource_type": "payments",
    "action": "confirmed",
    "details": {
      "origin": "gocardless",
      "cause": "payment_confirmed",
      "description": "Payment confirmed"
    },
    "metadata": {},
    "resource_metadata": { "order_dispatch_date": "2014-05-22" },
    "links": {
      "payment": "PM123"
    }
  }
}

Response 200

Successful response

eventsobject

10 properties

idstring

Unique identifier, beginning with "EV".

created_atstring

Fixed timestamp, recording when this resource was created.

resource_typestring

The resource type for this event. One of:

billing_requests
creditors
exports
instalment_schedules
mandates
payer_authorisations
payments
payouts
refunds
scheme_identifiers
subscriptions
outbound_payments
payment_account_transactions

actionstring

What has happened to the resource. See Event Types for the possible actions.

customer_notificationsarray

Present only in webhooks when an integrator is authorised to send their own notifications. See here for further information.

4 properties

idstring

The id of the notification.

typestring

See here for a complete list of customer notification types.

mandatoryboolean

Whether or not the notification must be sent.

deadlinestring

Time after which GoCardless will send the notification by email.

detailsobject

11 properties

originstring

Who initiated the event. One of:

bank: this event was triggered by a report from the banks
gocardless: this event was performed by GoCardless automatically
api: this event was triggered by an API endpoint
customer: this event was triggered by a Customer
payer: this event was triggered by a Payer

bankapigocardlesscustomerpayer

causestring

What triggered the event. Note: cause is our simplified and predictable key indicating what triggered the event.

descriptionstring

Human readable description of the cause. Note: Changes to event descriptions are not considered breaking.

schemestring

A bank payment scheme. Set when a bank is the origin of the event.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_coresepa_cor1

reason_codestring

will_attempt_retryboolean

Whether the payment will be retried automatically. Set on a payment failed event.

not_retried_reasonstring

When will_attempt_retry is set to false, this field will contain the reason the payment was not retried. This can be one of:

failure_filter_applied: The payment won't be intelligently retried as there is a high likelihood of failure on retry.
other: The payment won't be intelligently retried due to any other reason.

bank_account_idstring

When we send a creditor new_payout_currency_added webhook, we also send the bank account id of the new account

currencystring

When we send a creditor new_payout_currency_added webhook, we also send the currency of the new account

propertystring

When we send a creditor creditor_updated webhook, this tells you which property on the creditor has been updated

item_countinteger

Count of rows in the csv. This is sent for export events

metadataobject

The metadata that was passed when making the API request that triggered the event (for instance, cancelling a mandate).

This field will only be populated if the details[origin] field is api otherwise it will be an empty object.

resource_metadataobject

sourceobject

Audit information about the source of the event.

2 properties

typestring

The type of the event's source.

appusergc_teamaccess_token

namestring

The name of the event's source.

linksobject

24 properties

billing_requeststring

ID of a billing request.

billing_request_flowstring

ID of a billing request flow.

bank_authorisationstring

ID of a bank authorisation.

payment_request_paymentstring

If resource_type is billing_requests, this is the ID of the payment which has been created for Pay by Bank.

mandate_requeststring

This is the id of the mandate request associated to this event

mandate_request_mandatestring

If resource_type is billing_requests, this is the ID of the mandate which has been created.

customerstring

ID of a customer.

customer_bank_accountstring

ID of a customer bank account.

paymentstring

If resource_type is payments, this is the ID of the payment which has been updated.

mandatestring

If resource_type is mandates, this is the ID of the mandate which has been updated.

payer_authorisationstring

ID of a payer authorisation.

payoutstring

If resource_type is payouts, this is the ID of the payout which has been updated.

refundstring

If resource_type is refunds, this is the ID of the refund which has been updated.

subscriptionstring

If resource_type is subscription, this is the ID of the subscription which has been updated.

instalment_schedulestring

If resource_type is instalment_schedule, this is the ID of the instalment schedule which has been updated.

creditorstring

If resource_type is creditor, this is the ID of the creditor which has been updated.

parent_eventstring

previous_customer_bank_accountstring

This is only included for mandate transfer events, when it is the ID of the customer bank account which the mandate is being transferred from.

new_customer_bank_accountstring

This is only included for mandate transfer events, when it is the ID of the customer bank account which the mandate is being transferred to.

new_mandatestring

This is only included for mandate replaced events, when it is the ID of the new mandate that replaces the existing mandate.

organisationstring

If the event is included in a webhook to an OAuth app, this is the ID of the account to which it belongs.

outbound_paymentstring

If resource_type is outbound_payments, this is the ID of the outbound_payment which has been updated.

payment_account_transactionstring

If resource_type is payment_account_transaction, this is the ID of a transaction which has been recorded on the payment account.

scheme_identifierstring

If resource_type is scheme_identifiers, this is the ID of the scheme_identifier which has been updated.

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