Connection
- Authentication: API key (Access token).
- Required settings:
- Environment — Use “api-sandbox” for the Sandbox (api-sandbox.gocardless.com), or “api” for Live (api.gocardless.com).
Sign in to your GoCardless dashboard — manage-sandbox.gocardless.com for the Sandbox, manage.gocardless.com for Live — then Developers → Create → Access token. Name it, give it Read-write access, and copy the token (it is shown once). Enter “api-sandbox” in the Environment field for a sandbox token, “api” for a live one: a token is valid on its own environment only.See GoCardless’s documentation.
Read actions (10)
| Action | Description |
|---|---|
get_customer | Fetch a single customer: name, e-mail, address, language and metadata. |
get_payment | Fetch a single payment: amount, currency, status, charge date, description and links. |
list_billing_requests | List billing requests, to find back the id of a request created earlier and check whether the payer completed it. Optional filters: status, customer. Cursor pagination with limit + after/before. |
list_customer_bank_accounts | List customer bank accounts (masked account number, bank name, country). Optional filters: customer, enabled, created_at_gt / created_at_lt. Cursor pagination with limit + after/before. |
list_customers | List customers, newest first. Optional filters: currency, sort_field, sort_direction, created_at_gt / created_at_lt. Cursor pagination with limit + after/before. |
list_events | List events — the audit trail of everything that happened (payment failed, mandate cancelled…). Optional filters: resource_type, action, or one resource id among payment / mandate / subscription / payout / billing_request, plus created_at_gt / created_at_lt. resource_type cannot be combined with a resource id. Cursor pagination with limit + after/before. |
list_mandates | List Direct Debit mandates — the authorisation a payment or a subscription is collected against. Optional filters: customer, creditor, customer_bank_account, status, reference, mandate_type, created_at_gt / created_at_lt. Cursor pagination with limit + after/before. |
list_payments | List payments. Optional filters: customer, mandate, subscription, creditor, status, currency, charge_date_gte / charge_date_lte, created_at_gt / created_at_lt, sort_field, sort_direction. Cursor pagination with limit + after/before. |
list_payouts | List payouts — the amounts GoCardless has sent to your bank account, to reconcile against collected payments. Optional filters: status, currency, creditor, payout_type, reference, created_at_gt / created_at_lt. Cursor pagination with limit + after/before. |
list_subscriptions | List subscriptions (recurring payment schedules). Optional filters: customer, mandate, status, created_at_gt / created_at_lt. Cursor pagination with limit + after/before. |
Write actions (8)
| Action | Description |
|---|---|
cancel_mandate | Cancel a mandate: it moves to “cancelled” and no new payment can be collected against it. Arguments: mandateId (string MD…, in the path), metadata (object of string values, up to 3 keys, optional). The body is sent enveloped as {“mandates”: {…}}. |
cancel_payment | Cancel a payment that has not yet been submitted to the banks (status “pending_submission” or “pending_customer_approval”); it moves to “cancelled”. Arguments: paymentId (string PM…, in the path), metadata (object of string values, up to 3 keys, optional). The body is sent enveloped as {“payments”: {…}}. |
cancel_subscription | Cancel a subscription: it moves to “cancelled” and no further payment is created; payments already submitted are still collected. Arguments: subscriptionId (string SB…, in the path), metadata (object of string values, up to 3 keys, optional). The body is sent enveloped as {“subscriptions”: {…}}. |
create_billing_request | Create a billing request: the object that asks a payer to authorise a mandate (and optionally pay straight away). Arguments: mandate_request (object {currency: string 3-letter ISO 4217, scheme: string bank payment scheme — “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” or “sepa_core”, description: string, reference: string, verify: string enum “minimum” | “recommended” | “when_available” | “always”} — all optional but currency and scheme are what pins the mandate), payment_request (object {amount: integer in the lowest denomination, e.g. cents, currency: string, description: string, reference: string} — optional, for an instant first payment), customer_id (string CU…, optional, to attach the request to an existing customer), fallback_enabled (boolean), metadata (object of string values, up to 3 keys). The body is sent enveloped as {“billing_requests”: {…}} with customer_id moved into links.customer. Then call create_billing_request_flow to obtain the URL to send to the payer. |
create_billing_request_flow | Create the hosted flow for a billing request and return its authorisation_url — the link to send to the payer so they authorise the mandate. Arguments: billing_request_id (string BRQ…, required, sent as links.billing_request), redirect_uri (string URL the payer returns to once done), exit_uri (string URL for a payer who cannot go further), language (string, 2-letter ISO 639-1, e.g. “fr”), lock_customer_details (boolean), lock_bank_account (boolean), prefilled_customer (object {email, given_name, family_name, company_name, address_line1, address_line2, address_line3, city, region, postal_code, country_code} — all strings, all optional). The body is sent enveloped as {“billing_request_flows”: {…}}. |
create_customer | Create a customer. Arguments: email (string — required in most cases, so GoCardless can notify the payer), given_name (string) and family_name (string) — both required unless company_name is given, company_name (string, required unless given_name + family_name are given), address_line1 / address_line2 / address_line3 (strings), city (string), region (string, 2-letter ISO 3166-2 code for US customers), postal_code (string), country_code (string, 2-letter ISO 3166-1 alpha-2, e.g. “FR”), language (string, 2-letter ISO 639-1, e.g. “fr”), phone_number (string, ITU E.123 with country code), metadata (object of string values: up to 3 keys, key names up to 50 characters, values up to 500). The body is sent enveloped as {“customers”: {…}}. |
create_payment | Collect a one-off payment against an active mandate. Arguments: amount (integer, REQUIRED, in the lowest denomination for the currency — 1250 means 12.50 EUR), currency (string enum, REQUIRED: AUD | CAD | DKK | EUR | GBP | NZD | SEK | USD), mandate_id (string MD…, REQUIRED, sent as links.mandate — see list_mandates), description (string, shown to the payer in the notification e-mail), charge_date (string “yyyy-mm-dd”, a future collection date; collected as soon as possible when omitted), reference (string appearing on the payer bank statement), retry_if_possible (boolean), metadata (object of string values, up to 3 keys). The body is sent enveloped as {“payments”: {…}}. |
create_subscription | Create a subscription: a recurring payment schedule on an active mandate. Arguments: amount (integer, REQUIRED, in the lowest denomination for the currency), currency (string, REQUIRED, 3-letter ISO 4217 — AUD, CAD, DKK, EUR, GBP, NZD, SEK and USD are supported), interval_unit (string enum, REQUIRED: “weekly” | “monthly” | “yearly”), mandate_id (string MD…, REQUIRED, sent as links.mandate), interval (integer ≥ 1, number of interval_units between charges, default 1), day_of_month (integer 1–28, or -1 for the last day of the month), month (string enum: january…december, lowercase, only when interval_unit is “yearly”), name (string, max 255, used as the description of each payment), start_date (string “yyyy-mm-dd”), end_date (string “yyyy-mm-dd”), count (integer, total number of payments to take), payment_reference (string), retry_if_possible (boolean), metadata (object of string values, up to 3 keys). The body is sent enveloped as {“subscriptions”: {…}}. |
Permissions
Every action above must be explicitly granted to an agent before it can be used. See Permissions for the grant model and Security for how credentials are protected.Last reviewed against the provider API: September 2026.