Even if no BIC is returned for an account, GoCardless may still be able to collect payments from it - you should refer to the available_debit_schemes attribute to determine reachability.
Important: All properties associated with `subscription_request` and `instalment_schedule_request` are only supported for ACH and PAD schemes.
", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/billing_request_id" }, "purpose_code": { "$ref": "#/components/schemas/billing_request_purpose_code" }, "payment_purpose_code": { "$ref": "#/components/schemas/billing_request_payment_purpose_code" }, "payment_context_code": { "$ref": "#/components/schemas/billing_request_payment_context_code" }, "created_at": { "$ref": "#/components/schemas/billing_request_created_at" }, "status": { "$ref": "#/components/schemas/billing_request_status" }, "metadata": { "$ref": "#/components/schemas/billing_request_nullable_metadata" }, "mandate_request": { "$ref": "#/components/schemas/billing_request_mandate_request" }, "payment_request": { "$ref": "#/components/schemas/billing_request_payment_request" }, "subscription_request": { "$ref": "#/components/schemas/billing_request_subscription_request" }, "instalment_schedule_request": { "$ref": "#/components/schemas/billing_request_instalment_schedule_request" }, "actions": { "$ref": "#/components/schemas/billing_request_actions" }, "resources": { "$ref": "#/components/schemas/billing_request_resources" }, "links": { "$ref": "#/components/schemas/billing_request_links" }, "fallback_enabled": { "$ref": "#/components/schemas/billing_request_fallback_enabled" }, "fallback_occurred": { "$ref": "#/components/schemas/billing_request_fallback_occurred" } } }, "billing_request_nullable_metadata": { "type": "object", "nullable": true, "title": "BillingRequestNullableMetadata", "description": "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." }, "billing_request_id": { "type": "string", "title": "BillingRequestId", "description": "Unique identifier, beginning with \"BRQ\".", "example": "BRQ123" }, "billing_request_identity": { "$ref": "#/components/schemas/billing_request_id" }, "billing_request_created_at": { "type": "string", "title": "BillingRequestCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2015-01-01T12:00:00.000Z", "format": "date-time" }, "billing_request_status": { "type": "string", "title": "BillingRequestStatus", "description": "One of:\n\n- `pending`: the billing request is pending and can be used\n- `ready_to_fulfil`: the billing request is ready to fulfil\n- `fulfilling`: the billing request is currently undergoing fulfilment\n- `fulfilled`: the billing request has been fulfilled and a payment created\n- `cancelled`: the billing request has been cancelled and cannot be used", "example": "pending", "enum": [ "pending", "ready_to_fulfil", "fulfilling", "fulfilled", "cancelled" ] }, "billing_request_fallback_enabled": { "type": "boolean", "title": "BillingRequestFallbackEnabled", "description": "(Optional) If true, this billing request can fallback from instant payment to direct debit.\nShould not be set if GoCardless payment intelligence feature is used.\n\nSee [Billing Requests: Retain customers with Fallbacks](https://developer.gocardless.com/billing-requests/retain-customers-with-fallbacks/)\nfor more information." }, "billing_request_purpose_code": { "title": "BillingRequestPurposeCode", "description": "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.\nSee [Billing Request Purpose Codes](https://developer.gocardless.com/billing-request-purpose-codes/) for the complete list of valid codes.", "enum": [ "mortgage", "utility", "loan", "dependant_support", "gambling", "retail", "salary", "personal", "government", "pension", "tax", "other", "bonus_payment", "cash_management_transfer", "card_bulk_clearing", "credit_card_payment", "trade_settlement_payment", "debit_card_payment", "dividend", "deliver_against_payment", "epayment", "fee_collection_and_interest", "fee_collection", "person_to_person_payment", "government_payment", "hedging_transaction", "irrevocable_credit_card_payment", "irrevocable_debit_card_payment", "intra_company_payment", "interest", "lockbox_transactions", "commercial", "consumer", "other_payment", "pension_payment", "represented", "reimbursement_received_credit_transfer", "receive_against_payment", "salary_payment", "securities", "social_security_benefit", "supplier_payment", "tax_payment", "trade", "treasury_payment", "value_added_tax_payment", "with_holding", "cash_management_sweep_account", "cash_management_top_account", "cash_management_zero_balance_account", "crossborder_mi_payments", "foreign_currency_domestic_transfer", "cash_in_pre_credit", "cash_out_notes_coins", "carrier_guarded_wholesale_valuables" ], "type": "string" }, "billing_request_payment_purpose_code": { "type": "string", "title": "BillingRequestPaymentPurposeCode", "description": "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.\nSee [VRP Commercial Payment Purpose Codes](https://developer.gocardless.com/vrp-commercial-payment-purpose-codes/) for the complete list of valid codes." }, "billing_request_payment_context_code": { "title": "BillingRequestPaymentContextCode", "description": "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.", "enum": [ "billing_goods_and_services_in_advance", "billing_goods_and_services_in_arrears", "face_to_face_point_of_sale", "ecommerce_merchant_initiated_payment", "transfer_to_self", "transfer_to_third_party" ], "type": "string" }, "billing_request_fallback_occurred": { "type": "boolean", "title": "BillingRequestFallbackOccurred", "description": "True if the billing request was completed with direct debit." }, "billing_request_pay_id": { "type": "string", "title": "BillingRequestPayId", "description": "A unique record such as an email address, mobile number or company number, that can be used to make and accept payments." }, "billing_request_payment_currency": { "type": "string", "title": "BillingRequestPaymentCurrency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. `GBP` and `EUR` supported; `GBP` with your customers in the UK and for `EUR` with your customers in supported Eurozone countries only.", "example": "GBP" }, "billing_request_payment_scheme": { "type": "string", "nullable": true, "title": "BillingRequestPaymentScheme", "description": "(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.", "example": "faster_payments" }, "billing_request_currency": { "type": "string", "title": "BillingRequestCurrency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.", "example": "GBP" }, "billing_request_scheme": { "type": "string", "nullable": true, "title": "BillingRequestScheme", "description": "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.", "example": "bacs" }, "billing_request_notification_type": { "type": "string", "title": "BillingRequestNotificationType", "description": "Currently, can only be `email`.", "example": "email", "enum": [ "email" ] }, "billing_request_description": { "type": "string", "nullable": true, "title": "BillingRequestDescription", "description": "A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.\n", "example": "Top-up Payment" }, "billing_request_ach_pad_currency": { "type": "string", "title": "BillingRequestAchPadCurrency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently \"USD\" and \"CAD\" are supported.", "example": "USD" }, "billing_request_charge_date": { "type": "string", "nullable": true, "title": "BillingRequestChargeDate", "description": "A future date on which the payment should be collected. If the date\nis before the next_possible_charge_date on the\n[mandate](#core-endpoints-mandates), it will be automatically rolled\nforwards to that date.", "example": "2014-05-21", "format": "date" }, "billing_request_amount_stringable": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "title": "BillingRequestAmountStringable", "description": "Amount in minor unit (e.g. pence in GBP, cents in EUR).", "example": 1000 }, "billing_request_amount": { "type": "integer", "title": "BillingRequestAmount", "description": "Amount in minor unit (e.g. pence in GBP, cents in EUR).", "example": 1000 }, "billing_request_app_fee_stringable": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "integer" } ], "title": "BillingRequestAppFeeStringable", "description": "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).", "example": 100 }, "billing_request_app_fee": { "type": "integer", "nullable": true, "title": "BillingRequestAppFee", "description": "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).", "example": 100 }, "billing_request_payment_request_links": { "type": "object", "title": "BillingRequestPaymentRequestLinks", "description": "", "properties": { "payment": { "type": "string", "description": "(Optional) ID of the [payment](#core-endpoints-payments) that was created from this payment request." } } }, "billing_request_reference": { "type": "string", "nullable": true, "title": "BillingRequestReference", "description": "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.\n", "example": "some-custom-ref", "maxLength": 18, "minLength": 1 }, "billing_request_funds_settlement": { "title": "BillingRequestFundsSettlement", "description": "This field will decide how GoCardless handles settlement of funds from the customer.\n\n- `managed` will be moved through GoCardless' account, batched, and payed out.\n- `direct` will be a direct transfer from the payer's account to the merchant where\n invoicing will be handled separately.\n", "enum": [ "managed", "direct" ], "type": "string" }, "billing_request_mandate_request_verify": { "title": "BillingRequestMandateRequestVerify", "description": "Verification preference for the mandate. One of:\n\n- `minimum`: only verify if absolutely required, such as when part of scheme rules\n- `recommended`: in addition to `minimum`, use the GoCardless payment intelligence solution to decide if a payer should be verified\n- `when_available`: if verification mechanisms are available, use them\n- `always`: as `when_available`, but fail to create the Billing Request if a mechanism isn't available\n\nBy 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`.\n\nIf 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.\n\nSee [Billing Requests: Creating Verified Mandates](https://developer.gocardless.com/getting-started/billing-requests/verified-mandates/)\nfor more information.", "enum": [ "minimum", "recommended", "when_available", "always" ], "type": "string" }, "billing_request_sweeping": { "type": "boolean", "title": "BillingRequestSweeping", "description": "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" }, "billing_request_payer_requested_dual_signature": { "type": "boolean", "title": "BillingRequestPayerRequestedDualSignature", "description": "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." }, "billing_request_consent_type": { "type": "string", "nullable": true, "title": "BillingRequestConsentType", "description": "This attribute represents the authorisation type between the payer and merchant. It can be set to `one_off`,\n`recurring` or `standing` for ACH scheme. And `single`, `recurring` and `sporadic` for PAD scheme. _Note:_ This is only supported for ACH and PAD schemes.\n" }, "billing_request_mandate_request_links": { "type": "object", "title": "BillingRequestMandateRequestLinks", "description": "", "properties": { "mandate": { "type": "string", "description": "(Optional) ID of the [mandate](#core-endpoints-mandates) that was created from this mandate request. this mandate request.\n" } } }, "billing_request_subscription_request_start_date": { "type": "string", "nullable": true, "title": "BillingRequestSubscriptionRequestStartDate", "description": "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`.\nWhen left blank and `month` or `day_of_month` are provided, this will be set to the date of the first payment.\nIf created without `month` or `day_of_month` this will be set as the mandate's `next_possible_charge_date`.\n", "example": "2014-10-21", "format": "date" }, "billing_request_subscription_request_links": { "type": "object", "title": "BillingRequestSubscriptionRequestLinks", "description": "", "properties": { "subscription": { "type": "string", "description": "(Optional) ID of the [subscription](#core-endpoints-subscriptions) that was created from this subscription request.\n" } } }, "billing_request_subscription_payment_reference": { "type": "string", "nullable": true, "title": "BillingRequestSubscriptionPaymentReference", "description": "An optional payment reference. This will be set as the reference on each payment\ncreated and will appear on your customer's bank statement. See the documentation for\nthe [create payment endpoint](#payments-create-a-payment) for more details.\n\n This API is currently only available for GoCardless Protect+ integrators - please get in touch if you would like to use this API.\n
", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/block_id" }, "block_type": { "$ref": "#/components/schemas/block_block_type" }, "reason_type": { "$ref": "#/components/schemas/block_reason_type" }, "reason_description": { "$ref": "#/components/schemas/block_reason_description" }, "resource_reference": { "$ref": "#/components/schemas/block_resource_reference" }, "active": { "$ref": "#/components/schemas/block_active" }, "created_at": { "$ref": "#/components/schemas/block_created_at" }, "updated_at": { "$ref": "#/components/schemas/block_updated_at" } } }, "block_id": { "type": "string", "title": "BlockId", "description": "Unique identifier, beginning with \"BLC\".", "example": "BLC123" }, "block_identity": { "$ref": "#/components/schemas/block_id" }, "block_block_type": { "type": "string", "title": "BlockBlockType", "description": "Type of entity we will seek to match against when blocking the mandate. This\ncan currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.", "enum": [ "email", "email_domain", "bank_account", "bank_name" ] }, "block_reason_type": { "type": "string", "title": "BlockReasonType", "description": "The reason you wish to block this payer, can currently be one of 'identity_fraud',\n'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the\nabove then 'other' can be selected but you must provide a reason description.", "enum": [ "identity_fraud", "no_intent_to_pay", "unfair_chargeback", "other" ] }, "block_reason_description": { "type": "string", "nullable": true, "title": "BlockReasonDescription", "description": "This field is required if the reason_type is other. It should be a description of\nthe reason for why you wish to block this payer and why it does not align with the\ngiven reason_types. This is intended to help us improve our knowledge of types of\nfraud." }, "block_resource_reference": { "type": "string", "title": "BlockResourceReference", "description": "This field is a reference to the value you wish to block. This may be the raw value\n(in the case of emails or email domains) or the ID of the resource (in the case of\nbank accounts and bank names). This means in order to block a specific bank account\n(even if you wish to block generically by name) it must already have been created as\na resource.", "example": "example@example.com" }, "block_active": { "type": "boolean", "nullable": true, "title": "BlockActive", "description": "Shows if the block is active or disabled. Only active blocks will be used when deciding\nif a mandate should be blocked.", "example": true }, "block_created_at": { "type": "string", "title": "BlockCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this\nresource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "block_updated_at": { "type": "string", "title": "BlockUpdatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this\nresource was updated.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "block_reference_type": { "type": "string", "title": "BlockReferenceType", "description": "Type of entity we will seek to get the associated emails and bank accounts to\ncreate blocks from. This can currently be one of 'customer' or 'mandate'.", "enum": [ "customer", "mandate" ] }, "block_reference_value": { "type": "string", "title": "BlockReferenceValue", "description": "This field is a reference to the entity you wish to block based on its emails\nand bank accounts. This may be the ID of a customer or a mandate. This means in\norder to block by reference the entity must have already been created as a\nresource.", "example": "CU123" }, "block_pagination_meta": { "type": "object", "title": "BlockPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "block_single_resource_response": { "type": "object", "title": "BlockSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "blocks": { "$ref": "#/components/schemas/block" } } }, "block_multi_resource_response": { "type": "object", "title": "BlockMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/block" } }, "meta": { "$ref": "#/components/schemas/block_pagination_meta" } } }, "creditor": { "type": "object", "title": "Creditors", "description": "Each [payment](#core-endpoints-payments) taken through the API is linked to a \"creditor\", to whom the payment is then paid out. In most cases your organisation will have a single \"creditor\", but the API also supports collecting payments on behalf of others.\n\nCurrently, for Anti Money Laundering reasons, any creditors you add must be directly related to your organisation.", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/creditor_id" }, "created_at": { "$ref": "#/components/schemas/creditor_created_at" }, "name": { "$ref": "#/components/schemas/creditor_name" }, "address_line1": { "$ref": "#/components/schemas/creditor_address_line1" }, "address_line2": { "$ref": "#/components/schemas/creditor_address_line2" }, "address_line3": { "$ref": "#/components/schemas/creditor_address_line3" }, "city": { "$ref": "#/components/schemas/creditor_city" }, "region": { "$ref": "#/components/schemas/creditor_region" }, "postal_code": { "$ref": "#/components/schemas/creditor_postal_code" }, "country_code": { "$ref": "#/components/schemas/creditor_country_code" }, "can_create_refunds": { "$ref": "#/components/schemas/creditor_can_create_refunds" }, "bank_reference_prefix": { "$ref": "#/components/schemas/creditor_bank_reference_prefix" }, "links": { "$ref": "#/components/schemas/creditor_links" }, "scheme_identifiers": { "$ref": "#/components/schemas/creditor_scheme_identifiers" }, "logo_url": { "$ref": "#/components/schemas/creditor_logo_url" }, "verification_status": { "$ref": "#/components/schemas/creditor_verification_status" }, "merchant_responsible_for_notifications": { "$ref": "#/components/schemas/creditor_merchant_responsible_for_notifications" }, "mandate_imports_enabled": { "$ref": "#/components/schemas/creditor_mandate_imports_enabled" }, "custom_payment_pages_enabled": { "$ref": "#/components/schemas/creditor_custom_payment_pages_enabled" }, "fx_payout_currency": { "$ref": "#/components/schemas/creditor_fx_payout_currency" }, "creditor_type": { "$ref": "#/components/schemas/creditor_creditor_type" } } }, "creditor_id": { "type": "string", "title": "CreditorId", "description": "Unique identifier, beginning with \"CR\".", "example": "CR123" }, "creditor_identity": { "$ref": "#/components/schemas/creditor_id" }, "creditor_created_at": { "type": "string", "title": "CreditorCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "creditor_name": { "type": "string", "title": "CreditorName", "description": "The creditor's trading name.", "example": "Acme" }, "creditor_address_line1": { "type": "string", "nullable": true, "title": "CreditorAddressLine1", "description": "The first line of the creditor's address.", "example": "338-346 Goswell Road" }, "creditor_address_line2": { "type": "string", "nullable": true, "title": "CreditorAddressLine2", "description": "The second line of the creditor's address.", "example": "Islington" }, "creditor_address_line3": { "type": "string", "nullable": true, "title": "CreditorAddressLine3", "description": "The third line of the creditor's address." }, "creditor_city": { "type": "string", "nullable": true, "title": "CreditorCity", "description": "The city of the creditor's address.", "example": "London" }, "creditor_region": { "type": "string", "nullable": true, "title": "CreditorRegion", "description": "The creditor's address region, county or department." }, "creditor_postal_code": { "type": "string", "nullable": true, "title": "CreditorPostalCode", "description": "The creditor's postal code.", "example": "EC1V 7LQ" }, "creditor_country_code": { "type": "string", "nullable": true, "title": "CreditorCountryCode", "description": "[ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)", "example": "GB" }, "creditor_creditor_type": { "title": "CreditorTypeNullable", "description": "The type of business of the creditor. Currently, `individual`, `company`, `charity`, `partnership`, and `trust` are supported.", "example": "company", "enum": [ "company", "individual", "charity", "partnership", "trust" ], "nullable": true, "type": "string" }, "creditor_logo_url": { "type": "string", "nullable": true, "title": "CreditorLogoUrl", "description": "URL for the creditor's logo, which may be shown on their payment pages.", "example": "https://uploads.gocardless.com/logo.png" }, "creditor_mandate_imports_enabled": { "type": "boolean", "title": "CreditorMandateImportsEnabled", "description": "Boolean value indicating whether creditor has the [Mandate Imports](#core-endpoints-mandate-imports) functionality enabled.", "example": true }, "creditor_merchant_responsible_for_notifications": { "type": "boolean", "title": "CreditorMerchantResponsibleForNotifications", "description": "Boolean value indicating whether the organisation is responsible for sending all customer notifications (note this is separate from the functionality described [here](/getting-started/api/handling-customer-notifications/)). If you are a partner app, and this value is true, you should not send notifications on behalf of this organisation.", "example": true }, "creditor_custom_payment_pages_enabled": { "type": "boolean", "title": "CreditorCustomPaymentPagesEnabled", "description": "Boolean value indicating whether creditor has the [Custom Payment Pages](https://hub.gocardless.com/s/article/Custom-payment-pages) functionality enabled.", "example": true }, "creditor_verification_status": { "title": "CreditorVerificationStatus", "description": "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](/getting-started/partners/helping-your-users-get-verified/). One of:\n\n- `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.\n- `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.\n- `action_required`: The creditor needs to provide further information to verify their account so they can receive payouts, and should visit the verification flow.", "example": "action_required", "enum": [ "successful", "in_review", "action_required" ], "type": "string" }, "creditor_scheme_identifiers": { "type": "array", "title": "CreditorSchemeIdentifiers", "description": "An array of the scheme identifiers this creditor can create mandates against.\n\nThe 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](#appendix-compliance-requirements) for more details.", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/scheme_identifier_id" }, "created_at": { "$ref": "#/components/schemas/scheme_identifier_created_at" }, "name": { "$ref": "#/components/schemas/scheme_identifier_name" }, "scheme": { "$ref": "#/components/schemas/scheme_identifier_scheme" }, "reference": { "$ref": "#/components/schemas/scheme_identifier_reference" }, "status": { "$ref": "#/components/schemas/scheme_identifier_status" }, "minimum_advance_notice": { "$ref": "#/components/schemas/scheme_identifier_minimum_advance_notice" }, "address_line1": { "$ref": "#/components/schemas/scheme_identifier_address_line1" }, "address_line2": { "$ref": "#/components/schemas/scheme_identifier_address_line2" }, "address_line3": { "$ref": "#/components/schemas/scheme_identifier_address_line3" }, "city": { "$ref": "#/components/schemas/scheme_identifier_city" }, "region": { "$ref": "#/components/schemas/scheme_identifier_region" }, "postal_code": { "$ref": "#/components/schemas/scheme_identifier_postal_code" }, "country_code": { "$ref": "#/components/schemas/scheme_identifier_country_code" }, "email": { "$ref": "#/components/schemas/scheme_identifier_email" }, "phone_number": { "$ref": "#/components/schemas/scheme_identifier_phone_number" }, "currency": { "$ref": "#/components/schemas/scheme_identifier_currency" }, "can_specify_mandate_reference": { "$ref": "#/components/schemas/scheme_identifier_can_specify_mandate_reference" } } } }, "creditor_can_create_refunds": { "type": "boolean", "title": "CreditorCanCreateRefunds", "description": "Boolean indicating whether the creditor is permitted to create refunds." }, "creditor_bank_reference_prefix": { "type": "string", "title": "CreditorBankReferencePrefix", "description": "Prefix for the bank reference of payouts sent to this creditor. For instance, if\nthe creditor's `bank_reference_prefix` was `ACME`, the bank reference of a payout\nsent to that creditor could be `ACME-8G7Q8`.\n\nThis prefix is also used for refunds in EUR and GBP.\n", "example": "ACME" }, "creditor_fx_payout_currency": { "title": "FxCurrency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) 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.", "example": "EUR", "enum": [ "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK", "USD" ], "nullable": true, "type": "string" }, "creditor_links": { "type": "object", "title": "CreditorLinks", "description": "", "properties": { "default_aud_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in AUD.", "example": "BA234" }, "default_gbp_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in GBP.", "example": "BA123" }, "default_eur_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in EUR.", "example": "BA456" }, "default_sek_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in SEK.", "example": "BA789" }, "default_dkk_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in DKK.", "example": "BA790" }, "default_nzd_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in NZD.", "example": "BA791" }, "default_cad_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in CAD.", "example": "BA792" }, "default_usd_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in USD.", "example": "BA792" } } }, "creditor_pagination_meta": { "type": "object", "title": "CreditorPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "creditor_single_resource_response": { "type": "object", "title": "CreditorSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "creditors": { "$ref": "#/components/schemas/creditor" } } }, "creditor_multi_resource_response": { "type": "object", "title": "CreditorMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "creditors": { "type": "array", "items": { "$ref": "#/components/schemas/creditor" } }, "meta": { "$ref": "#/components/schemas/creditor_pagination_meta" } } }, "creditor_bank_account": { "type": "object", "title": "Creditor Bank Accounts", "description": "Creditor Bank Accounts hold the bank details of a [creditor](#core-endpoints-creditors). These are the bank accounts which your [payouts](#core-endpoints-payouts) will be sent to.\n\nNote that creditor bank accounts must be unique, and so you will encounter a `bank_account_exists` error if you try to create a duplicate bank account. You may wish to handle this by updating the existing record instead, the ID of which will be provided as `links[creditor_bank_account]` in the error response.\n\nRestricted: This API is not available for partner integrations.
", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/creditor_bank_account_id" }, "created_at": { "$ref": "#/components/schemas/creditor_bank_account_created_at" }, "account_holder_name": { "$ref": "#/components/schemas/creditor_bank_account_account_holder_name" }, "account_number_ending": { "$ref": "#/components/schemas/creditor_bank_account_account_number_ending" }, "account_type": { "$ref": "#/components/schemas/creditor_bank_account_account_type" }, "country_code": { "$ref": "#/components/schemas/creditor_bank_account_country_code" }, "currency": { "$ref": "#/components/schemas/creditor_bank_account_currency" }, "bank_name": { "$ref": "#/components/schemas/creditor_bank_account_bank_name" }, "enabled": { "$ref": "#/components/schemas/creditor_bank_account_enabled" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "links": { "$ref": "#/components/schemas/creditor_bank_account_links" }, "verification_status": { "$ref": "#/components/schemas/creditor_bank_account_verification_status" } } }, "creditor_bank_account_id": { "type": "string", "title": "CreditorBankAccountId", "description": "Unique identifier, beginning with \"BA\".", "example": "BA123" }, "creditor_bank_account_identity": { "$ref": "#/components/schemas/creditor_bank_account_id" }, "creditor_bank_account_created_at": { "type": "string", "title": "CreditorBankAccountCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "creditor_bank_account_account_holder_name": { "type": "string", "title": "CreditorBankAccountAccountHolderName", "description": "Name of the account holder, as known by the bank. Usually this is the same as the name stored with the linked [creditor](#core-endpoints-creditors). This field will be transliterated, upcased and truncated to 18 characters.", "example": "Billie Jean" }, "creditor_bank_account_account_number_ending": { "type": "string", "nullable": true, "title": "CreditorBankAccountAccountNumberEnding", "description": "The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.", "example": "1234" }, "creditor_bank_account_country_code": { "type": "string", "nullable": true, "title": "CreditorBankAccountCountryCode", "description": "[ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required.", "example": "GB" }, "creditor_bank_account_currency": { "type": "string", "nullable": true, "title": "CreditorBankAccountCurrency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently \"AUD\", \"CAD\", \"DKK\", \"EUR\", \"GBP\", \"NZD\", \"SEK\" and \"USD\" are supported.", "example": "EUR" }, "creditor_bank_account_bank_name": { "type": "string", "nullable": true, "title": "CreditorBankAccountBankName", "description": "Name of bank, taken from the bank details.", "example": "BARCLAYS BANK PLC" }, "creditor_bank_account_enabled": { "type": "boolean", "title": "CreditorBankAccountEnabled", "description": "Boolean value showing whether the bank account is enabled or disabled.", "example": true }, "creditor_bank_account_account_number": { "type": "string", "nullable": true, "title": "CreditorBankAccountAccountNumber", "description": "Bank account number - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`.", "example": "55779911" }, "creditor_bank_account_bank_code": { "type": "string", "nullable": true, "title": "CreditorBankAccountBankCode", "description": "Bank code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`." }, "creditor_bank_account_branch_code": { "type": "string", "nullable": true, "title": "CreditorBankAccountBranchCode", "description": "Branch code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`.", "example": "20-00-00" }, "creditor_bank_account_account_type": { "title": "BankAccountType", "description": "Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information.", "example": "savings", "enum": [ "savings", "checking" ], "nullable": true, "type": "string" }, "creditor_bank_account_iban": { "type": "string", "nullable": true, "title": "CreditorBankAccountIban", "description": "International Bank Account Number. Alternatively you can provide [local details](#appendix-local-bank-details). IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply [local details](#local-bank-details-sweden).", "example": "GB60BARC20000055779911" }, "creditor_bank_account_set_as_default_payout_account": { "type": "boolean", "title": "CreditorBankAccountSetAsDefaultPayoutAccount", "description": "Defaults to `true`. When this is set to `true`, it will cause this bank account to be set as the account that GoCardless will pay out to." }, "creditor_bank_account_verification_status": { "title": "CreditorBankAccountVerificationStatus", "description": "Verification status of the Bank Account. Can be one of `pending`, `in_review` or `successful`", "example": "successful", "enum": [ "pending", "in_review", "successful", "could_not_verify" ], "type": "string" }, "creditor_bank_account_links": { "type": "object", "title": "CreditorBankAccountLinks", "description": "", "properties": { "creditor": { "type": "string", "description": "ID of the [creditor](#core-endpoints-creditors) that owns this bank account.", "example": "CR123" } } }, "creditor_bank_account_pagination_meta": { "type": "object", "title": "CreditorBankAccountPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "creditor_bank_account_single_resource_response": { "type": "object", "title": "CreditorBankAccountSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "creditor_bank_accounts": { "$ref": "#/components/schemas/creditor_bank_account" } } }, "creditor_bank_account_multi_resource_response": { "type": "object", "title": "CreditorBankAccountMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "creditor_bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/creditor_bank_account" } }, "meta": { "$ref": "#/components/schemas/creditor_bank_account_pagination_meta" } } }, "currency_exchange_rate": { "type": "object", "title": "Currency Exchange Rates", "description": "Currency exchange rates from our foreign exchange provider.", "additionalProperties": true, "properties": { "source": { "$ref": "#/components/schemas/currency_exchange_rate_source" }, "target": { "$ref": "#/components/schemas/currency_exchange_rate_target" }, "rate": { "$ref": "#/components/schemas/currency_exchange_rate_rate" }, "time": { "$ref": "#/components/schemas/currency_exchange_rate_time" } } }, "currency_exchange_rate_source": { "type": "string", "title": "CurrencyExchangeRateSource", "description": "Source currency", "example": "GBP" }, "currency_exchange_rate_target": { "type": "string", "title": "CurrencyExchangeRateTarget", "description": "Target currency", "example": "EUR" }, "currency_exchange_rate_rate": { "type": "string", "title": "CurrencyExchangeRateRate", "description": "The exchange rate from the source to target currencies provided with up to 10 decimal places.", "example": "1.1234567890" }, "currency_exchange_rate_time": { "type": "string", "title": "CurrencyExchangeRateTime", "description": "Time at which the rate was retrieved from the provider.", "example": "2014-01-01T12:00:00Z", "format": "date-time" }, "currency_exchange_rate_pagination_meta": { "type": "object", "title": "CurrencyExchangeRatePaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "currency_exchange_rate_multi_resource_response": { "type": "object", "title": "CurrencyExchangeRateMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "currency_exchange_rates": { "type": "array", "items": { "$ref": "#/components/schemas/currency_exchange_rate" } }, "meta": { "$ref": "#/components/schemas/currency_exchange_rate_pagination_meta" } } }, "customer": { "type": "object", "title": "Customers", "description": "Customer objects hold the contact details for a customer. A customer can have several [customer bank accounts](#core-endpoints-customer-bank-accounts), which in turn can have several Direct Debit [mandates](#core-endpoints-mandates).", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/customer_id" }, "created_at": { "$ref": "#/components/schemas/customer_created_at" }, "email": { "$ref": "#/components/schemas/customer_email" }, "given_name": { "$ref": "#/components/schemas/customer_given_name" }, "family_name": { "$ref": "#/components/schemas/customer_family_name" }, "company_name": { "$ref": "#/components/schemas/customer_company_name" }, "address_line1": { "$ref": "#/components/schemas/customer_address_line1" }, "address_line2": { "$ref": "#/components/schemas/customer_address_line2" }, "address_line3": { "$ref": "#/components/schemas/customer_address_line3" }, "city": { "$ref": "#/components/schemas/customer_city" }, "region": { "$ref": "#/components/schemas/customer_region" }, "postal_code": { "$ref": "#/components/schemas/customer_postal_code" }, "country_code": { "$ref": "#/components/schemas/customer_country_code" }, "language": { "$ref": "#/components/schemas/customer_language" }, "phone_number": { "$ref": "#/components/schemas/customer_phone_number" }, "swedish_identity_number": { "$ref": "#/components/schemas/customer_swedish_identity_number" }, "danish_identity_number": { "$ref": "#/components/schemas/customer_danish_identity_number" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } }, "customer_metadata": { "type": "object", "title": "CustomerMetadata", "description": "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_sort_direction": { "title": "SortDirection", "description": "The direction to sort in.\nOne of:\n\n- `asc`\n- `desc`", "enum": [ "asc", "desc" ], "type": "string" }, "customer_sort_field": { "title": "SortField", "description": "Field by which to sort records.\nOne of:\n\n- `name`\n- `company_name`\n- `created_at`", "enum": [ "name", "company_name", "created_at" ], "type": "string" }, "customer_id": { "type": "string", "title": "CustomerId", "description": "Unique identifier, beginning with \"CU\".", "example": "CU123" }, "customer_identity": { "$ref": "#/components/schemas/customer_id" }, "customer_created_at": { "type": "string", "title": "CustomerCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "customer_email": { "type": "string", "nullable": true, "title": "CustomerEmail", "description": "Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.", "example": "user@example.com", "maxLength": 255 }, "customer_given_name": { "type": "string", "nullable": true, "title": "CustomerGivenName", "description": "Customer's first name. Required unless a `company_name` is provided.", "example": "Frank", "maxLength": 255 }, "customer_family_name": { "type": "string", "nullable": true, "title": "CustomerFamilyName", "description": "Customer's surname. Required unless a `company_name` is provided.", "example": "Osborne", "maxLength": 255 }, "customer_company_name": { "type": "string", "nullable": true, "title": "CustomerCompanyName", "description": "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\").", "example": "Hamilton Trading Ltd.", "maxLength": 255 }, "customer_address_line1": { "type": "string", "nullable": true, "title": "CustomerAddressLine1", "description": "The first line of the customer's address.", "example": "221B Baker Street", "maxLength": 255 }, "customer_address_line2": { "type": "string", "nullable": true, "title": "CustomerAddressLine2", "description": "The second line of the customer's address.", "example": "Marylebone", "maxLength": 255 }, "customer_address_line3": { "type": "string", "nullable": true, "title": "CustomerAddressLine3", "description": "The third line of the customer's address.", "example": "City of Westminster", "maxLength": 255 }, "customer_city": { "type": "string", "nullable": true, "title": "CustomerCity", "description": "The city of the customer's address.", "example": "London", "maxLength": 255 }, "customer_region": { "type": "string", "nullable": true, "title": "CustomerRegion", "description": "The customer's address region, county or department. For US customers a 2 letter [ISO3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) state code is required (e.g. `CA` for California).", "example": "Greater London", "maxLength": 255 }, "customer_postal_code": { "type": "string", "nullable": true, "title": "CustomerPostalCode", "description": "The customer's postal code.", "example": "NW1 6XE", "maxLength": 20 }, "customer_country_code": { "type": "string", "nullable": true, "title": "CustomerCountryCode", "description": "[ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)", "example": "GB", "maxLength": 2 }, "customer_language": { "type": "string", "nullable": true, "title": "CustomerLanguage", "description": "[ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see [compliance requirements](#appendix-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\".", "example": "en", "maxLength": 2 }, "customer_phone_number": { "type": "string", "nullable": true, "title": "CustomerPhoneNumber", "description": "[ITU E.123](https://en.wikipedia.org/wiki/E.123) formatted phone number, including country code.", "example": "+64 4 817 9999", "maxLength": 30 }, "customer_swedish_identity_number": { "type": "string", "nullable": true, "title": "CustomerSwedishIdentityNumber", "description": "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.", "example": "556564-5404", "maxLength": 12 }, "customer_danish_identity_number": { "type": "string", "nullable": true, "title": "CustomerDanishIdentityNumber", "description": "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).", "example": "2205506218", "maxLength": 10 }, "customer_currency": { "title": "Currency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently \"AUD\", \"CAD\", \"DKK\", \"EUR\", \"GBP\", \"NZD\", \"SEK\" and \"USD\" are supported.", "example": "EUR", "enum": [ "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK", "USD" ], "type": "string" }, "customer_pagination_meta": { "type": "object", "title": "CustomerPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "customer_single_resource_response": { "type": "object", "title": "CustomerSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "customers": { "$ref": "#/components/schemas/customer" } } }, "customer_multi_resource_response": { "type": "object", "title": "CustomerMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/customer" } }, "meta": { "$ref": "#/components/schemas/customer_pagination_meta" } } }, "customer_bank_account": { "type": "object", "title": "Customer Bank Accounts", "description": "Customer Bank Accounts hold the bank details of a [customer](#core-endpoints-customers). They always belong to a [customer](#core-endpoints-customers), and may be linked to several Direct Debit [mandates](#core-endpoints-mandates).\n\nNote that customer bank accounts must be unique, and so you will encounter a `bank_account_exists` error if you try to create a duplicate bank account. You may wish to handle this by updating the existing record instead, the ID of which will be provided as `links[customer_bank_account]` in the error response.\n\n_Note:_ To ensure the customer's bank accounts are valid, verify them first\nusing\n[bank_details_lookups](#bank-details-lookups-perform-a-bank-details-lookup),\nbefore proceeding with creating the accounts", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/customer_bank_account_id" }, "created_at": { "$ref": "#/components/schemas/customer_bank_account_created_at" }, "account_holder_name": { "$ref": "#/components/schemas/customer_bank_account_account_holder_name" }, "account_number_ending": { "$ref": "#/components/schemas/customer_bank_account_account_number_ending" }, "account_type": { "$ref": "#/components/schemas/customer_bank_account_account_type" }, "country_code": { "$ref": "#/components/schemas/customer_bank_account_country_code" }, "currency": { "$ref": "#/components/schemas/customer_bank_account_currency" }, "bank_name": { "$ref": "#/components/schemas/customer_bank_account_bank_name" }, "bank_account_token": { "$ref": "#/components/schemas/customer_bank_account_bank_account_token" }, "enabled": { "$ref": "#/components/schemas/customer_bank_account_enabled" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "links": { "$ref": "#/components/schemas/customer_bank_account_links" }, "trusted_recipient": { "$ref": "#/components/schemas/customer_bank_account_trusted_recipient" }, "payer_name_verification_result": { "$ref": "#/components/schemas/customer_bank_account_payer_name_verification_result" } } }, "customer_bank_account_id": { "type": "string", "title": "CustomerBankAccountId", "description": "Unique identifier, beginning with \"BA\".", "example": "BA123" }, "customer_bank_account_identity": { "$ref": "#/components/schemas/customer_bank_account_id" }, "customer_bank_account_created_at": { "type": "string", "title": "CustomerBankAccountCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "customer_bank_account_account_holder_name": { "type": "string", "title": "CustomerBankAccountAccountHolderName", "description": "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](#javascript-flow-customer-bank-account-tokens).", "example": "Billie Jean" }, "customer_bank_account_account_number_ending": { "type": "string", "nullable": true, "title": "CustomerBankAccountAccountNumberEnding", "description": "The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.", "example": "1234" }, "customer_bank_account_country_code": { "type": "string", "nullable": true, "title": "CustomerBankAccountCountryCode", "description": "[ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required.", "example": "GB" }, "customer_bank_account_currency": { "type": "string", "nullable": true, "title": "CustomerBankAccountCurrency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently \"AUD\", \"CAD\", \"DKK\", \"EUR\", \"GBP\", \"NZD\", \"SEK\" and \"USD\" are supported.", "example": "EUR" }, "customer_bank_account_bank_name": { "type": "string", "nullable": true, "title": "CustomerBankAccountBankName", "description": "Name of bank, taken from the bank details.", "example": "BARCLAYS BANK PLC" }, "customer_bank_account_enabled": { "type": "boolean", "title": "CustomerBankAccountEnabled", "description": "Boolean value showing whether the bank account is enabled or disabled.", "example": true }, "customer_bank_account_account_number": { "type": "string", "nullable": true, "title": "CustomerBankAccountAccountNumber", "description": "Bank account number - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`.", "example": "55779911" }, "customer_bank_account_account_type": { "title": "BankAccountType", "description": "Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information.", "example": "savings", "enum": [ "savings", "checking" ], "nullable": true, "type": "string" }, "customer_bank_account_bank_code": { "type": "string", "nullable": true, "title": "CustomerBankAccountBankCode", "description": "Bank code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`." }, "customer_bank_account_bank_account_token": { "type": "string", "nullable": true, "title": "CustomerBankAccountBankAccountToken", "description": "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.", "example": "bat_f975ab3c-ecee-47a1-9590-5bb1d56fa113" }, "customer_bank_account_branch_code": { "type": "string", "nullable": true, "title": "CustomerBankAccountBranchCode", "description": "Branch code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`.", "example": "20-00-00" }, "customer_bank_account_iban": { "type": "string", "nullable": true, "title": "CustomerBankAccountIban", "description": "International Bank Account Number. Alternatively you can provide [local details](#appendix-local-bank-details). IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply [local details](#local-bank-details-sweden).", "example": "GB60BARC20000055779911" }, "customer_bank_account_trusted_recipient": { "type": "boolean", "title": "CustomerBankAccountTrustedRecipient", "description": "Whether this customer bank account is registered as a trusted recipient for Outbound Payments. Only present when the feature is enabled for the organisation.", "example": true }, "customer_bank_account_payer_name_verification_result": { "type": "string", "title": "CustomerBankAccountPayerNameVerificationResult", "description": "The result of the payer name verification check performed when the bank account was created. Only present if a check was performed.\n\n- `full`: The name provided matches the name held by the bank.\n- `close`: The name provided is a close but not exact match to the name held by the bank.\n- `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.", "example": "full", "enum": [ "full", "close", "cannot_perform_verification" ] }, "customer_bank_account_links": { "type": "object", "title": "CustomerBankAccountLinks", "description": "", "properties": { "customer": { "type": "string", "description": "ID of the [customer](#core-endpoints-customers) that owns this bank account." } } }, "customer_bank_account_pagination_meta": { "type": "object", "title": "CustomerBankAccountPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "customer_bank_account_single_resource_response": { "type": "object", "title": "CustomerBankAccountSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "customer_bank_accounts": { "$ref": "#/components/schemas/customer_bank_account" } } }, "customer_bank_account_multi_resource_response": { "type": "object", "title": "CustomerBankAccountMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "customer_bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/customer_bank_account" } }, "meta": { "$ref": "#/components/schemas/customer_bank_account_pagination_meta" } } }, "customer_notification": { "type": "object", "title": "Customer Notifications", "description": "Customer Notifications represent the notification which is due to be sent to a customer\nafter an event has happened. The event, the resource and the customer to be notified\nare all identified in the `links` property.\n\nOnly `payment_created`, `mandate_created` and `subscription_created` notifications are\nsupported.\n\nNote that these are ephemeral records - once the notification has been actioned in some\nway, it is no longer visible using this API.\n\nRestricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.
", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/customer_notification_id" }, "type": { "$ref": "#/components/schemas/customer_notification_type" }, "action_taken": { "$ref": "#/components/schemas/customer_notification_action_taken" }, "action_taken_at": { "$ref": "#/components/schemas/customer_notification_action_taken_at" }, "action_taken_by": { "$ref": "#/components/schemas/customer_notification_action_taken_by" }, "links": { "$ref": "#/components/schemas/customer_notification_links" } } }, "customer_notification_id": { "type": "string", "title": "CustomerNotificationId", "description": "The id of the notification.", "example": "EV1D18JEXAMPLE" }, "customer_notification_identity": { "$ref": "#/components/schemas/customer_notification_id" }, "customer_notification_type": { "type": "string", "title": "CustomerNotificationType", "description": "The type of notification the customer shall receive.\n\nNote: today, only `payment_created`, `mandate_created` and `subscription_created`\nnotifications are actually supported. The remaining values are reserved for now.\n\nMaking a request for an event of any other type will get a `403` `customer_notifications_notification_type_forbidden` error.", "example": "payment_created", "enum": [ "payment_created", "payment_cancelled", "mandate_created", "mandate_blocked", "subscription_created", "subscription_cancelled", "instalment_schedule_created", "instalment_schedule_cancelled" ] }, "customer_notification_action_taken": { "type": "string", "title": "CustomerNotificationActionTaken", "description": "The action that was taken on the notification. Currently this can only be `handled`,\nwhich means the integrator sent the notification themselves.\n", "enum": [ "handled" ] }, "customer_notification_action_taken_at": { "type": "string", "nullable": true, "title": "CustomerNotificationActionTakenAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this\naction was taken.", "format": "date-time" }, "customer_notification_action_taken_by": { "type": "string", "nullable": true, "title": "CustomerNotificationActionTakenBy", "description": "A string identifying the integrator who was able to handle this notification." }, "customer_notification_pagination_meta": { "type": "object", "title": "CustomerNotificationPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "customer_notification_links": { "type": "object", "title": "CustomerNotificationLinks", "description": "", "additionalProperties": false, "required": [ "customer", "event" ], "properties": { "payment": { "type": "string", "description": "The identifier of the related payment.", "example": "PM123" }, "mandate": { "type": "string", "description": "The identifier of the related mandate.", "example": "MD123" }, "refund": { "type": "string", "description": "The identifier of the related refund.", "example": "RF123" }, "subscription": { "type": "string", "description": "The identifier of the related subscription.", "example": "SB123" }, "customer": { "type": "string", "description": "The customer who should be contacted with this notification.", "example": "CU123" }, "event": { "type": "string", "description": "The event that triggered the notification to be scheduled.", "example": "EV123" } } }, "customer_notification_single_resource_response": { "type": "object", "title": "CustomerNotificationSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "customer_notifications": { "$ref": "#/components/schemas/customer_notification" } } }, "event": { "type": "object", "title": "Events", "description": "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](#event-types) for a complete list of event types.\nImportant: Events older than 18 months will be archived and no longer accessible via the API or exports. Archival will begin no sooner than 1 August 2026 in sandbox environments, and no sooner than 1 October 2026 in live environments. Events within the 18-month window are unaffected. If you need archived data, contact GoCardless support.
", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/event_id" }, "created_at": { "$ref": "#/components/schemas/event_created_at" }, "resource_type": { "$ref": "#/components/schemas/event_resource_type" }, "action": { "$ref": "#/components/schemas/event_action" }, "customer_notifications": { "$ref": "#/components/schemas/event_customer_notifications" }, "details": { "$ref": "#/components/schemas/event_details" }, "metadata": { "$ref": "#/components/schemas/event_metadata" }, "resource_metadata": { "$ref": "#/components/schemas/event_resource_metadata" }, "source": { "$ref": "#/components/schemas/event_source" }, "links": { "$ref": "#/components/schemas/event_links" } } }, "event_id": { "type": "string", "title": "EventId", "description": "Unique identifier, beginning with \"EV\".", "example": "EV123" }, "event_identity": { "$ref": "#/components/schemas/event_id" }, "event_created_at": { "type": "string", "title": "EventCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "event_customer_notifications": { "type": "array", "nullable": true, "title": "EventCustomerNotifications", "description": "Present only in webhooks when an integrator is authorised to send their own\nnotifications. See [here](/getting-started/api/handling-customer-notifications/)\nfor further information.\n", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/customer_notification_identity" }, "type": { "type": "string", "description": "See [here](#core-endpoints-customer-notifications) for a complete list of customer notification types." }, "mandatory": { "type": "boolean", "description": "Whether or not the notification must be sent." }, "deadline": { "type": "string", "description": "Time after which GoCardless will send the notification by email.", "format": "date-time" } } } }, "event_include_resource_type": { "title": "EventIncludeResourceType", "description": "The resource type of a linked resource that can be requested via the `include` query parameter.", "enum": [ "billing_request", "creditor", "customer", "instalment_schedule", "mandate", "outbound_payment", "payer_authorisation", "payment", "payment_account_transaction", "payout", "refund", "scheme_identifier", "subscription" ], "type": "string" }, "event_resource_type": { "title": "EventResourceType", "description": "The resource type for this event.", "example": "mandates", "enum": [ "billing_requests", "creditors", "customers", "exports", "instalment_schedules", "mandates", "organisations", "outbound_payments", "payer_authorisations", "payments", "payment_account_transactions", "payouts", "refunds", "scheme_identifiers", "subscriptions" ], "type": "string" }, "event_action": { "type": "string", "title": "EventAction", "description": "What has happened to the resource. See [Event Types](#event-types) for the possible actions.", "example": "cancelled" }, "event_details": { "type": "object", "title": "EventDetails", "description": "", "properties": { "origin": { "description": "Who initiated the event. One of:\n\n- `bank`: this event was triggered by a report from the banks\n- `gocardless`: this event was performed by GoCardless automatically\n- `api`: this event was triggered by an API endpoint\n- `customer`: this event was triggered by a Customer\n- `payer`: this event was triggered by a Payer", "example": "bank", "enum": [ "bank", "api", "gocardless", "customer", "payer" ], "type": "string" }, "cause": { "type": "string", "description": "What triggered the event. _Note:_ `cause` is our simplified and predictable key indicating what triggered the event.", "example": "bank_account_disabled" }, "description": { "type": "string", "description": "Human readable description of the cause. _Note:_ Changes to event descriptions are not considered breaking.", "example": "Customer's bank account closed" }, "scheme": { "description": "A bank payment scheme. Set when a bank is the origin of the event.", "example": "bacs", "enum": [ "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_cor1", "sepa_credit_transfer", "sepa_instant_credit_transfer" ], "nullable": true, "type": "string" }, "reason_code": { "type": "string", "description": "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](https://gocardless.com/direct-debit/receiving-messages) for information on the meanings of different reason codes. _Note:_ `reason_code` is payment scheme-specific and can be inconsistent between banks.", "example": "ADDACS-B" }, "will_attempt_retry": { "type": "boolean", "description": "Whether the payment will be retried automatically. Set on a payment failed event.", "example": true }, "not_retried_reason": { "type": "string", "description": "When will_attempt_retry is set to false, this field will contain\nthe reason the payment was not retried. This can be one of:\n\n- `failure_filter_applied`: The payment won't be intelligently retried as there is a high likelihood of failure on retry.\n- `other`: The payment won't be intelligently retried due to any other reason.", "example": "failure_filter_applied" }, "bank_account_id": { "type": "string", "description": "When we send a creditor `new_payout_currency_added` webhook, we also send the bank account id of the new account", "example": "BA123" }, "currency": { "type": "string", "description": "When we send a creditor `new_payout_currency_added` webhook, we also send the currency of the new account", "example": "GBP" }, "property": { "type": "string", "description": "When we send a creditor `creditor_updated` webhook, this tells you which property on the creditor has been updated", "example": "fx_payout_currency" }, "item_count": { "type": "integer", "description": "Count of rows in the csv. This is sent for export events", "example": 10 } } }, "event_metadata": { "type": "object", "title": "EventMetadata", "description": "The metadata that was passed when making the API request that triggered the event\n(for instance, cancelling a mandate).\n\nThis field will only be populated if the `details[origin]` field is `api` otherwise it will be an empty object.\n" }, "event_resource_metadata": { "type": "object", "title": "EventResourceMetadata", "description": "The metadata of the resource that the event is for. For example, this field will have the same\nvalue of the `mandate[metadata]` field on the response you would receive from performing a GET request on a mandate.\n" }, "event_source": { "type": "object", "title": "EventSource", "description": "Audit information about the source of the event.", "properties": { "type": { "description": "The type of the event's source.", "enum": [ "app", "user", "gc_team", "access_token", "billing_request", "billing_request_flow", "dropin", "hosted_payment_page" ], "type": "string" }, "name": { "type": "string", "description": "The name of the event's source.", "example": "Joe Bloggs" } } }, "event_links": { "type": "object", "title": "EventLinks", "description": "", "properties": { "billing_request": { "type": "string", "description": "ID of a [billing request](#billing-requests-billing-requests).", "example": "BRQ123" }, "billing_request_flow": { "type": "string", "description": "ID of a [billing request flow](#billing-requests-billing-request-flows).", "example": "BRF123" }, "bank_authorisation": { "type": "string", "description": "ID of a [bank authorisation](#billing-requests-bank-authorisations).", "example": "BAU123" }, "payment_request_payment": { "type": "string", "description": "If `resource_type` is `billing_requests`, this is the ID of the [payment](#core-endpoints-payments) which has been created for Pay by Bank.", "example": "PM123" }, "mandate_request": { "type": "string", "description": "This is the id of the mandate request associated to this event", "example": "MRQ123" }, "mandate_request_mandate": { "type": "string", "description": "If `resource_type` is `billing_requests`, this is the ID of the [mandate](#core-endpoints-mandates) which has been created.", "example": "MD123" }, "customer": { "type": "string", "description": "ID of a [customer](#core-endpoints-customers).", "example": "CU123" }, "customer_bank_account": { "type": "string", "description": "ID of a [customer bank account](#core-endpoints-customer-bank-accounts).", "example": "BA123" }, "payment": { "type": "string", "description": "If `resource_type` is `payments`, this is the ID of the [payment](#core-endpoints-payments) which has been updated.", "example": "PM123" }, "mandate": { "type": "string", "description": "If `resource_type` is `mandates`, this is the ID of the [mandate](#core-endpoints-mandates) which has been updated.", "example": "MD123" }, "payer_authorisation": { "type": "string", "description": "ID of a [payer authorisation](#core-endpoints-payer-authorisations).", "example": "PAU123" }, "payout": { "type": "string", "description": "If `resource_type` is `payouts`, this is the ID of the [payout](#core-endpoints-payouts) which has been updated.", "example": "PO123" }, "refund": { "type": "string", "description": "If `resource_type` is `refunds`, this is the ID of the [refund](#core-endpoints-refunds) which has been updated.", "example": "RF123" }, "subscription": { "type": "string", "description": "If `resource_type` is `subscription`, this is the ID of the [subscription](#core-endpoints-subscriptions) which has been updated.", "example": "SB123" }, "instalment_schedule": { "type": "string", "description": "If `resource_type` is `instalment_schedule`, this is the ID of the [instalment schedule](#core-endpoints-instalment-schedules) which has been updated.", "example": "IS123" }, "creditor": { "type": "string", "description": "If `resource_type` is `creditor`, this is the ID of the [creditor](#core-endpoints-creditors) which has been updated.", "example": "CR123" }, "parent_event": { "type": "string", "description": "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.", "example": "EV123" }, "previous_customer_bank_account": { "type": "string", "description": "This is only included for mandate transfer events, when it is the ID of the [customer bank account](#core-endpoints-customer-bank-accounts) which the mandate is being transferred from.", "example": "BA123" }, "new_customer_bank_account": { "type": "string", "description": "This is only included for mandate transfer events, when it is the ID of the [customer bank account](#core-endpoints-customer-bank-accounts) which the mandate is being transferred to.", "example": "BA123" }, "new_mandate": { "type": "string", "description": "This is only included for mandate replaced events, when it is the ID of the new [mandate](#core-endpoints-mandates) that replaces the existing mandate.", "example": "MD123" }, "organisation": { "type": "string", "description": "If the event is included in a [webhook](#webhooks-overview) to an [OAuth app](#appendix-oauth), this is the ID of the account to which it belongs.", "example": "OR123" }, "outbound_payment": { "type": "string", "description": "If `resource_type` is `outbound_payments`, this is the ID of the outbound_payment which has been updated.", "example": "OUT123" }, "payment_account_transaction": { "type": "string", "description": "If `resource_type` is `payment_account_transaction`, this is the ID of a transaction which has been recorded on the payment account.", "example": "PATR123" }, "scheme_identifier": { "type": "string", "description": "If `resource_type` is `scheme_identifiers`, this is the ID of the [scheme_identifier](#core-endpoints-scheme-identifiers) which has been updated.", "example": "SU123" } } }, "event_linked": { "type": "object", "title": "EventLinked", "description": "", "properties": { "billing_requests": { "type": "array", "description": "A list of billing requests linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/billing_request" } }, "creditors": { "type": "array", "description": "A list of creditors linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/creditor" } }, "instalment_schedules": { "type": "array", "description": "A list of instalment schedules linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/instalment_schedule" } }, "mandates": { "type": "array", "description": "A list of mandates linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/mandate" } }, "outbound_payments": { "type": "array", "description": "A list of outbound payments linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/outbound_payment" } }, "payer_authorisations": { "type": "array", "description": "A list of payer authorisations linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/payer_authorisation" } }, "payment_account_transactions": { "type": "array", "description": "A list of payment account transactions linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/payment_account_transaction" } }, "payments": { "type": "array", "description": "A list of payments linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/payment" } }, "payouts": { "type": "array", "description": "A list of payouts linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/payout" } }, "refunds": { "type": "array", "description": "A list of refunds linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/refund" } }, "subscriptions": { "type": "array", "description": "A list of subscriptions linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/subscription" } }, "scheme_identifiers": { "type": "array", "description": "A list of scheme identifiers linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/scheme_identifier" } }, "customers": { "type": "array", "description": "A list of customers linked to the events returned in the list of events.", "items": { "$ref": "#/components/schemas/customer" } } } }, "event_pagination_meta": { "type": "object", "title": "EventPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "event_single_resource_response": { "type": "object", "title": "EventSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "events": { "$ref": "#/components/schemas/event" } } }, "event_multi_resource_response": { "type": "object", "title": "EventMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/event" } }, "meta": { "$ref": "#/components/schemas/event_pagination_meta" }, "linked": { "$ref": "#/components/schemas/event_linked" } } }, "export": { "type": "object", "title": "Exports", "description": "File-based exports of data", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/export_id" }, "created_at": { "$ref": "#/components/schemas/export_created_at" }, "export_type": { "$ref": "#/components/schemas/export_export_type" }, "download_url": { "$ref": "#/components/schemas/export_download_url" }, "currency": { "$ref": "#/components/schemas/export_currency" }, "error_message": { "$ref": "#/components/schemas/export_error_message" } } }, "export_id": { "type": "string", "title": "ExportId", "description": "Unique identifier, beginning with \"EX\".", "example": "EX123" }, "export_identity": { "$ref": "#/components/schemas/export_id" }, "export_created_at": { "type": "string", "title": "ExportCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "export_currency": { "type": "string", "title": "ExportCurrency", "description": "The currency of the export (if applicable)", "example": "GBP" }, "export_export_type": { "title": "ExportExportType", "description": "The type of the export", "example": "payments_index", "enum": [ "payments_index", "events_index", "refunds_index", "payouts_index", "customers_index", "subscriptions_index", "payment_events", "subscription_events", "payout_events", "refund_events", "mandate_events", "payout_events_breakdown", "payout_events_reconciliation", "payout_transactions_breakdown", "payout_transactions_reconciliation", "authorisation_requests", "customer_bank_accounts", "users", "organisation_authorisations", "app_connected_organisations", "gc_invalid_authorisation_requests", "partner_fees", "payments_import_template", "payment_account_statement", "outbound_payments_index", "payment_account_transactions" ], "type": "string" }, "export_download_url": { "type": "string", "nullable": true, "title": "ExportDownloadUrl", "description": "Download url for the export file. Subject to expiry." }, "export_error_message": { "type": "string", "nullable": true, "title": "ExportErrorMessage", "description": "Error message if the export encountered an error during processing." }, "export_pagination_meta": { "type": "object", "title": "ExportPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "export_single_resource_response": { "type": "object", "title": "ExportSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "exports": { "$ref": "#/components/schemas/export" } } }, "export_multi_resource_response": { "type": "object", "title": "ExportMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "exports": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/export_id" }, "export_type": { "$ref": "#/components/schemas/export_export_type" }, "currency": { "$ref": "#/components/schemas/export_currency" }, "created_at": { "$ref": "#/components/schemas/export_created_at" } } } }, "meta": { "$ref": "#/components/schemas/export_pagination_meta" } } }, "funds_availability": { "type": "object", "title": "Funds Availability", "description": "Checks if the payer's current balance is sufficient to cover the amount the merchant wants to charge within the consent parameters defined on the mandate.", "additionalProperties": true, "properties": { "available": { "$ref": "#/components/schemas/funds_availability_available" } } }, "funds_availability_available": { "type": "boolean", "title": "FundsAvailabilityAvailable", "description": "Indicates if the amount is available" }, "funds_availability_amount": { "type": "string", "title": "FundsAvailabilityAmount", "description": "The amount of the payment", "example": "1000" }, "instalment_schedule": { "type": "object", "title": "Instalment Schedule", "description": "Instalment schedules are objects which represent a collection of related payments, with the\nintention to collect the `total_amount` specified. The API supports both schedule-based\ncreation (similar to subscriptions) as well as explicit selection of differing payment\namounts and charge dates.\n\nUnlike subscriptions, the payments are created immediately, so the instalment schedule\ncannot be modified once submitted and instead can only be cancelled (which will cancel\nany of the payments which have not yet been submitted).\n\nCustomers will receive a single notification about the complete schedule of collection.\n", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/instalment_schedule_id" }, "created_at": { "$ref": "#/components/schemas/instalment_schedule_created_at" }, "total_amount": { "$ref": "#/components/schemas/instalment_schedule_total_amount" }, "name": { "$ref": "#/components/schemas/instalment_schedule_name" }, "currency": { "$ref": "#/components/schemas/instalment_schedule_currency" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "status": { "$ref": "#/components/schemas/instalment_schedule_status" }, "payment_errors": { "$ref": "#/components/schemas/instalment_schedule_payment_errors" }, "links": { "$ref": "#/components/schemas/instalment_schedule_links" } } }, "instalment_schedule_id": { "type": "string", "title": "InstalmentScheduleId", "description": "Unique identifier, beginning with \"IS\".", "example": "IS123" }, "instalment_schedule_identity": { "$ref": "#/components/schemas/instalment_schedule_id" }, "instalment_schedule_name": { "type": "string", "title": "InstalmentScheduleName", "description": "Name of the instalment schedule, up to 100 chars. This name will also be\ncopied to the payments of the instalment schedule if you use schedule-based creation.", "example": "Invoice 4404", "maxLength": 100, "minLength": 1 }, "instalment_schedule_currency": { "title": "Currency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently \"AUD\", \"CAD\", \"DKK\", \"EUR\", \"GBP\", \"NZD\", \"SEK\" and \"USD\" are supported.", "example": "EUR", "enum": [ "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK", "USD" ], "type": "string" }, "instalment_schedule_payment_reference": { "type": "string", "nullable": true, "title": "InstalmentSchedulePaymentReference", "description": "An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.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.
", "example": "WINEBOX001" }, "instalment_schedule_retry_if_possible": { "type": "boolean", "title": "InstalmentScheduleRetryIfPossible", "description": "On failure, automatically retry payments using [intelligent retries](/success-plus/overview). Default is `false`.Important: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus).
" }, "instalment_schedule_total_amount_stringable": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "title": "InstalmentScheduleTotalAmountStringable", "description": "The total amount of the instalment schedule, defined as the sum of all individual\npayments, in the lowest denomination for the currency (e.g. pence in GBP, cents in\nEUR). If the requested payment amounts do not sum up correctly, a validation error\nwill be returned.", "example": 1000 }, "instalment_schedule_total_amount": { "type": "integer", "title": "InstalmentScheduleTotalAmount", "description": "The total amount of the instalment schedule, defined as the sum of all individual\npayments, in the lowest denomination for the currency (e.g. pence in GBP, cents in\nEUR). If the requested payment amounts do not sum up correctly, a validation error\nwill be returned.", "example": 1000 }, "instalment_schedule_status": { "title": "InstalmentScheduleStatus", "description": "One of:\n\n- `pending`: we're waiting for GC to create the payments\n- `active`: the payments have been created, and the schedule is active\n- `creation_failed`: payment creation failed\n- `completed`: we have passed the date of the final payment and all payments have been collected\n- `cancelled`: the schedule has been cancelled\n- `errored`: one or more payments have failed", "example": "active", "enum": [ "pending", "active", "creation_failed", "completed", "cancelled", "errored" ], "type": "string" }, "instalment_schedule_created_at": { "type": "string", "title": "InstalmentScheduleCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "instalment_schedule_mandate": { "type": "string", "title": "InstalmentScheduleMandate", "description": "ID of the associated [mandate](#core-endpoints-mandates) which the instalment schedule will create payments against.", "example": "MD123" }, "instalment_schedule_customer": { "type": "string", "title": "InstalmentScheduleCustomer", "description": "ID of the associated [customer](#core-endpoints-customers).", "example": "CU123" }, "instalment_schedule_payments": { "type": "array", "title": "InstalmentSchedulePayments", "description": "Array of IDs of the associated [payments](#core-endpoints-payments)", "example": [ "PM123", "PM456" ], "items": { "type": "string" } }, "instalment_schedule_payment_errors": { "type": "object", "title": "InstalmentSchedulePaymentErrors", "description": "If the status is `creation_failed`, this property will be populated with validation\nfailures from the individual payments, arranged by the index of the payment that\nfailed.\n", "example": { "0": [ { "field": "charge_date", "message": "must be on or after mandate's next_possible_customer_charge_date" } ] } }, "instalment_schedule_links": { "type": "object", "title": "InstalmentScheduleLinks", "description": "Links to associated objects", "additionalProperties": false, "required": [ "mandate", "customer" ], "properties": { "mandate": { "$ref": "#/components/schemas/instalment_schedule_mandate" }, "customer": { "$ref": "#/components/schemas/instalment_schedule_customer" }, "payments": { "$ref": "#/components/schemas/instalment_schedule_payments" } } }, "instalment_schedule_pagination_meta": { "type": "object", "title": "InstalmentSchedulePaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "instalment_schedule_single_resource_response": { "type": "object", "title": "InstalmentScheduleSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "instalment_schedules": { "$ref": "#/components/schemas/instalment_schedule" } } }, "instalment_schedule_multi_resource_response": { "type": "object", "title": "InstalmentScheduleMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "instalment_schedules": { "type": "array", "items": { "$ref": "#/components/schemas/instalment_schedule" } }, "meta": { "$ref": "#/components/schemas/instalment_schedule_pagination_meta" } } }, "instalment_schedule_charge_date": { "type": "string", "nullable": true, "title": "InstalmentScheduleChargeDate", "description": "A future date on which the payment should be collected. If the date\nis before the next_possible_charge_date on the\n[mandate](#core-endpoints-mandates), it will be automatically rolled\nforwards to that date.", "example": "2014-05-21", "format": "date" }, "institution": { "type": "object", "title": "Institutions", "description": "Institutions that are supported when creating [Bank Authorisations](#billing-requests-bank-authorisations) for a particular country or purpose.\n\nNot all institutions support both Payment Initiation (PIS) and Account Information (AIS) services.", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/institution_id" }, "name": { "$ref": "#/components/schemas/institution_name" }, "icon_url": { "$ref": "#/components/schemas/institution_icon_url" }, "logo_url": { "$ref": "#/components/schemas/institution_logo_url" }, "roles": { "$ref": "#/components/schemas/institution_roles" }, "country_code": { "$ref": "#/components/schemas/institution_country_code" }, "limits": { "$ref": "#/components/schemas/institution_limits" } } }, "institution_id": { "type": "string", "title": "InstitutionId", "description": "The unique identifier for this institution", "example": "monzo" }, "institution_icon_url": { "type": "string", "title": "InstitutionIconUrl", "description": "A URL pointing to the icon for this institution", "example": "https://gocardless/assets/icons/monzo" }, "institution_logo_url": { "type": "string", "title": "InstitutionLogoUrl", "description": "A URL pointing to the logo for this institution", "example": "https://gocardless/assets/logos/monzo" }, "institution_roles": { "type": "array", "title": "InstitutionRoles", "description": "The roles assigned to this institution, representing the open banking features it supports.", "example": [ "corporate_accounts", "funds_confirmation" ], "items": { "type": "string", "description": "- `read_refund_account`: The institution can return the payer's refund account.\n- `read_debtor_account`: The institution can return the payer's debtor account.\n- `funds_confirmation`: The institution supports a funds-confirmation check before authorising an instant payment.\n- `corporate_accounts`: The institution supports corporate accounts." } }, "institution_name": { "type": "string", "title": "InstitutionName", "description": "A human readable name for this institution", "example": "VAT" }, "institution_country_code": { "type": "string", "title": "InstitutionCountryCode", "description": "[ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code 'GB' are returned by default.", "example": "GB" }, "institution_scheme": { "type": "string", "title": "InstitutionScheme", "description": "The scheme that institutions support. The available options include `faster_payments`, `sepa_credit_transfer`, and `sepa_instant_credit_transfer`. If nothing is provided, institutions supporting 'faster_payments' are returned by default.", "example": "faster_payments" }, "institution_feature": { "type": "string", "title": "InstitutionFeature", "description": "The feature that institutions support. The available options include `pis`, and `vrp_sweeping`. If nothing is provided, institutions supporting 'pis' are returned by default.", "example": "pis" }, "institution_branch_code": { "type": "string", "title": "InstitutionBranchCode", "description": "(Currently only supports UK sort-codes) The six-digit number that identifies both the bank and the specific branch where an account is held, eg. '601234'.", "example": "601234" }, "institution_autocompletes_collect_bank_account": { "type": "boolean", "title": "InstitutionAutocompletesCollectBankAccount", "description": "Flag to show if selecting this institution in the select_institution action can auto-complete the collect_bank_account action. The bank can return the payer's bank account details to GoCardless.", "example": true }, "institution_status": { "type": "string", "title": "InstitutionStatus", "description": "The status of the institution", "example": "enabled", "enum": [ "enabled", "disabled", "temporarily_disabled" ] }, "institution_limits": { "type": "object", "nullable": true, "title": "InstitutionLimits", "description": "Defines individual limits for business and personal accounts.", "properties": { "daily": { "type": "object", "nullable": true, "description": "Daily limit details for this institution, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). The 'limits' property is only available via an authenticated request with a generated access token" }, "single": { "type": "object", "nullable": true, "description": "Single transaction limit details for this institution, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). The 'limits' property is only available via an authenticated request with a generated access token" } } }, "institution_pagination_meta": { "type": "object", "title": "InstitutionPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "institution_multi_resource_response": { "type": "object", "title": "InstitutionMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/institution" } }, "meta": { "$ref": "#/components/schemas/institution_pagination_meta" } } }, "logo": { "type": "object", "title": "Logos", "description": "Logos are image uploads that, when associated with a creditor, are shown on the [billing request flow](#billing-requests-billing-request-flows) payment pages.", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/logo_id" } } }, "logo_id": { "type": "string", "title": "LogoId", "description": "Unique identifier, beginning with \"LO\".", "example": "LO123" }, "logo_single_resource_response": { "type": "object", "title": "LogoSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "logos": { "$ref": "#/components/schemas/logo" } } }, "mandate": { "type": "object", "title": "Mandates", "description": "Mandates represent the Direct Debit mandate with a [customer](#core-endpoints-customers).\n\nGoCardless will notify you via a [webhook](#appendix-webhooks) whenever the status of a mandate changes.", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/mandate_id" }, "created_at": { "$ref": "#/components/schemas/mandate_created_at" }, "reference": { "$ref": "#/components/schemas/mandate_reference" }, "status": { "$ref": "#/components/schemas/mandate_status" }, "scheme": { "$ref": "#/components/schemas/mandate_scheme" }, "mandate_type": { "$ref": "#/components/schemas/mandate_mandate_type" }, "next_possible_charge_date": { "$ref": "#/components/schemas/mandate_next_possible_charge_date" }, "next_possible_standard_ach_charge_date": { "$ref": "#/components/schemas/mandate_next_possible_standard_ach_charge_date" }, "payments_require_approval": { "$ref": "#/components/schemas/mandate_payments_require_approval" }, "verified_at": { "$ref": "#/components/schemas/mandate_verified_at" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "links": { "$ref": "#/components/schemas/mandate_links" }, "consent_parameters": { "$ref": "#/components/schemas/mandate_consent_parameters" }, "authorisation_source": { "$ref": "#/components/schemas/mandate_authorisation_source" }, "funds_settlement": { "$ref": "#/components/schemas/mandate_funds_settlement" }, "consent_type": { "$ref": "#/components/schemas/mandate_consent_type" } } }, "mandate_id": { "type": "string", "title": "MandateId", "description": "Unique identifier, beginning with \"MD\". Note that this prefix may not apply to mandates created before 2016.", "example": "MD123" }, "mandate_identity": { "$ref": "#/components/schemas/mandate_id" }, "mandate_created_at": { "type": "string", "title": "MandateCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "mandate_reference": { "type": "string", "nullable": true, "title": "MandateReference", "description": "Unique reference. Different schemes have different length and [character set](#appendix-character-sets) requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.", "example": "REF-123" }, "mandate_status": { "title": "MandateStatus", "description": "One of:\n\n- `pending_customer_approval`: the mandate has not yet been signed by the second customer\n- `pending_submission`: the mandate has not yet been submitted to the customer's bank\n- `submitted`: the mandate has been submitted to the customer's bank but has not been processed yet\n- `active`: the mandate has been successfully set up by the customer's bank\n- `suspended_by_payer`: the mandate has been suspended by payer\n- `failed`: the mandate could not be created\n- `cancelled`: the mandate has been cancelled\n- `expired`: the mandate has expired due to dormancy\n- `consumed`: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised)\n- `blocked`: the mandate has been blocked and payments cannot be created", "example": "pending_submission", "enum": [ "pending_customer_approval", "pending_submission", "submitted", "active", "failed", "cancelled", "expired", "consumed", "blocked", "suspended_by_payer" ], "type": "string" }, "mandate_scheme": { "type": "string", "nullable": true, "title": "MandateScheme", "description": "Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account.", "example": "bacs" }, "mandate_mandate_type": { "type": "string", "nullable": true, "title": "MandateTypeString", "description": "Mandate type", "example": "bank_debit", "enum": [ "bank_debit", "instant", "recurring", "vrp_commercial", "vrp_sweeping" ] }, "mandate_next_possible_charge_date": { "type": "string", "nullable": true, "title": "MandateNextPossibleChargeDate", "description": "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.", "example": "2014-10-27", "format": "date" }, "mandate_next_possible_standard_ach_charge_date": { "type": "string", "nullable": true, "title": "MandateNextPossibleStandardAchChargeDate", "description": "If this is an ACH mandate, the earliest date that can be used as a\n`charge_date` on any newly created payment to be charged through standard\nACH, rather than Faster ACH. This value will change over time.\n\nIt is only present in the API response for ACH mandates.", "example": "2014-10-27", "format": "date" }, "mandate_payments_require_approval": { "type": "boolean", "title": "MandatePaymentsRequireApproval", "description": "Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed." }, "mandate_payer_ip_address": { "type": "string", "nullable": true, "title": "MandatePayerIpAddress", "description": "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).\n\nNot required for creating offline mandates where `authorisation_source` is set to telephone or paper.\n", "example": "127.0.0.1" }, "mandate_verified_at": { "type": "string", "nullable": true, "title": "MandateVerifiedAt", "description": "[Timestamp](#api-usage-dates-and-times) recording when this mandate was verified.", "example": "2021-01-01T12:00:00.000Z", "format": "date-time" }, "mandate_period": { "title": "MandatePeriod", "description": "The repeating period for this mandate", "enum": [ "day", "week", "month", "year", "flexible" ], "type": "string" }, "mandate_max_amount_per_period": { "type": "integer", "nullable": true, "title": "MandateMaxAmountPerPeriod", "description": "The maximum total amount that can be charged for all payments in this period" }, "mandate_max_payments_per_period": { "type": "integer", "nullable": true, "title": "MandateMaxPaymentsPerPeriod", "description": "The maximum number of payments that can be collected in this period" }, "mandate_start_date": { "type": "string", "title": "MandateStartDate", "description": "The date from which payments can be taken" }, "mandate_end_date": { "type": "string", "nullable": true, "title": "MandateEndDate", "description": "The latest date at which payments can be taken, must occur after start_date if present" }, "mandate_max_amount_per_payment": { "type": "integer", "nullable": true, "title": "MandateMaxAmountPerPayment", "description": "The maximum amount that can be charged for a single payment" }, "mandate_consent_type": { "type": "string", "nullable": true, "title": "MandateConsentType", "description": "(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.", "enum": [ "one_off", "single", "recurring", "standing", "sporadic" ] }, "mandate_consent_parameters": { "type": "object", "nullable": true, "title": "MandateConsentParameters", "description": "(Optional) Payto and VRP Scheme specific information", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique identifier for the consent parameters" }, "scheme": { "type": "string", "description": "The scheme associated with the consent parameters" }, "currency": { "type": "string", "description": "The currency for the consent parameters" }, "fixed_amount_per_payment": { "type": "integer", "nullable": true, "description": "The fixed amount for each payment, in the lowest denomination for the currency" }, "max_amount_per_payment": { "$ref": "#/components/schemas/mandate_max_amount_per_payment" }, "period": { "$ref": "#/components/schemas/mandate_period" }, "max_amount_per_period": { "$ref": "#/components/schemas/mandate_max_amount_per_period" }, "max_payments_per_period": { "$ref": "#/components/schemas/mandate_max_payments_per_period" }, "start_date": { "$ref": "#/components/schemas/mandate_start_date" }, "end_date": { "$ref": "#/components/schemas/mandate_end_date" }, "period_alignment": { "type": "string", "description": "The alignment of the payment period.", "enum": [ "calendar", "consent", "creation_date" ] } } }, "mandate_funds_settlement": { "title": "MandateFundsSettlement", "description": "This field will decide how GoCardless handles settlement of funds from the customer.\n\n- `managed` will be moved through GoCardless' account, batched, and payed out.\n- `direct` will be a direct transfer from the payer's account to the merchant where\n invoicing will be handled separately.\n", "enum": [ "managed", "direct" ], "type": "string" }, "mandate_links": { "type": "object", "title": "MandateLinks", "description": "", "properties": { "customer_bank_account": { "type": "string", "description": "ID of the associated [customer bank account](#core-endpoints-customer-bank-accounts) which the mandate is created and submits payments against.", "example": "BA123" }, "creditor": { "type": "string", "description": "ID of the associated [creditor](#core-endpoints-creditors).", "example": "CR123" }, "new_mandate": { "type": "string", "description": "ID of the new mandate if this mandate has been replaced.", "example": "MD123" }, "customer": { "type": "string", "description": "ID of the associated [customer](#core-endpoints-customers)", "example": "CU123" } } }, "mandate_pagination_meta": { "type": "object", "title": "MandatePaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "mandate_single_resource_response": { "type": "object", "title": "MandateSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "mandates": { "$ref": "#/components/schemas/mandate" } } }, "mandate_multi_resource_response": { "type": "object", "title": "MandateMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "mandates": { "type": "array", "items": { "$ref": "#/components/schemas/mandate" } }, "meta": { "$ref": "#/components/schemas/mandate_pagination_meta" } } }, "mandate_authorisation_source": { "title": "MandateAuthorisationSource", "description": "This field is ACH specific, sometimes referred to as [SEC code](https://www.moderntreasury.com/learn/sec-codes).\n\nThis is the way that the payer gives authorisation to the merchant.\n web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB)\n telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL)\n paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)\n", "enum": [ "web", "telephone", "paper" ], "type": "string" }, "mandate_import": { "type": "object", "title": "Mandate Imports", "description": "Mandate Imports allow you to migrate existing mandates from other providers into the\nGoCardless platform.\n\nThe process is as follows:\n\n 1. [Create a mandate import](#mandate-imports-create-a-new-mandate-import)\n 2. [Add entries](#mandate-import-entries-add-a-mandate-import-entry) to the import\n 3. [Submit](#mandate-imports-submit-a-mandate-import) the import\n 4. Wait until a member of the GoCardless team approves the import, at which point the mandates will be created\n 5. [Link up the mandates](#mandate-import-entries-list-all-mandate-import-entries) in your system\n\nWhen you add entries to your mandate import, they are not turned into actual mandates\nuntil the mandate import is submitted by you via the API, and then processed by a member\nof the GoCardless team. When that happens, a mandate will be created for each entry in the import.\n\nWe will issue a `mandate_created` webhook for each entry, which will be the same as the webhooks\ntriggered when [ creating a mandate ](#mandates-create-a-mandate) using the mandates API. Once these\nwebhooks start arriving, any reconciliation can now be accomplished by\n[checking the current status](#mandate-imports-get-a-mandate-import) of the mandate import and\n[linking up the mandates to your system](#mandate-import-entries-list-all-mandate-import-entries).\n\nNote that all Mandate Imports have an upper limit of 30,000 entries, so we recommend you split your import into several smaller imports if you're planning to exceed this threshold.
\n\nRestricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.
", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/mandate_import_id" }, "created_at": { "$ref": "#/components/schemas/mandate_import_created_at" }, "status": { "$ref": "#/components/schemas/mandate_import_status" }, "scheme": { "$ref": "#/components/schemas/mandate_import_scheme" }, "links": { "$ref": "#/components/schemas/mandate_import_links" } } }, "mandate_import_id": { "type": "string", "title": "MandateImportId", "description": "Unique identifier, beginning with \"IM\".", "example": "IM123" }, "mandate_import_identity": { "$ref": "#/components/schemas/mandate_import_id" }, "mandate_import_created_at": { "type": "string", "title": "MandateImportCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "mandate_import_scheme": { "title": "MandateScheme", "description": "The scheme of the mandates to be imported.Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.
", "additionalProperties": true, "properties": { "record_identifier": { "$ref": "#/components/schemas/mandate_import_entry_record_identifier" }, "created_at": { "$ref": "#/components/schemas/mandate_import_created_at" }, "links": { "$ref": "#/components/schemas/mandate_import_entry_links" }, "processing_errors": { "$ref": "#/components/schemas/mandate_import_entry_processing_errors" } } }, "mandate_import_entry_record_identifier": { "type": "string", "nullable": true, "title": "MandateImportEntryRecordIdentifier", "description": "A unique identifier for this entry, which you can use (once the import has been\nprocessed by GoCardless) to identify the records that have been created. Limited\nto 255 characters.\n", "example": "bank-file.xml/line-1", "maxLength": 255 }, "mandate_import_entry_mandate_import": { "type": "string", "title": "MandateImportEntryMandateImport", "description": "The ID of the mandate import. This is returned when you\n[create a Mandate Import](#mandate-imports-create-a-new-mandate-import).\n", "example": "IM0000AAAAAAA" }, "mandate_import_entry_links": { "type": "object", "title": "MandateImportEntryLinks", "description": "Related resources", "required": [ "mandate_import" ], "properties": { "mandate_import": { "$ref": "#/components/schemas/mandate_import_entry_mandate_import" }, "mandate": { "allOf": [ { "$ref": "#/components/schemas/mandate_identity" }, { "description": "The ID of the mandate which was created when the mandate import was processed." } ] }, "customer": { "allOf": [ { "$ref": "#/components/schemas/customer_identity" }, { "description": "The ID of the customer which was created when the mandate import was processed." } ] }, "customer_bank_account": { "allOf": [ { "$ref": "#/components/schemas/customer_bank_account_identity" }, { "description": "The ID of the customer bank account which was created when the mandate import\nwas processed." } ] } } }, "mandate_import_entry_status": { "title": "MandateImportEntryStatus", "description": "One of:\n\n- `successfully_processed`: the entry has been imported and the associated records created.\n- `unsuccessfully_processed`: the entry could not be processed due to an error, see the 'processing_errors' value", "example": "successfully_processed", "enum": [ "successfully_processed", "unsuccessfully_processed" ], "type": "string" }, "mandate_import_entry_processing_errors": { "type": "object", "nullable": true, "title": "MandateImportEntryProcessingErrors", "description": "Per-resource processing errors" }, "mandate_import_entry_pagination_meta": { "type": "object", "title": "MandateImportEntryPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "mandate_import_entry_single_resource_response": { "type": "object", "title": "MandateImportEntrySingleResourceResponse", "description": "", "properties": { "mandate_import_entries": { "$ref": "#/components/schemas/mandate_import_entry" } } }, "mandate_import_entry_multi_resource_response": { "type": "object", "title": "MandateImportEntryMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "mandate_import_entries": { "type": "array", "items": { "$ref": "#/components/schemas/mandate_import_entry" } }, "meta": { "$ref": "#/components/schemas/mandate_import_entry_pagination_meta" } } }, "mandate_pdf": { "type": "object", "title": "Mandate PDFs", "description": "Mandate PDFs allow you to easily display [scheme-rules compliant](#appendix-compliance-requirements) Direct Debit mandates to your customers.", "additionalProperties": true, "properties": { "url": { "$ref": "#/components/schemas/mandate_pdf_url" }, "expires_at": { "$ref": "#/components/schemas/mandate_pdf_expires_at" } } }, "mandate_pdf_scheme": { "type": "string", "nullable": true, "title": "MandatePdfScheme", "description": "Direct Debit scheme. Can be supplied or automatically detected from the bank account details provided. If you do not provide a scheme, you must provide either a mandate, an `iban`, or [local details](#appendix-local-bank-details) including a `country_code`.", "example": "bacs" }, "mandate_pdf_iban": { "type": "string", "nullable": true, "title": "MandatePdfIban", "description": "International Bank Account Number. Alternatively you can provide [local details](#appendix-local-bank-details). IBANs cannot be provided for Autogiro mandates." }, "mandate_pdf_bic": { "type": "string", "nullable": true, "title": "MandatePdfBic", "description": "SWIFT BIC. Will be derived automatically if a valid `iban` or [local details](#appendix-local-bank-details) are provided." }, "mandate_pdf_account_number": { "type": "string", "nullable": true, "title": "MandatePdfAccountNumber", "description": "Bank account number - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`.", "example": "55779912" }, "mandate_pdf_bank_code": { "type": "string", "nullable": true, "title": "MandatePdfBankCode", "description": "Bank code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`.", "example": "20041" }, "mandate_pdf_branch_code": { "type": "string", "nullable": true, "title": "MandatePdfBranchCode", "description": "Branch code - see [local details](#appendix-local-bank-details) for more information. Alternatively you can provide an `iban`.", "example": "01005" }, "mandate_pdf_country_code": { "type": "string", "nullable": true, "title": "MandatePdfCountryCode", "description": "[ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) alpha-2 code. Required if providing local details." }, "mandate_pdf_account_holder_name": { "type": "string", "nullable": true, "title": "MandatePdfAccountHolderName", "description": "Name of the account holder, as known by the bank. Usually this matches the name of the [customer](#core-endpoints-customers). This field cannot exceed 18 characters.", "example": "Lando Calrissian" }, "mandate_pdf_given_name": { "type": "string", "nullable": true, "title": "MandatePdfGivenName", "description": "The customer's given name (i.e. first name). Used to populate the \"Customer Name or Company name\" field on the PDF. Ignored if `company_name` is provided.", "example": "Lando" }, "mandate_pdf_family_name": { "type": "string", "nullable": true, "title": "MandatePdfFamilyName", "description": "The customer's family name (i.e. last name). Used to populate the \"Customer Name or Company name\" field on the PDF. Ignored if `company_name` is provided.", "example": "Calrissian" }, "mandate_pdf_company_name": { "type": "string", "nullable": true, "title": "MandatePdfCompanyName", "description": "The customer's company name. Used to populate the \"Customer Name or Company name\" field on the PDF.", "example": "Lando Corp" }, "mandate_pdf_phone_number": { "type": "string", "nullable": true, "title": "MandatePdfPhoneNumber", "description": "The customer phone number. Should only be provided for BECS NZ mandates.", "example": "+64 4 817 9999" }, "mandate_pdf_mandate_reference": { "type": "string", "nullable": true, "title": "MandatePdfMandateReference", "description": "Unique 6 to 18 character reference. This may be left blank at the point of signing.", "example": "Foo Subscription" }, "mandate_pdf_signature_date": { "type": "string", "nullable": true, "title": "MandatePdfSignatureDate", "description": "If provided, a form will be generated with this date and no signature field.", "example": "2014-01-18", "format": "date" }, "mandate_pdf_swedish_identity_number": { "type": "string", "nullable": true, "title": "MandatePdfSwedishIdentityNumber", "description": "For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Should only be supplied for Autogiro mandates.", "example": "556564-5404" }, "mandate_pdf_danish_identity_number": { "type": "string", "nullable": true, "title": "MandatePdfDanishIdentityNumber", "description": "For Danish customers only. The civic/company number (CPR or CVR) of the customer. Should only be supplied for Betalingsservice mandates.", "example": "220550-6218" }, "mandate_pdf_url": { "type": "string", "title": "MandatePdfUrl", "description": "The URL at which this mandate PDF can be viewed until it expires at the date and time specified by `expires_at`. You should not store this URL or rely on its structure remaining the same.", "example": "https://api.gocardless.com/mandate_pdfs/wLJKzbG12uqcDly7t6L2" }, "mandate_pdf_expires_at": { "type": "string", "title": "MandatePdfExpiresAt", "description": "The date and time at which the `url` will expire (10 minutes after the original request).", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "mandate_pdf_account_type": { "title": "BankAccountType", "description": "Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information.", "example": "savings", "enum": [ "savings", "checking" ], "nullable": true, "type": "string" }, "mandate_pdf_payer_ip_address": { "type": "string", "nullable": true, "title": "MandatePdfPayerIpAddress", "description": "For American customers only. IP address of the computer used by the customer to set up the mandate. This is required in order to create compliant Mandate PDFs according to the ACH scheme rules.", "example": "127.0.0.1" }, "mandate_pdf_subscription_amount": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "integer" } ], "title": "MandatePdfSubscriptionAmount", "description": "For American customers only. Subscription amount being authorised by the mandate. In the lowest denomination for the currency (cents in USD). Is required if `subscription_frequency` has been provided.", "example": "5000" }, "mandate_pdf_subscription_frequency": { "type": "string", "nullable": true, "title": "MandatePdfSubscriptionFrequency", "description": "For American customers only. Frequency of the subscription being authorised by the mandate. One of `weekly`, `monthly` or `yearly`. Is required if `subscription_amount` has been provided.", "example": "monthly", "enum": [ "weekly", "monthly", "yearly" ] }, "mandate_pdf_single_resource_response": { "type": "object", "title": "MandatePdfSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "mandate_pdfs": { "$ref": "#/components/schemas/mandate_pdf" } } }, "negative_balance_limit": { "type": "object", "title": "Negative Balance Limit", "description": "The negative balance limit is a threshold for the creditor balance beyond which refunds are not permitted. The default limit is zero — refunds are not permitted if the creditor has a negative balance. The limit can be changed on a per-creditor basis.\n", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/negative_balance_limit_id" }, "created_at": { "$ref": "#/components/schemas/negative_balance_limit_created_at" }, "balance_limit": { "$ref": "#/components/schemas/negative_balance_limit_balance_limit" }, "currency": { "$ref": "#/components/schemas/negative_balance_limit_currency" }, "links": { "$ref": "#/components/schemas/negative_balance_limit_links" } } }, "negative_balance_limit_id": { "type": "string", "title": "NegativeBalanceLimitId", "description": "Unique identifier, beginning with \"NBL\".", "example": "NBL123" }, "negative_balance_limit_balance_limit": { "type": "integer", "title": "NegativeBalanceLimitBalanceLimit", "description": "The limit amount in pence (e.g. 10000 for a -100 GBP limit).", "example": 10000 }, "negative_balance_limit_currency": { "title": "Currency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently \"AUD\", \"CAD\", \"DKK\", \"EUR\", \"GBP\", \"NZD\", \"SEK\" and \"USD\" are supported.", "example": "EUR", "enum": [ "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK", "USD" ], "type": "string" }, "negative_balance_limit_created_at": { "type": "string", "title": "NegativeBalanceLimitCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this limit was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "negative_balance_limit_links": { "type": "object", "title": "NegativeBalanceLimitLinks", "description": "", "properties": { "creator_user": { "type": "string", "description": "ID of the creator_user who created this limit", "example": "US123" }, "creditor": { "type": "string", "description": "ID of [creditor](#core-endpoints-creditors) which this limit relates to", "example": "CR123" } } }, "negative_balance_limit_pagination_meta": { "type": "object", "title": "NegativeBalanceLimitPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "negative_balance_limit_multi_resource_response": { "type": "object", "title": "NegativeBalanceLimitMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "negative_balance_limits": { "type": "array", "items": { "$ref": "#/components/schemas/negative_balance_limit" } }, "meta": { "$ref": "#/components/schemas/negative_balance_limit_pagination_meta" } } }, "outbound_payment": { "type": "object", "title": "Outbound Payments", "description": "Outbound Payments represent payments sent from [creditors](#core-endpoints-creditors).\n\nGoCardless will notify you via a [webhook](#appendix-webhooks) when the status of the outbound payment [changes](#event-types-outbound-payment).\n\n#### Rate limiting\n\nTwo rate limits apply to the Outbound Payments APIs:\n- All POST Outbound Payment endpoints (create, withdraw, approve, cancel and etc.) share a single rate-limit group of 300 requests per minute. As initiating a payment typically requires two API calls (one to create the payment and one to approve it), this allows you to add approximately 150 outbound payments per minute.\n- All remaining Outbound Payment endpoints are limited to 500 requests per minute.", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/outbound_payment_id" }, "created_at": { "$ref": "#/components/schemas/outbound_payment_created_at" }, "status": { "$ref": "#/components/schemas/outbound_payment_status" }, "amount": { "$ref": "#/components/schemas/outbound_payment_amount" }, "scheme": { "$ref": "#/components/schemas/outbound_payment_scheme" }, "currency": { "$ref": "#/components/schemas/outbound_payment_currency" }, "execution_date": { "$ref": "#/components/schemas/outbound_payment_execution_date" }, "description": { "$ref": "#/components/schemas/outbound_payment_description" }, "reference": { "$ref": "#/components/schemas/outbound_payment_reference" }, "is_withdrawal": { "$ref": "#/components/schemas/outbound_payment_is_withdrawal" }, "links": { "$ref": "#/components/schemas/outbound_payment_links" }, "verifications": { "$ref": "#/components/schemas/outbound_payment_verifications" }, "metadata": { "$ref": "#/components/schemas/outbound_payment_metadata" } } }, "outbound_payment_id": { "type": "string", "title": "OutboundPaymentId", "description": "Unique identifier of the outbound payment.", "example": "OUT123" }, "outbound_payment_identity": { "$ref": "#/components/schemas/outbound_payment_id" }, "outbound_payment_amount": { "type": "integer", "title": "OutboundPaymentAmount", "description": "Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).", "example": 1000 }, "outbound_payment_scheme": { "title": "OutboundPaymentScheme", "description": "Bank payment scheme to process the outbound payment. Currently only \"faster_payments\" (GBP) is supported.", "example": "faster_payments", "enum": [ "faster_payments" ], "type": "string" }, "outbound_payment_currency": { "title": "OutboundPaymentCurrency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency. Currently only \"GBP\" is supported.", "example": "GBP", "enum": [ "GBP" ], "type": "string" }, "outbound_payment_execution_date": { "type": "string", "title": "OutboundPaymentExecutionDate", "description": "A future date on which the outbound payment should be sent.\nIf not specified, the payment will be sent as soon as possible.", "example": "2024-08-31", "format": "date" }, "outbound_payment_description": { "type": "string", "title": "OutboundPaymentDescription", "description": "A human-readable description of the outbound payment", "example": "Reward Payment (August 2024)" }, "outbound_payment_reference": { "type": "string", "title": "OutboundPaymentReference", "description": "An optional reference that will appear on your customer's bank statement.\nThe character limit for this reference is dependent on the scheme.Outbound Payment Imports are capped at 1000 entries. If you expect to exceed this limit, please create multiple smaller imports.
", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/outbound_payment_import_id" }, "created_at": { "$ref": "#/components/schemas/outbound_payment_import_created_at" }, "status": { "$ref": "#/components/schemas/outbound_payment_import_status" }, "amount_sum": { "$ref": "#/components/schemas/outbound_payment_import_amount_sum" }, "currency": { "$ref": "#/components/schemas/outbound_payment_import_currency" }, "authorisation_url": { "$ref": "#/components/schemas/outbound_payment_import_authorisation_url" }, "entry_counts": { "$ref": "#/components/schemas/outbound_payment_import_entry_counts" }, "links": { "$ref": "#/components/schemas/outbound_payment_import_links" } } }, "outbound_payment_import_id": { "type": "string", "title": "OutboundPaymentImportId", "description": "Unique identifier, beginning with \"IM\".", "example": "IM123" }, "outbound_payment_import_identity": { "$ref": "#/components/schemas/outbound_payment_import_id" }, "outbound_payment_import_created_at": { "type": "string", "title": "OutboundPaymentImportCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "outbound_payment_import_status": { "title": "OutboundPaymentImportStatus", "description": "The status of the outbound payment import.\n\n- `created`: The initial state of a new import.\n- `validating`: Import validation in progress.\n- `invalid`: Import validation failed.\n- `valid`: Import validation succeeded.\n- `processing`: Authorisation received; payments are being generated.\n- `processed`: All entries have been successfully converted into outbound payments.\n- `cancelled`: The import was cancelled by a user or automatically expired by the system.", "example": "created", "enum": [ "created", "validating", "valid", "invalid", "processing", "processed", "cancelled" ], "type": "string" }, "outbound_payment_import_amount_sum": { "type": "integer", "title": "OutboundPaymentImportAmountSum", "description": "The sum of all import entry amounts, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).", "example": 1000 }, "outbound_payment_import_currency": { "$ref": "#/components/schemas/outbound_payment_currency" }, "outbound_payment_import_authorisation_url": { "type": "string", "title": "OutboundPaymentImportAuthorisationUrl", "description": "The link to the GoCardless dashboard to review and authorise the import", "example": "https://manage.gocardless.com/imports/IM123" }, "outbound_payment_import_entry_counts": { "type": "object", "title": "OutboundPaymentImportEntryCounts", "description": "", "additionalProperties": false, "properties": { "total": { "type": "integer", "description": "The total number of entries included in the import.", "example": 1000 }, "valid": { "type": "integer", "description": "Count of entries that passed validation checks.", "example": 1000 }, "invalid": { "type": "integer", "description": "Count of entries that failed validation checks.", "example": 0 }, "processed": { "type": "integer", "description": "Count of entries successfully converted into outbound payments after the import was authorised.", "example": 1000 }, "failed_to_process": { "type": "integer", "description": "Count of entries that encountered a terminal error during the outbound payment generation process.", "example": 0 }, "verified": { "type": "integer", "description": "Total count of entries checked against bank account holder verification services (e.g., CoP).", "example": 0 }, "verified_with_full_match": { "type": "integer", "description": "Count of entries where the account holder name was a direct match.", "example": 0 }, "verified_with_partial_match": { "type": "integer", "description": "Count of entries where the account holder name was a close match.", "example": 0 }, "verified_with_no_match": { "type": "integer", "description": "Count of entries where the account holder name did not match the records.", "example": 0 }, "verified_with_unable_to_match": { "type": "integer", "description": "Count of entries where the verification service could not return a definitive result.", "example": 0 } } }, "outbound_payment_import_links": { "type": "object", "title": "OutboundPaymentImportLinks", "description": "", "additionalProperties": false, "properties": { "creditor": { "type": "string", "description": "ID of the creditor who sends the outbound payments from the import.", "example": "CR123" } } }, "outbound_payment_import_entry_item_amount": { "$ref": "#/components/schemas/outbound_payment_amount" }, "outbound_payment_import_entry_item_reference": { "$ref": "#/components/schemas/outbound_payment_reference" }, "outbound_payment_import_entry_recipient_bank_account_id": { "type": "string", "title": "OutboundPaymentImportEntryRecipientBankAccountId", "description": "ID of the customer bank account which receives the outbound payment.", "example": "BA123" }, "outbound_payment_import_entry_item_metadata": { "$ref": "#/components/schemas/outbound_payment_metadata" }, "outbound_payment_import_single_resource_response": { "type": "object", "title": "OutboundPaymentImportSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "outbound_payment_imports": { "$ref": "#/components/schemas/outbound_payment_import" } } }, "outbound_payment_import_pagination_meta": { "type": "object", "title": "OutboundPaymentImportPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "outbound_payment_import_multi_resource_response": { "type": "object", "title": "OutboundPaymentImportMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "outbound_payment_imports": { "type": "array", "items": { "$ref": "#/components/schemas/outbound_payment_import" } }, "meta": { "$ref": "#/components/schemas/outbound_payment_import_pagination_meta" } } }, "outbound_payment_import_entry": { "type": "object", "title": "Outbound Payment Import Entries", "description": "Import Entries are the individual rows of an outbound payment import, representing each payment to be created.", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/outbound_payment_import_entry_id" }, "created_at": { "$ref": "#/components/schemas/outbound_payment_import_entry_created_at" }, "processed_at": { "$ref": "#/components/schemas/outbound_payment_import_entry_processed_at" }, "amount": { "$ref": "#/components/schemas/outbound_payment_import_entry_amount" }, "scheme": { "$ref": "#/components/schemas/outbound_payment_scheme" }, "reference": { "$ref": "#/components/schemas/outbound_payment_import_entry_reference" }, "verification_result": { "$ref": "#/components/schemas/outbound_payment_import_entry_verification_result" }, "validation_errors": { "$ref": "#/components/schemas/outbound_payment_import_entry_validation_errors" }, "links": { "$ref": "#/components/schemas/outbound_payment_import_entry_links" }, "metadata": { "$ref": "#/components/schemas/outbound_payment_import_entry_metadata" } } }, "outbound_payment_import_entry_id": { "type": "string", "title": "OutboundPaymentImportEntryId", "description": "Unique identifier, beginning with \"IE\".", "example": "IE123" }, "outbound_payment_import_entry_created_at": { "type": "string", "title": "OutboundPaymentImportEntryCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "outbound_payment_import_entry_processed_at": { "type": "string", "nullable": true, "title": "OutboundPaymentImportEntryProcessedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this entry was processed.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "outbound_payment_import_entry_amount": { "type": "integer", "nullable": true, "title": "OutboundPaymentImportEntryAmount", "description": "Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).", "example": 1000 }, "outbound_payment_import_entry_reference": { "type": "string", "nullable": true, "title": "OutboundPaymentImportEntryReference", "description": "An optional reference for the outbound payment.", "example": "Invoice 12345" }, "outbound_payment_import_entry_metadata": { "type": "object", "nullable": true, "title": "OutboundPaymentImportEntryMetadata", "description": "Key-value store of custom data. Up to 3 keys are permitted, with\nkey names up to 50 characters and values up to 500 characters." }, "outbound_payment_import_entry_verification_result": { "type": "string", "nullable": true, "title": "OutboundPaymentImportEntryVerificationResult", "description": "The result of bank account holder verification, if performed.", "example": "full_match", "enum": [ "full_match", "partial_match", "no_match", "unable_to_match" ] }, "outbound_payment_import_entry_validation_errors": { "type": "object", "nullable": true, "title": "OutboundPaymentImportEntryValidationErrors", "description": "Per-field validation errors for this entry, keyed by resource type and then by field name.", "additionalProperties": false, "properties": { "outbound_payment": { "type": "object", "description": "Validation errors for the outbound payment fields.", "additionalProperties": false, "properties": { "amount": { "type": "array", "description": "Errors related to the amount field.", "items": { "type": "string" } }, "scheme": { "$ref": "#/components/schemas/outbound_payment_scheme" }, "recipient_bank_account": { "type": "array", "description": "Errors related to the recipient bank account.", "items": { "type": "string" } }, "reference": { "type": "array", "description": "Errors related to the reference field.", "items": { "type": "string" } } } } } }, "outbound_payment_import_entry_links": { "type": "object", "title": "OutboundPaymentImportEntryLinks", "description": "", "additionalProperties": false, "properties": { "outbound_payment_import": { "type": "string", "description": "ID of the associated import.", "example": "IM123" }, "outbound_payment": { "type": "string", "nullable": true, "description": "ID of the associated outbound payment, once the entry has been processed.", "example": "OUT123" }, "recipient_bank_account": { "type": "string", "nullable": true, "description": "ID of the recipient bank account.", "example": "BA123" } } }, "outbound_payment_import_entry_multi_resource_response": { "type": "object", "title": "OutboundPaymentImportEntryMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "outbound_payment_import_entries": { "type": "array", "items": { "$ref": "#/components/schemas/outbound_payment_import_entry" } }, "meta": { "type": "object", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } } } }, "payer_authorisation": { "type": "object", "title": "Payer Authorisations", "description": "\n Don't use Payer Authorisations for new integrations.\n It is deprecated in favour of\n \n Billing Requests. Use Billing Requests to build any future integrations.\n
\n\nPayer Authorisation resource acts as a wrapper for creating customer, bank account and mandate details in a single request.\nPayerAuthorisation API enables the integrators to build their own custom payment pages.\n\nThe process to use the Payer Authorisation API is as follows:\n\n 1. Create a Payer Authorisation, either empty or with already available information\n 2. Update the authorisation with additional information or fix any mistakes\n 3. Submit the authorisation, after the payer has reviewed their information\n 4. [coming soon] Redirect the payer to the verification mechanisms from the response of the Submit request (this will be introduced as a non-breaking change)\n 5. Confirm the authorisation to indicate that the resources can be created\n\nAfter the Payer Authorisation is confirmed, resources will eventually be created as it's an asynchronous process.\n\nTo retrieve the status and ID of the linked resources you can do one of the following:\n payer_authorisation_completed webhook (recommended)https://api.gocardless.com/events?payer_authorisation={id}&action=completed \n Note that the create and update endpoints behave differently than\n other existing create and update endpoints. The Payer Authorisation is still saved if incomplete data is provided.\n We return the list of incomplete data in the incomplete_fields along with the resources in the body of the response.\n The bank account details(account_number, bank_code & branch_code) must be sent together rather than splitting across different request for both create and update endpoints.\n
\n The API is designed to be flexible and allows you to collect information in multiple steps without storing any sensitive data in the browser or in your servers.\n
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.
", "example": "WINEBOX001" }, "payment_amount_refunded": { "type": "integer", "title": "PaymentAmountRefunded", "description": "Amount [refunded](#core-endpoints-refunds), in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).", "example": 150 }, "payment_app_fee_request": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "integer" } ], "title": "PaymentAppFeeRequest", "description": "The amount to be deducted from the payment as the OAuth app's fee, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).", "example": "100" }, "payment_app_fee_response": { "type": "integer", "nullable": true, "title": "PaymentAppFeeResponse", "description": "The amount to be deducted from the payment as the OAuth app''s fee,\nin the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).\n\nOnly present if the payment was created via an app.", "example": 100 }, "payment_status": { "title": "PaymentStatus", "description": "One of:\n\n- `pending_customer_approval`: we're waiting for the customer to approve this payment\n- `pending_submission`: the payment has been created, but not yet submitted to the banks\n- `submitted`: the payment has been submitted to the banks\n- `confirmed`: the payment has been confirmed as collected\n- `paid_out`: the payment has been included in a [payout](#core-endpoints-payouts)\n- `cancelled`: the payment has been cancelled\n- `customer_approval_denied`: the customer has denied approval for the payment. You should contact the customer directly\n- `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.\n- `charged_back`: the payment has been charged back", "example": "submitted", "enum": [ "pending_customer_approval", "pending_submission", "submitted", "confirmed", "paid_out", "cancelled", "customer_approval_denied", "failed", "charged_back" ], "type": "string" }, "payment_description": { "type": "string", "nullable": true, "title": "PaymentDescription", "description": "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](#appendix-compliance-requirements)).", "example": "One-off upgrade fee" }, "payment_sort_field": { "title": "PaymentSortField", "description": "Field by which to sort records.\nOne of:\n\n- `charge_date`\n- `amount`", "enum": [ "charge_date", "amount" ], "type": "string" }, "payment_sort_direction": { "title": "SortDirection", "description": "The direction to sort in.\nOne of:\n\n- `asc`\n- `desc`", "enum": [ "asc", "desc" ], "type": "string" }, "payment_fx": { "type": "object", "title": "PaymentFx", "description": "", "properties": { "exchange_rate": { "type": "string", "nullable": true, "description": "Rate used in the foreign exchange of the `amount` into the `fx_currency`.\nPresent only after a resource is paid out. Has up to 10 decimal places.", "example": "1.1234567890" }, "estimated_exchange_rate": { "type": "string", "nullable": true, "description": "Estimated rate that will be used in the foreign exchange of the `amount` into the `fx_currency`.\nThis will vary based on the prevailing market rate until the moment that it is paid out.\nPresent only before a resource is paid out. Has up to 10 decimal places.", "example": "1.1234567890" }, "fx_amount": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "integer" } ], "description": "Amount that was paid out in the `fx_currency` after foreign exchange.\nPresent only after the resource has been paid out.", "example": 1150 }, "fx_currency": { "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) 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.", "example": "EUR", "enum": [ "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK", "USD" ], "nullable": true, "type": "string" } } }, "payment_retry_if_possible": { "type": "boolean", "title": "PaymentRetryIfPossible", "description": "On failure, automatically retry the payment using [intelligent retries](/success-plus/overview). Default is `false`.Important: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus).
" }, "payment_faster_ach_request": { "type": "boolean", "nullable": true, "title": "PaymentFasterAchRequest", "description": "Set this to true or false in the request to create an ACH payment to\nexplicitly choose whether the payment should be processed through Faster\nACH or standard ACH, rather than relying on the presence or absence of the\ncharge date to indicate that." }, "payment_faster_ach_response": { "type": "boolean", "nullable": true, "title": "PaymentFasterAchResponse", "description": "This field indicates whether the ACH payment is processed through Faster\nACH or standard ACH.\n\nIt is only present in the API response for ACH payments." }, "payment_psu_interaction_type": { "title": "PaymentPsuInteractionType", "description": "Indicates how a Variable Recurring Payment (VRP) is initiated, by or on behalf of the payer.\n\n- `in_session`: The payer is actively participating in the payment creation session.\n- `off_session`: The payer is not present during the transaction, and the payment is initiated by the merchant based on an established consent (e.g., a recurring subscription payment).", "enum": [ "in_session", "off_session" ], "type": "string" }, "payment_links": { "type": "object", "title": "PaymentLinks", "description": "", "properties": { "mandate": { "type": "string", "description": "ID of the [mandate](#core-endpoints-mandates) against which this payment should be collected.", "example": "MD123" }, "creditor": { "type": "string", "description": "ID of [creditor](#core-endpoints-creditors) to which the collected payment will be sent.", "example": "CR123" }, "payout": { "type": "string", "description": "ID of [payout](#core-endpoints-payouts) which contains the funds from this payment.410 Gone.\n",
"additionalProperties": true,
"properties": {
"amount": {
"$ref": "#/components/schemas/payout_item_amount"
},
"type": {
"$ref": "#/components/schemas/payout_item_type"
},
"taxes": {
"$ref": "#/components/schemas/payout_item_taxes"
},
"links": {
"$ref": "#/components/schemas/payout_item_links"
}
}
},
"payout_item_include_2020_tax_cutover": {
"title": "PayoutItemInclude2020TaxCutover",
"description": "Boolean value indicating whether the API should return tax data for the cutover period of April to August 2020. Defaults to false.",
"enum": [
"true",
"false"
],
"type": "string"
},
"payout_item_amount": {
"type": "string",
"title": "PayoutItemAmount",
"description": "The positive (credit) or negative (debit) value of the item, in fractional currency;\nthe lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place.\nFor accuracy, we store some of our fees to greater precision than we can actually pay out (for example, a GoCardless fee we record might come to 0.5 pence, but it is not possible to send a payout via bank transfer including a half penny).
To calculate the final amount of the payout, we sum all of the items and then round to the nearest currency unit.
Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators.\n The Billing Request flow API should be used for your payment flows.
\n\nRedirect flows enable you to use GoCardless' [hosted payment pages](https://pay-sandbox.gocardless.com/AL000000AKFPFF) to set up mandates with your customers. These pages are fully compliant and have been translated into Danish, Dutch, French, German, Italian, Norwegian, Portuguese, Slovak, Spanish and Swedish.\n\nThe overall flow is:\n\n1. You [create](#redirect-flows-create-a-redirect-flow) a redirect flow for your customer, and redirect them to the returned redirect url, e.g. `https://pay.gocardless.com/flow/RE123`.\n\n2. Your customer supplies their name, email, address, and bank account details, and submits the form. This securely stores their details, and redirects them back to your `success_redirect_url` with `redirect_flow_id=RE123` in the querystring.\n\n3. You [complete](#redirect-flows-complete-a-redirect-flow) the redirect flow, which creates a [customer](#core-endpoints-customers), [customer bank account](#core-endpoints-customer-bank-accounts), and [mandate](#core-endpoints-mandates), and returns the ID of the mandate. You may wish to create a [subscription](#core-endpoints-subscriptions) or [payment](#core-endpoints-payments) at this point.\n\nOnce you have [completed](#redirect-flows-complete-a-redirect-flow) the redirect flow via the API, you should display a confirmation page to your customer, confirming that their Direct Debit has been set up. You can build your own page, or redirect to the one we provide in the `confirmation_url` attribute of the redirect flow.\n\nRedirect flows expire 30 minutes after they are first created. You cannot complete an expired redirect flow. For an integrator this is shorter and they will expire after 10 minutes.", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/redirect_flow_id" }, "description": { "$ref": "#/components/schemas/redirect_flow_description" }, "session_token": { "$ref": "#/components/schemas/redirect_flow_session_token" }, "scheme": { "$ref": "#/components/schemas/redirect_flow_scheme" }, "success_redirect_url": { "$ref": "#/components/schemas/redirect_flow_success_redirect_url" }, "confirmation_url": { "$ref": "#/components/schemas/redirect_flow_confirmation_url" }, "redirect_url": { "$ref": "#/components/schemas/redirect_flow_redirect_url" }, "created_at": { "$ref": "#/components/schemas/redirect_flow_created_at" }, "links": { "$ref": "#/components/schemas/redirect_flow_links" }, "metadata": { "$ref": "#/components/schemas/redirect_flow_metadata" }, "mandate_reference": { "$ref": "#/components/schemas/redirect_flow_mandate_reference" } } }, "redirect_flow_id": { "type": "string", "title": "RedirectFlowId", "description": "Unique identifier, beginning with \"RE\".", "example": "RE123456" }, "redirect_flow_identity": { "$ref": "#/components/schemas/redirect_flow_id" }, "redirect_flow_created_at": { "type": "string", "title": "RedirectFlowCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "redirect_flow_description": { "type": "string", "nullable": true, "title": "RedirectFlowDescription", "description": "A description of the item the customer is paying for. This will be shown on the hosted payment pages.", "example": "Standard subscription" }, "redirect_flow_session_token": { "type": "string", "title": "RedirectFlowSessionToken", "description": "The customer's session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.", "example": "SESS_wSs0uGYMISxzqOBq" }, "redirect_flow_scheme": { "title": "RedirectFlowScheme", "description": "The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer's bank account.", "example": "bacs", "enum": [ "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "pad", "sepa_core" ], "nullable": true, "type": "string" }, "redirect_flow_success_redirect_url": { "type": "string", "title": "RedirectFlowSuccessRedirectUrl", "description": "The URL to redirect to upon successful mandate setup. You must use a URL beginning `https` in the live environment.", "example": "https://example.com/pay/confirm" }, "redirect_flow_redirect_url": { "type": "string", "title": "RedirectFlowRedirectUrl", "description": "The URL of the hosted payment pages for this redirect flow. This is the URL you should redirect your customer to.", "example": "http://pay.gocardless.com/flow/RE123" }, "redirect_flow_mandate_reference": { "type": "string", "title": "RedirectFlowMandateReference", "description": "Mandate reference generated by GoCardless or submitted by an integrator." }, "redirect_flow_confirmation_url": { "type": "string", "title": "RedirectFlowConfirmationUrl", "description": "The URL of a confirmation page, which you may optionally redirect the customer to rather than use your own page, that confirms in their chosen language that their Direct Debit has been set up successfully. Only returned once the customer has set up their mandate via the payment pages and the redirect flow has been [completed](#redirect-flows-complete-a-redirect-flow), and only available for 15 minutes from when you complete the redirect flow. The structure of this URL may change at any time, so you should read it directly from the API response.", "example": "https://pay.gocardless.com/flow/RE123/success" }, "redirect_flow_metadata": { "type": "object", "title": "RedirectFlowMetadata", "description": "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.", "example": { "salesforce_id": "ABCD1234" } }, "redirect_flow_links": { "type": "object", "title": "RedirectFlowLinks", "description": "", "properties": { "creditor": { "type": "string", "description": "The [creditor](#core-endpoints-creditors) for whom the mandate will be created. The `name` of the creditor will be displayed on the payment page.", "example": "CR123" }, "mandate": { "type": "string", "description": "ID of [mandate](#core-endpoints-mandates) created by this redirect flow.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.
", "example": "WINEBOX001" }, "refund_amount_stringable": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "title": "RefundAmountStringable", "description": "Amount in minor unit (e.g. pence in GBP, cents in EUR).", "example": 150 }, "refund_amount": { "type": "integer", "title": "RefundAmount", "description": "Amount in minor unit (e.g. pence in GBP, cents in EUR).", "example": 150 }, "refund_total_amount_confirmation": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "title": "RefundTotalAmountConfirmation", "description": "Total expected refunded amount in minor unit (e.g. pence/cents/öre). If there are\nother partial refunds against this payment, this value should be the sum of the\nexisting refunds plus the amount of the refund being created.\nIt is possible to opt out of requiring total_amount_confirmation, please contact our support team for more information.
Deprecated: This field will be removed in a future API version. Use count to specify a number of payments instead.
Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.
", "example": "GOLDPLAN" }, "subscription_status": { "type": "string", "title": "SubscriptionStatus", "description": "One of:\n\n- `pending_customer_approval`: the subscription is waiting for customer approval before becoming active\n- `customer_approval_denied`: the customer did not approve the subscription\n- `active`: the subscription is currently active and will continue to create payments\n- `finished`: all of the payments scheduled for creation under this subscription have been created\n- `cancelled`: the subscription has been cancelled and will no longer create payments\n- `paused`: the subscription has been paused and will not create payments", "example": "active", "enum": [ "pending_customer_approval", "customer_approval_denied", "active", "finished", "cancelled", "paused" ] }, "subscription_upcoming_payments": { "type": "array", "title": "SubscriptionUpcomingPayments", "description": "Up to 10 upcoming payments with their amounts and charge dates.", "example": [ { "amount": 2500, "charge_date": "2014-11-03" } ], "items": { "type": "object", "properties": { "charge_date": { "type": "string", "description": "The date on which this payment will be charged.", "example": "2014-11-03", "format": "date" }, "amount": { "type": "integer", "description": "The amount of this payment, in minor unit (e.g. pence in GBP, cents in EUR).", "example": 2500 } } } }, "subscription_currency": { "type": "string", "title": "SubscriptionCurrency", "description": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently \"AUD\", \"CAD\", \"DKK\", \"EUR\", \"GBP\", \"NZD\", \"SEK\" and \"USD\" are supported.", "example": "EUR" }, "subscription_app_fee_stringable": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "integer" } ], "title": "SubscriptionAppFeeStringable", "description": "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).", "example": 100 }, "subscription_app_fee": { "type": "integer", "nullable": true, "title": "SubscriptionAppFee", "description": "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).", "example": 100 }, "subscription_retry_if_possible": { "type": "boolean", "title": "SubscriptionRetryIfPossible", "description": "On failure, automatically retry payments using [intelligent retries](/success-plus/overview). Default is `false`.Important: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus).
" }, "subscription_pause_cycles": { "type": "integer", "nullable": true, "title": "SubscriptionPauseCycles", "description": "The number of cycles to pause a subscription for. A cycle is one duration of `interval` and `interval_unit`. This should be a non zero positive value.\nFor AUD subscriptions with `interval_unit: weekly` the minimum value varies between `3` & `4` because of the [mandatory minimum waiting period](#subscriptions-resume-a-subscription).\nFor NZD subscriptions with `interval_unit: weekly` the minimum value is `2` because of the [mandatory minimum waiting period](#subscriptions-resume-a-subscription).", "example": 2 }, "subscription_earliest_charge_date_after_resume": { "type": "string", "nullable": true, "title": "SubscriptionEarliestChargeDateAfterResume", "description": "The earliest date that will be used as a `charge_date` on payments\ncreated for this subscription if it is resumed. Only present for `paused` subscriptions.\nThis value will change over time.", "example": "2014-11-03", "format": "date" }, "subscription_parent_plan_paused": { "type": "boolean", "title": "SubscriptionParentPlanPaused", "description": "Whether the parent plan of this subscription is paused." }, "subscription_links": { "type": "object", "title": "SubscriptionLinks", "description": "", "properties": { "mandate": { "type": "string", "description": "ID of the associated [mandate](#core-endpoints-mandates) which the subscription will create payments against.", "example": "MD123" } } }, "subscription_pagination_meta": { "type": "object", "title": "SubscriptionPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "subscription_single_resource_response": { "type": "object", "title": "SubscriptionSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "subscriptions": { "$ref": "#/components/schemas/subscription" } } }, "subscription_multi_resource_response": { "type": "object", "title": "SubscriptionMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/subscription" } }, "meta": { "$ref": "#/components/schemas/subscription_pagination_meta" } } }, "tax_rate": { "type": "object", "title": "Tax Rates", "description": "Tax rates from tax authority.\n\nWe also maintain a [static list of the tax rates for each jurisdiction](#appendix-tax-rates).", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/tax_rate_id" }, "jurisdiction": { "$ref": "#/components/schemas/tax_rate_jurisdiction" }, "type": { "$ref": "#/components/schemas/tax_rate_type" }, "percentage": { "$ref": "#/components/schemas/tax_rate_percentage" }, "start_date": { "$ref": "#/components/schemas/tax_rate_start_date" }, "end_date": { "$ref": "#/components/schemas/tax_rate_end_date" } } }, "tax_rate_id": { "type": "string", "title": "TaxRateId", "description": "The unique identifier created by the jurisdiction, tax type and version", "example": "GB_VAT_1" }, "tax_rate_identity": { "$ref": "#/components/schemas/tax_rate_id" }, "tax_rate_jurisdiction": { "type": "string", "title": "TaxRateJurisdiction", "description": "The jurisdiction this tax rate applies to", "example": "GBP" }, "tax_rate_type": { "type": "string", "title": "TaxRateType", "description": "The type of tax applied by this rate", "example": "VAT" }, "tax_rate_percentage": { "type": "string", "title": "TaxRatePercentage", "description": "The percentage of tax that is applied onto of GoCardless fees", "example": "20.0" }, "tax_rate_start_date": { "type": "string", "title": "TaxRateStartDate", "description": "Date at which GoCardless started applying the tax rate in the jurisdiction.", "example": "2014-01-01", "format": "date" }, "tax_rate_end_date": { "type": "string", "nullable": true, "title": "TaxRateEndDate", "description": "Date at which GoCardless stopped applying the tax rate for the jurisdiction.", "example": "2014-01-01", "format": "date" }, "tax_rate_pagination_meta": { "type": "object", "title": "TaxRatePaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "tax_rate_single_resource_response": { "type": "object", "title": "TaxRateSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "tax_rates": { "$ref": "#/components/schemas/tax_rate" } } }, "tax_rate_multi_resource_response": { "type": "object", "title": "TaxRateMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "tax_rates": { "type": "array", "items": { "$ref": "#/components/schemas/tax_rate" } }, "meta": { "$ref": "#/components/schemas/tax_rate_pagination_meta" } } }, "transferred_mandate": { "type": "object", "title": "Transferred Mandate", "description": "Mandates that have been transferred using Current Account Switch Service", "additionalProperties": true, "properties": { "encrypted_decryption_key": { "$ref": "#/components/schemas/transferred_mandate_encrypted_decryption_key" }, "public_key_id": { "$ref": "#/components/schemas/transferred_mandate_public_key_id" }, "encrypted_customer_bank_details": { "$ref": "#/components/schemas/transferred_mandate_encrypted_customer_bank_details" }, "links": { "$ref": "#/components/schemas/transferred_mandate_links" } } }, "transferred_mandate_encrypted_decryption_key": { "type": "string", "title": "TransferredMandateEncryptedDecryptionKey", "description": "Random AES-256 key used to encrypt bank account details, itself encrypted with your public key." }, "transferred_mandate_public_key_id": { "type": "string", "title": "TransferredMandatePublicKeyId", "description": "The ID of an RSA-2048 public key, from your JWKS, used to encrypt the AES key." }, "transferred_mandate_encrypted_customer_bank_details": { "type": "string", "title": "TransferredMandateEncryptedCustomerBankDetails", "description": "Encrypted customer bank account details, containing:\n`iban`, `account_holder_name`, `swift_bank_code`, `swift_branch_code`, `swift_account_number`" }, "transferred_mandate_links": { "type": "object", "title": "TransferredMandateLinks", "description": "", "properties": { "customer_bank_account": { "type": "string", "description": "The ID of the updated [customer_bank_account](#core-endpoints-customer-bank-accounts)", "example": "BA123" }, "mandate": { "type": "string", "description": "The ID of the transferred mandate", "example": "MD123" } } }, "transferred_mandate_single_resource_response": { "type": "object", "title": "TransferredMandateSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "transferred_mandates": { "$ref": "#/components/schemas/transferred_mandate" } } }, "verification_detail": { "type": "object", "title": "Verification Details", "description": "Verification details represent any information needed by GoCardless to verify a creditor.\n\nRestricted:\n These endpoints are restricted to customers who want to collect their merchant's\n verification details and pass them to GoCardless via our API. Please get in\n touch if you wish to enable this feature on your\n account.
", "additionalProperties": true, "properties": { "name": { "$ref": "#/components/schemas/verification_detail_name" }, "company_number": { "$ref": "#/components/schemas/verification_detail_company_number" }, "description": { "$ref": "#/components/schemas/verification_detail_description" }, "address_line1": { "$ref": "#/components/schemas/verification_detail_address_line1" }, "address_line2": { "$ref": "#/components/schemas/verification_detail_address_line2" }, "address_line3": { "$ref": "#/components/schemas/verification_detail_address_line3" }, "city": { "$ref": "#/components/schemas/verification_detail_city" }, "postal_code": { "$ref": "#/components/schemas/verification_detail_postal_code" }, "region": { "$ref": "#/components/schemas/verification_detail_region" }, "country_code": { "$ref": "#/components/schemas/verification_detail_country_code" }, "directors": { "$ref": "#/components/schemas/verification_detail_directors" }, "links": { "$ref": "#/components/schemas/verification_detail_links" } } }, "verification_detail_id": { "type": "string", "title": "VerificationDetailId", "description": "Unique identifier of the creditor these details are being stored against,\nbeginning with \"CR\".", "example": "CR123" }, "verification_detail_name": { "type": "string", "title": "VerificationDetailName", "description": "The company's legal name.", "example": "Acme Limited" }, "verification_detail_company_number": { "type": "string", "title": "VerificationDetailCompanyNumber", "description": "The company's registration number.", "example": "07495895" }, "verification_detail_description": { "type": "string", "title": "VerificationDetailDescription", "description": "A summary describing what the company does.", "example": "Wine and cheese seller" }, "verification_detail_address_line1": { "type": "string", "title": "VerificationDetailAddressLine1", "description": "The first line of the company's address.", "example": "338-346 Goswell Road" }, "verification_detail_address_line2": { "type": "string", "nullable": true, "title": "VerificationDetailAddressLine2", "description": "The second line of the company's address.", "example": "Islington" }, "verification_detail_address_line3": { "type": "string", "nullable": true, "title": "VerificationDetailAddressLine3", "description": "The third line of the company's address." }, "verification_detail_city": { "type": "string", "title": "VerificationDetailCity", "description": "The city of the company's address.", "example": "London" }, "verification_detail_postal_code": { "type": "string", "title": "VerificationDetailPostalCode", "description": "The company's postal code.", "example": "EC1V 7LQ" }, "verification_detail_region": { "type": "string", "nullable": true, "title": "VerificationDetailRegion", "description": "The region of the company's address.", "example": "Essex" }, "verification_detail_country_code": { "type": "string", "title": "VerificationDetailCountryCode", "description": "The country code of the company's address.", "example": "GB" }, "verification_detail_director": { "type": "object", "title": "VerificationDetailDirector", "description": "A primary director of the company represented by the creditor.", "additionalProperties": false, "required": [ "given_name", "family_name", "date_of_birth", "street", "postal_code", "city", "country_code" ], "properties": { "given_name": { "type": "string", "description": "The person's given name.", "example": "Tom" }, "family_name": { "type": "string", "description": "The person's family name.", "example": "Jones" }, "date_of_birth": { "type": "string", "description": "The person's date of birth.", "example": "1986-02-19" }, "street": { "type": "string", "description": "The street of the person's address." }, "city": { "type": "string", "description": "The city of the person's address.", "example": "London" }, "postal_code": { "type": "string", "description": "The person's postal code.", "example": "EC1V 7LQ" }, "country_code": { "type": "string", "description": "[ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)", "example": "GB" } } }, "verification_detail_directors": { "type": "array", "title": "VerificationDetailDirectors", "description": "The company's directors.", "items": { "$ref": "#/components/schemas/verification_detail_director" } }, "verification_detail_links": { "type": "object", "title": "VerificationDetailLinks", "description": "", "properties": { "creditor": { "type": "string", "description": "ID of the [creditor](#core-endpoints-creditors)", "example": "CR123" } } }, "verification_detail_pagination_meta": { "type": "object", "title": "VerificationDetailPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "verification_detail_single_resource_response": { "type": "object", "title": "VerificationDetailSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "verification_details": { "$ref": "#/components/schemas/verification_detail" } } }, "verification_detail_multi_resource_response": { "type": "object", "title": "VerificationDetailMultiResourceResponse", "description": "A list of verification details", "additionalProperties": false, "properties": { "verification_details": { "type": "array", "items": { "$ref": "#/components/schemas/verification_detail" } }, "meta": { "$ref": "#/components/schemas/verification_detail_pagination_meta" } } }, "webhook": { "type": "object", "title": "Webhooks", "description": "Basic description of a webhook", "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/webhook_id" }, "created_at": { "$ref": "#/components/schemas/webhook_created_at" }, "url": { "$ref": "#/components/schemas/webhook_url" }, "request_headers": { "$ref": "#/components/schemas/webhook_request_headers" }, "request_body": { "$ref": "#/components/schemas/webhook_request_body" }, "response_code": { "$ref": "#/components/schemas/webhook_response_code" }, "response_body": { "$ref": "#/components/schemas/webhook_response_body" }, "response_body_truncated": { "$ref": "#/components/schemas/webhook_response_body_truncated" }, "response_headers": { "$ref": "#/components/schemas/webhook_response_headers" }, "response_headers_content_truncated": { "$ref": "#/components/schemas/webhook_response_headers_content_truncated" }, "response_headers_count_truncated": { "$ref": "#/components/schemas/webhook_response_headers_count_truncated" }, "is_test": { "$ref": "#/components/schemas/webhook_is_test" }, "successful": { "$ref": "#/components/schemas/webhook_successful" } } }, "webhook_id": { "type": "string", "title": "WebhookId", "description": "Unique identifier, beginning with \"WB\".", "example": "WB123" }, "webhook_identity": { "$ref": "#/components/schemas/webhook_id" }, "webhook_created_at": { "type": "string", "title": "WebhookCreatedAt", "description": "Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created.", "example": "2014-01-01T12:00:00.000Z", "format": "date-time" }, "webhook_url": { "type": "string", "title": "WebhookUrl", "description": "URL the webhook was POST-ed to", "example": "https://example.com/webhooks" }, "webhook_request_headers": { "type": "object", "title": "WebhookRequestHeaders", "description": "The request headers sent with the webhook" }, "webhook_request_body": { "type": "string", "title": "WebhookRequestBody", "description": "The body of the request sent to the webhook URL" }, "webhook_response_code": { "type": "integer", "nullable": true, "title": "WebhookResponseCode", "description": "The response code from the webhook request" }, "webhook_response_headers": { "type": "object", "nullable": true, "title": "WebhookResponseHeaders", "description": "The headers sent with the response from the webhook URL" }, "webhook_response_body": { "type": "string", "nullable": true, "title": "WebhookResponseBody", "description": "The body of the response from the webhook URL" }, "webhook_is_test": { "type": "boolean", "title": "WebhookIsTest", "description": "Boolean value showing whether this was a demo webhook for testing" }, "webhook_response_body_truncated": { "type": "boolean", "nullable": true, "title": "WebhookResponseBodyTruncated", "description": "Boolean value indicating the webhook response body was truncated" }, "webhook_response_headers_content_truncated": { "type": "boolean", "nullable": true, "title": "WebhookResponseHeadersContentTruncated", "description": "Boolean indicating the content of response headers was truncated" }, "webhook_response_headers_count_truncated": { "type": "boolean", "nullable": true, "title": "WebhookResponseHeadersCountTruncated", "description": "Boolean indicating the number of response headers was truncated" }, "webhook_successful": { "type": "boolean", "title": "WebhookSuccessful", "description": "Boolean indicating whether the request was successful or failed" }, "webhook_pagination_meta": { "type": "object", "title": "WebhookPaginationMeta", "description": "Cursor pagination information", "additionalProperties": false, "required": [ "cursors", "limit" ], "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "type": "string", "nullable": true, "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "nullable": true, "description": "Cursor pointing to the start of the desired set." } } } } }, "webhook_single_resource_response": { "type": "object", "title": "WebhookSingleResourceResponse", "description": "", "additionalProperties": false, "properties": { "webhooks": { "$ref": "#/components/schemas/webhook" } } }, "webhook_multi_resource_response": { "type": "object", "title": "WebhookMultiResourceResponse", "description": "", "additionalProperties": false, "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/webhook" } }, "meta": { "$ref": "#/components/schemas/webhook_pagination_meta" } } }, "pagination_meta": { "description": "Cursor pagination information", "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "cursors": { "type": "object", "properties": { "before": { "type": "string", "description": "Cursor pointing to the end of the desired set." }, "after": { "type": "string", "description": "Cursor pointing to the start of the desired set." } }, "additionalProperties": false, "required": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "cursors", "limit" ] }, "error": { "description": "Generic error", "type": "object", "properties": { "code": { "type": "integer" }, "documentation_url": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "field": { "type": "string" }, "request_pointer": { "type": "string" }, "message": { "type": "string" }, "metadata": { "type": "object" }, "links": { "type": "object" } }, "required": [ "message" ] } }, "message": { "type": "string" }, "request_id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "errors", "message", "request_id" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "parameters": { "GoCardlessVersionHeader": { "name": "GoCardless-Version", "schema": { "type": "string" }, "in": "header", "example": "2015-07-06", "required": true } } }, "paths": { "/balances": { "get": { "operationId": "list_balance", "summary": "List balances", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of balances for a given creditor. This endpoint is rate limited to 60 requests per minute.", "tags": [ "Balance" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "creditor", "in": "query", "required": true, "schema": { "type": "string", "example": "CR123" }, "description": "ID of a [creditor](#core-endpoints-creditors)." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/balance_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.balances.list(\n params: {\n creditor: \"CR123\",\n }\n).records" }, { "lang": "Python", "label": "Python", "source": "client.balances.list(params={\n \"creditor\": \"CR123\",\n}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "await client.balances.list({\n creditor: \"CR123\",\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->balances()->list([\n \"params\" => [\n \"creditor\" => \"CR123\",\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.balances().\n all().\n withCreditor(\"CR123\").\n execute();" }, { "lang": "Go", "label": "Go", "source": "params := gocardless.BalanceListParams{\n Creditor: \"CR123\",\n}\n\nresponse, err := client.Balances.List(ctx, params)" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.BalanceListRequest()\n{\n Creditor = \"CR123\",\n};\n\nclient.Balances.All(request);" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/balances?creditor=CR123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"balances\": [\n {\n \"balance_type\": \"pending_payments_submitted\",\n \"amount\": 365000,\n \"currency\": \"EUR\",\n \"last_updated_at\": \"2025-03-17T11:08:04.926Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n },\n {\n \"balance_type\": \"pending_payouts\",\n \"amount\": 0,\n \"currency\": \"EUR\",\n \"last_updated_at\": \"2025-03-17T11:48:14.416Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n },\n {\n \"balance_type\": \"confirmed_funds\",\n \"amount\": 421198,\n \"currency\": \"EUR\",\n \"last_updated_at\": \"2025-03-17T11:15:52.201Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n ],\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n }\n}" } ] } }, "/bank_account_details/{customer_bank_account_id}": { "get": { "operationId": "get_bank_account_details", "summary": "Get encrypted bank details", "description": "Returns bank account details in the flattened JSON Web Encryption format described in RFC 7516.\n\nYou must specify a `Gc-Key-Id` header when using this endpoint. See [Public Key Setup](https://developer.gocardless.com/gc-embed/bank-details-access#public_key_setup) for more details.\n\nRestricted: This endpoint is restricted to organisations with the Encrypted Bank Details Access upgrade
\n\nNote: See our [Security Requirements](#appendix-security-requirements) before using this feature
", "tags": [ "Bank Account Detail" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "customer_bank_account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer bank account id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bank_account_detail_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.bank_account_details.get(\"BA123\",\n headers: { 'Gc-Key-Id' => 'PK123' }\n)" }, { "lang": "Python", "label": "Python", "source": "client.bank_account_details.get(\"BA123\",\n headers={'Gc-Key-Id': 'PK123'}\n)" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.bankAccountDetails.find(\"BA123\", {\n \"Gc-Key-Id\": \"PK123\",\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->bankAccountDetails()->get(\"BA123\", [\n \"headers\" => ['Gc-Key-Id' => 'PK123']\n]);" }, { "lang": "Java", "label": "Java", "source": "client.bankAccountDetails().get(\"BA123\").withHeader(\"Gc-Key-Id\", \"PK123\").execute();" }, { "lang": "Go", "label": "Go", "source": "headers := map[string]string{\n \"Gc-Key-Id\": \"PK123\",\n}\n\nbankAccountDetails, err := client.BankAccountDetails.Get(\n ctx,\n \"BA123\",\n gocardless.BankAccountDetailGetParams{},\n gocardless.WithHeaders(headers),\n)" }, { "lang": "C#", "label": ".NET", "source": "var requestSettings = new GoCardless.Internals.RequestSettings\n{\n CustomiseRequestMessage = (request) =>\n {\n request.Headers.Add(\"Gc-Key-Id\", \"PK123\");\n }\n};\n\nvar resp = await client.BankAccountDetails.GetAsync(\"BA123\", null, requestSettings);" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/bank_account_details/BA123 HTTP/1.1\nContent-Type: application/json\nGc-Key-Id: PK123\n\nHTTP/1.1 200 (OK)\nLocation: /bank_account_details/BA123\nContent-Type: application/json\n{\n \"bank_account_details\": {\n \"protected\": \"eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJraWQiOiJiY2RkNDkzMmZhNjMxODY0MjI3YjhkZEZiMDdkMjQ5MDgyOGEzYWQ5OWM1OTYxNzc3ZDBjZTMzMDUyYjk5OGFiIn0\",\n \"encrypted_key\": \"pEQHNX_jCjKLIhZMa27C8cXgIlu7qUdrEcPuRwQw9EZyA_3vHG99gdd7YGQapVbSGEG43Hg5gi33Sgjsuekp6CumRFoBIKR7mANk5LUgfy6jFVFAC98RMiJ2H8yTBJlRiLonPRBILStNI8F7VU7cqqOOuCn7yeoeiJ7buSkqDW_ds9wrPC3uJgLZGyxPLU81R2WrE6b7hLVCpShLCBzH76wL3cPD5nYNT3eb5vqGl8SMb_mecZ-UnE5wfAzZhbU1CJ4qtlgFFiMt6HLFPvVAJBHlPdZaFcKotSjhOhk1rsySLrwKG9HmIBLykhED251jiIOyxTXIlNCzSMs23_R4XA\",\n \"iv\": \"6H4MLnhZGnwaWlQ2\",\n \"ciphertext\": \"Cntt_wZlkK4Ui7xI-BtAqf9V-FF41Cz8RxJd5KUGQJac\",\n \"tag\": \"WoaSncwUeLfU3IjgeFYtSQ\"\n }\n}" } ] } }, "/bank_account_holder_verifications": { "post": { "operationId": "create_bank_account_holder_verification", "summary": "Create a bank account holder verification.", "description": "Verify the account holder of the bank account. A complete verification can be attached when creating an outbound payment. \nThis endpoint allows partner merchants to create Confirmation of Payee checks on customer bank accounts before sending outbound payments.\n\nRestricted: This endpoint is restricted to organisations with Outbound Payments enabled
", "tags": [ "Bank Account Holder Verification" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bank_account_holder_verification_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_account_holder_verifications": { "type": "object", "additionalProperties": false, "required": [ "type", "links" ], "properties": { "type": { "$ref": "#/components/schemas/bank_account_holder_verification_type" }, "reference": { "$ref": "#/components/schemas/bank_account_holder_verification_reference" }, "links": { "type": "object", "additionalProperties": false, "required": [ "bank_account" ], "properties": { "bank_account": { "$ref": "#/components/schemas/bank_account_holder_verification_bank_account" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.bank_account_holder_verifications.create(\n params: {\n type: \"confirmation_of_payee\",\n links: {\n bank_account: \"BA123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.bank_account_holder_verifications.create(params={\n \"type\": \"confirmation_of_payee\",\n \"links\": {\n \"bank_account\": \"BA123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const verification = await client.bankAccountHolderVerifications.create({\n type: \"confirmation_of_payee\",\n links: {\n bank_account: \"BA123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->bankAccountHolderVerifications()->create([\n \"params\" => [\n \"type\" => \"confirmation_of_payee\",\n \"links\" => [\n \"bank_account\" => \"BA123\"\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.BankAccountHolderVerificationService.BankAccountHolderVerificationCreateRequest.Type;\n\nclient.bankAccountHolderVerifications().create()\n .withType(Type.CONFIRMATION_OF_PAYEE)\n .withLinksBankAccount(\"BA123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "bankAccountHolderVerificationCreateParams := gocardless.BankAccountHolderVerificationCreateParams{\n Type: \"confirmation_of_payee\",\n Links: gocardless.BankAccountHolderVerificationCreateParamsLinks{\n BankAccount: \"BA123\",\n },\n}\n\nverification, err := client.BankAccountHolderVerifications.Create(ctx, bankAccountHolderVerificationCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var verificationLinks = new GoCardless.Services.BankAccountHolderVerificationCreateRequest.BankAccountHolderVerificationLinks\n{\n BankAccount = \"BA123\"\n};\n\nvar resp = await client.BankAccountHolderVerifications.CreateAsync(\n new GoCardless.Services.BankAccountHolderVerificationCreateRequest()\n {\n Type = GoCardless.Services.BankAccountHolderVerificationCreateRequest.BankAccountHolderVerificationType.ConfirmationOfPayee,\n Links = verificationLinks,\n }\n);" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/bank_account_holder_verifications HTTP/1.1\nContent-Type: application/json\n{\n \"bank_account_holder_verifications\": {\n \"type\": \"confirmation_of_payee\",\n \"links\": {\n \"bank_account\": \"BA123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nContent-Type: application/json\n{\n \"bank_account_holder_verifications\": {\n \"id\": \"BAHV123\",\n \"type\": \"confirmation_of_payee\",\n \"result\": \"partial_match\",\n \"status\": \"pending\"\n }\n}" } ] } }, "/bank_account_holder_verifications/{bank_account_holder_verification_id}": { "get": { "operationId": "get_bank_account_holder_verifications", "summary": "Get a bank account holder verification.", "description": "Fetches a bank account holder verification by ID.", "tags": [ "Bank Account Holder Verification" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "bank_account_holder_verification_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The bank account holder verification id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bank_account_holder_verification_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.bank_account_holder_verifications.get(\"BAHV123\")" }, { "lang": "Python", "label": "Python", "source": "client.bank_account_holder_verifications.get(\"BAHV123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.bankAccountHolderVerifications.find(\"BAHV123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->bankAccountHolderVerifications()->get(\"BAHV123\");" }, { "lang": "Java", "label": "Java", "source": "client.bankAccountHolderVerifications().get(\"BAHV123\").execute();" }, { "lang": "Go", "label": "Go", "source": "verification, err := client.BankAccountHolderVerifications.Get(ctx, \"BAHV123\")" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BankAccountHolderVerifications.GetAsync(\"BAHV123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/bank_account_holder_verifications/BAHV123\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"bank_account_holder_verifications\": {\n \"id\": \"BAHV123\",\n \"type\": \"confirmation_of_payee\",\n \"result\": \"partial_match\",\n \"status\": \"pending\",\n \"actual_account_name\": null\n }\n}\n\nGET https://api.gocardless.com/bank_account_holder_verifications/BAHV124\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"bank_account_holder_verifications\": {\n \"id\": \"BAHV123\",\n \"type\": \"confirmation_of_payee\",\n \"result\": \"partial_match\",\n \"status\": \"completed\",\n \"actual_account_name\": \"Test Recipient\"\n }\n}" } ] } }, "/bank_authorisations": { "post": { "operationId": "create_bank_authorisation", "summary": "Create a Bank Authorisation", "description": "Create a Bank Authorisation.\n\nRestricted: this endpoint is restricted as the authorisation must be used within a\ncheckout flow that meets regulatory requirements for each payment\nscheme. Integrators should use a Billing Request Flow to do this.
\nIf you would like to enable bank authorisations, you will need to go through a separate compliance process.\nFor more details please get in touch.
Important: All properties associated with subscription_request and instalment_schedule_request are only supported for ACH and PAD schemes.
Note: Pay by Bank is only available for transactions in GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries. We will be adding other countries soon.
\n\nWarning: by default, the ability to provide a custom mandate reference is switched off. The banking system rules for valid references are quite complex, and we recommend allowing GoCardless to generate it. If you would like to provide custom references, please contact support.
", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_requests": { "type": "object", "additionalProperties": false, "properties": { "mandate_request": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/billing_request_currency" }, "scheme": { "$ref": "#/components/schemas/billing_request_scheme" }, "verify": { "$ref": "#/components/schemas/billing_request_mandate_request_verify" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "reference": { "$ref": "#/components/schemas/mandate_reference" }, "description": { "$ref": "#/components/schemas/billing_request_description" }, "constraints": { "$ref": "#/components/schemas/billing_request_mandate_request_constraints" }, "sweeping": { "$ref": "#/components/schemas/billing_request_sweeping" }, "authorisation_source": { "$ref": "#/components/schemas/billing_request_authorisation_source" }, "funds_settlement": { "$ref": "#/components/schemas/billing_request_funds_settlement" }, "consent_type": { "$ref": "#/components/schemas/billing_request_consent_type" } } }, "payment_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/billing_request_description" }, "currency": { "$ref": "#/components/schemas/billing_request_payment_currency" }, "scheme": { "$ref": "#/components/schemas/billing_request_payment_scheme" }, "amount": { "$ref": "#/components/schemas/billing_request_amount_stringable" }, "funds_settlement": { "$ref": "#/components/schemas/billing_request_funds_settlement" }, "app_fee": { "$ref": "#/components/schemas/billing_request_app_fee_stringable" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "reference": { "$ref": "#/components/schemas/billing_request_reference" }, "retry_if_possible": { "type": "boolean", "description": "On failure, automatically retry payments using [intelligent retries](/success-plus/overview). Default is `false`.Important: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus).
Important: This is not applicable to Pay by Bank and VRP payments.
" } } }, "subscription_request": { "type": "object", "additionalProperties": false, "required": [ "amount", "currency", "interval_unit" ], "properties": { "amount": { "$ref": "#/components/schemas/subscription_amount_stringable" }, "currency": { "$ref": "#/components/schemas/subscription_currency" }, "interval_unit": { "$ref": "#/components/schemas/subscription_interval_unit" }, "interval": { "$ref": "#/components/schemas/subscription_interval_stringable" }, "app_fee": { "$ref": "#/components/schemas/subscription_app_fee_stringable" }, "count": { "$ref": "#/components/schemas/subscription_count_stringable" }, "day_of_month": { "$ref": "#/components/schemas/subscription_day_of_month_stringable" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "month": { "$ref": "#/components/schemas/subscription_month" }, "name": { "$ref": "#/components/schemas/subscription_name" }, "payment_reference": { "$ref": "#/components/schemas/billing_request_subscription_payment_reference" }, "start_date": { "$ref": "#/components/schemas/billing_request_subscription_request_start_date" }, "retry_if_possible": { "$ref": "#/components/schemas/subscription_retry_if_possible" } } }, "instalment_schedule_request": { "type": "object", "additionalProperties": false, "properties": { "name": { "$ref": "#/components/schemas/instalment_schedule_name" }, "currency": { "$ref": "#/components/schemas/billing_request_ach_pad_currency" }, "total_amount": { "$ref": "#/components/schemas/instalment_schedule_total_amount_stringable" }, "payment_reference": { "$ref": "#/components/schemas/billing_request_subscription_payment_reference" }, "app_fee": { "$ref": "#/components/schemas/subscription_app_fee_stringable" }, "instalments_with_dates": { "$ref": "#/components/schemas/billing_request_instalments_with_dates_stringable" }, "instalments_with_schedule": { "$ref": "#/components/schemas/billing_request_instalments_with_schedule_stringable" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "retry_if_possible": { "$ref": "#/components/schemas/instalment_schedule_retry_if_possible" } } }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "links": { "type": "object", "description": "", "additionalProperties": false, "properties": { "customer": { "type": "string", "description": "ID of the [customer](#core-endpoints-customers) against which this request should be made.", "example": "CU123" }, "customer_bank_account": { "type": "string", "description": "(Optional) ID of the [customer_bank_account](#core-endpoints-customer-bank-accounts) against which this request should be made.\n", "example": "BA123" }, "creditor": { "type": "string", "description": "ID of the associated [creditor](#core-endpoints-creditors). Only required if your account manages multiple creditors.", "example": "CR123" } } }, "fallback_enabled": { "$ref": "#/components/schemas/billing_request_fallback_enabled" }, "purpose_code": { "$ref": "#/components/schemas/billing_request_purpose_code" }, "payment_purpose_code": { "$ref": "#/components/schemas/billing_request_payment_purpose_code" }, "payment_context_code": { "$ref": "#/components/schemas/billing_request_payment_context_code" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.create(\n params: {\n payment_request: {\n description: \"First Payment\",\n amount: \"500\",\n currency: \"GBP\",\n },\n mandate_request: {\n scheme: \"bacs\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.create(params={\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"amount\": \"500\",\n \"currency\": \"GBP\",\n },\n \"mandate_request\": {\n \"scheme\": \"bacs\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const billingRequest = await client.billingRequests.create({\n payment_request: {\n description: \"First Payment\",\n amount: 500,\n currency: \"GBP\",\n },\n mandate_request: {\n scheme: \"bacs\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->create([\n \"params\" => [\n \"payment_request\" => [\n \"description\" => \"First Payment\",\n \"amount\" => \"500\",\n \"currency\" => \"GBP\",\n ],\n \"mandate_request\" => [\n \"scheme\" => \"bacs\"\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "BillingRequest billingRequest = client.billingRequests().create()\n .withPaymentRequestDescription(\"First Payment\")\n .withPaymentRequestAmount(500)\n .withPaymentRequestCurrency(\"GBP\")\n .withMandateRequestScheme(\"bacs\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestCreateParams := gocardless.BillingRequestCreateParams{\n PaymentRequest: &gocardless.BillingRequestCreateParamsPaymentRequest{\n Amount: 1000,\n Currency: \"GBP\",\n Description: \"First Payment\",\n },\n MandateRequest: &gocardless.BillingRequestCreateParamsMandateRequest{\n Scheme: \"bacs\",\n },\n}\n\nbillingRequest, err := client.BillingRequests.Create(ctx, billingRequestCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var paymentRequest = new GoCardless.Services.BillingRequestCreateRequest.BillingRequestPaymentRequest\n{\n Description = \"First payment\",\n Amount = 500,\n Currency = \"GBP\",\n};\n\nvar mandateRequest = new GoCardless.Services.BillingRequestCreateRequest.BillingRequestMandateRequest\n{\n Scheme = \"bacs\",\n};\n\nvar resp = await client.BillingRequests.CreateAsync(\n new GoCardless.Services.BillingRequestCreateRequest()\n {\n PaymentRequest = paymentRequest,\n MandateRequest = mandateRequest,\n }\n);\n\nGoCardless.Resources.BillingRequest billingRequest = resp.BillingRequest;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests HTTP/1.1\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"amount\": \"500\",\n \"currency\": \"GBP\"\n },\n \"mandate_request\": {\n \"scheme\": \"bacs\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /billing_requests/BRQ123\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"pending\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_billing_detail\": \"CBD123\"\n },\n \"actions\": [\n {\n \"type\": \"choose_currency\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_customer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"choose_currency\"\n ],\n \"status\": \"pending\",\n \"collect_customer_details\": {\n \"incomplete_fields\": {\n \"customer\": [\n \"email\",\n \"given_name\",\n \"family_name\"\n ],\n \"customer_billing_detail\": [\n \"address_line1\",\n \"city\",\n \"postal_code\",\n \"country_code\"\n ]\n }\n }\n },\n {\n \"type\": \"select_institution\",\n \"required\": false,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"collect_bank_account\",\n \"required\": true,\n \"completes_actions\": [\n \"choose_currency\"\n ],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"bank_authorisation\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"collect_bank_account\"\n ],\n \"status\": \"pending\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": null,\n \"family_name\": null,\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_billing_detail\": {\n \"id\": \"CBD123\",\n \"created_at\": \"2021-03-22T12:20:04.374Z\",\n \"address_line1\": null,\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": null,\n \"swedish_identity_number\": null,\n \"danish_identity_number\": null\n }\n }\n }\n}" } ] }, "get": { "operationId": "list_billing_request", "summary": "List Billing Requests", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your billing requests.", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/billing_request_status" } }, { "name": "customer", "in": "query", "required": false, "schema": { "type": "string", "example": "CU123" }, "description": "ID of a [customer](#core-endpoints-customers). If specified, this endpoint will return all requests for the given customer." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.list" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.list().records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const billingRequests = await client.billingRequests.list();" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->list();" }, { "lang": "Java", "label": "Java", "source": "for (BillingRequest billingRequest : client.billingRequests().all().execute()) {\n System.out.println(billingRequest.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "billingRequestListParams := gocardless.BillingRequestListParams{}\nbillingRequestListResult, err := client.BillingRequests.List(ctx, billingRequestListParams)\nfor _, billingRequest := range billingRequestListResult.BillingRequests {\n fmt.Println(billingRequest.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var billingRequestListResponse = client.BillingRequests.All();\nforeach (GoCardless.Resources.BillingRequest billingRequest in billingRequestListResponse)\n{\n Console.WriteLine(billingRequest.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/billing_requests HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"billing_requests\": [\n {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T16:23:48.486Z\",\n \"status\": \"pending\",\n \"mandate_request\": null,\n \"payment_request\": {\n \"description\": \"£5 Top Up\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_billing_detail\": \"CBD123\",\n \"customer_bank_account\": \"BA123\"\n }\n }\n ]\n}" } ] } }, "/billing_requests/{billing_request_id}/actions/collect_customer_details": { "post": { "operationId": "collect_customer_details_billing_request", "summary": "Collect customer details", "description": "If the billing request has a pendingcollect_customer_details\naction, this endpoint can be used to collect the details in order to\ncomplete it.\n\nThe endpoint takes the same payload as Customers, but checks that the\ncustomer fields are populated correctly for the billing request scheme.\n\nWhatever is provided to this endpoint is used to update the referenced\ncustomer, and will take effect immediately after the request is\nsuccessful.",
"tags": [
"Billing Request"
],
"parameters": [
{
"$ref": "#/components/parameters/GoCardlessVersionHeader"
},
{
"name": "billing_request_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The billing request id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/billing_request_single_resource_response"
}
}
},
"description": "Action completed successfully"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "Unauthorised",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "Internal Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"billing_requests": {
"type": "object",
"additionalProperties": false,
"properties": {
"customer": {
"type": "object",
"properties": {
"email": {
"$ref": "#/components/schemas/customer_email"
},
"given_name": {
"$ref": "#/components/schemas/customer_given_name"
},
"family_name": {
"$ref": "#/components/schemas/customer_family_name"
},
"company_name": {
"$ref": "#/components/schemas/customer_company_name"
},
"language": {
"type": "string",
"nullable": true,
"description": " [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see [compliance requirements](#appendix-compliance-requirements)). Currently only \"en\", \"fr\", \"de\", \"pt\", \"es\", \"it\", \"nl\", \"da\", \"nb\", \"sl\", \"sv\" are supported. If this is not provided and a customer was linked during billing request creation, the linked customer language will be used. Otherwise, the language is default to \"en\".",
"example": "en"
},
"phone_number": {
"$ref": "#/components/schemas/customer_phone_number"
},
"metadata": {
"$ref": "#/components/schemas/customer_metadata"
}
}
},
"customer_billing_detail": {
"type": "object",
"properties": {
"address_line1": {
"$ref": "#/components/schemas/customer_address_line1"
},
"address_line2": {
"$ref": "#/components/schemas/customer_address_line2"
},
"address_line3": {
"$ref": "#/components/schemas/customer_address_line3"
},
"city": {
"$ref": "#/components/schemas/customer_city"
},
"region": {
"$ref": "#/components/schemas/customer_region"
},
"postal_code": {
"$ref": "#/components/schemas/customer_postal_code"
},
"country_code": {
"$ref": "#/components/schemas/customer_country_code"
},
"swedish_identity_number": {
"$ref": "#/components/schemas/customer_swedish_identity_number"
},
"danish_identity_number": {
"$ref": "#/components/schemas/customer_danish_identity_number"
},
"ip_address": {
"$ref": "#/components/schemas/mandate_payer_ip_address"
}
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "Ruby",
"label": "Ruby",
"source": "@client.billing_requests.collect_customer_details(\"BR123\", {\n params: {\n customer: {\n email: \"alice@example.com\",\n given_name: \"Alice\",\n family_name: \"Smith\",\n },\n customer_billing_detail: {\n address_line1: \"1 Somewhere Lane\"\n }\n }\n})"
},
{
"lang": "Python",
"label": "Python",
"source": "client.billing_requests.collect_customer_details(\"BR123\", params={\n \"customer\": {\n \"email\": \"alice@example.com\",\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\"\n },\n \"customer_billing_detail\": {\n \"address_line1\": \"1 Somewhere Lane\"\n }\n})"
},
{
"lang": "JavaScript",
"label": "JavaScript",
"source": "const resp = await client.billingRequests.collectCustomerDetails(\"BR123\", {\n customer: {\n email: \"alice@example.com\",\n given_name: \"Alice\",\n family_name: \"Smith\",\n },\n customer_billing_detail: {\n address_line1: \"1 Somewhere Lane\"\n }\n});"
},
{
"lang": "PHP",
"label": "PHP",
"source": "$client->billingRequests()->collectCustomerDetails(\"BR123\", [\n \"params\" => [\n \"customer\" => [\n \"email\" => \"alice@example.com\",\n \"given_name\" => \"Alice\",\n \"family_name\" => \"Smith\"\n ],\n \"customer_billing_detail\" => [\n \"address_line1\" => \"1 Somewhere Lane\"\n ]\n ]\n]);"
},
{
"lang": "Java",
"label": "Java",
"source": "client.billingRequests().collectCustomerDetails(\"BR123\")\n .withCustomerEmail(\"alice@example.com\")\n .withCustomerGivenName(\"Alice\")\n .withCustomerFamilyName(\"Smith\")\n .withCustomerBillingDetailAddressLine1(\"1 Somewhere Lane\")\n .execute();"
},
{
"lang": "Go",
"label": "Go",
"source": "billingRequestCollectCustomerDetailsParams := gocardless.BillingRequestCollectCustomerDetailsParams{\n Customer: &gocardless.BillingRequestCollectCustomerDetailsParamsCustomer{\n GivenName: \"Alice\",\n FamilyName: \"Smith\",\n Email: \"alice@example.com\",\n },\n CustomerBillingDetail: &gocardless.BillingRequestCollectCustomerDetailsParamsCustomerBillingDetail{\n AddressLine1: \"1 Somewhere Lane\",\n },\n}\n\nbillingRequest, err := client.BillingRequests.CollectCustomerDetails(ctx, \"BR123\", billingRequestCollectCustomerDetailsParams)"
},
{
"lang": "C#",
"label": ".NET",
"source": "var customer = new GoCardless.Services.BillingRequestCollectCustomerDetailsRequest.BillingRequestCustomer\n{\n Email = \"alice@example.com\",\n GivenName = \"Alice\",\n FamilyName = \"Smith\",\n};\n\nvar customerBillingDetail = new GoCardless.Services.BillingRequestCollectCustomerDetailsRequest.BillingRequestCustomerBillingDetail\n{\n AddressLine1 = \"1 Somewhere Lane\",\n};\n\nvar resp = await client.BillingRequests.CollectCustomerDetailsAsync(\"BR123\",\n new GoCardless.Services.BillingRequestCollectCustomerDetailsRequest\n {\n Customer = customer,\n CustomerBillingDetail = customerBillingDetail,\n });"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_customer_details HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"customer\": {\n \"email\": \"alice@example.com\",\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\"\n },\n \"customer_billing_detail\": {\n \"address_line1\": \"1 Somewhere Lane\"\n }\n }\n}\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"pending\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"creditor\": \"CR123\",\n \"mandate_request\": \"MRQ123\"\n },\n \"actions\": [\n {\n \"type\": \"choose_currency\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_customer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"choose_currency\"\n ],\n \"status\": \"pending\",\n \"collect_customer_details\": {\n \"incomplete_fields\": {\n \"customer\": [],\n \"customer_billing_detail\": [\n \"address_line1\",\n \"city\",\n \"postal_code\",\n \"country_code\"\n ]\n }\n }\n },\n {\n \"type\": \"select_institution\",\n \"required\": false,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"collect_bank_account\",\n \"required\": true,\n \"completes_actions\": [\n \"choose_currency\"\n ],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"bank_authorisation\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"collect_bank_account\"\n ],\n \"status\": \"pending\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": \"alice@example.com\",\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n }\n }\n }\n}"
}
]
}
},
"/billing_requests/{billing_request_id}/actions/collect_bank_account": {
"post": {
"operationId": "collect_bank_account_billing_request",
"summary": "Collect bank account details",
"description": "If the billing request has a pending\ncollect_bank_account action, this endpoint can be\nused to collect the details in order to complete it.\n\nThe endpoint takes the same payload as Customer Bank Accounts, but check\nthe bank account is valid for the billing request scheme before creating\nand attaching it.\n\nIf the scheme is PayTo and the pay_id is available, this can be included in the payload along with the\ncountry_code.\n\n_ACH scheme_ For compliance reasons, an extra validation step is done using\na third-party provider to make sure the customer's bank account can accept\nDirect Debit. If a bank account is discovered to be closed or invalid, the\ncustomer is requested to adjust the account number/routing number and\nsucceed in this check to continue with the flow.\n\n_BACS and SEPA schemes_ [Payer Name Verification](https://hub.gocardless.com/s/article/Introduction-to-Payer-Name-Verification?language=en_GB)\nis enabled by default for UK and Eurozone based bank accounts, meaning we verify the account holder name and bank account number/IBAN match\nthe details held by the relevant bank. If there is no match, the endpoint will return a 422 - validation error on account_holder_name:\n\"Account holder name does not match bank account details provided\". Testing instructions are [here](https://developer.gocardless.com/developer-tools/scenario-simulators/#payer_name_verification)",
"tags": [
"Billing Request"
],
"parameters": [
{
"$ref": "#/components/parameters/GoCardlessVersionHeader"
},
{
"name": "billing_request_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The billing request id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/billing_request_single_resource_response"
}
}
},
"description": "Action completed successfully"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "Unauthorised",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "Internal Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"billing_requests": {
"type": "object",
"additionalProperties": false,
"properties": {
"account_number": {
"$ref": "#/components/schemas/customer_bank_account_account_number"
},
"bank_code": {
"$ref": "#/components/schemas/customer_bank_account_bank_code"
},
"branch_code": {
"$ref": "#/components/schemas/customer_bank_account_branch_code"
},
"iban": {
"$ref": "#/components/schemas/customer_bank_account_iban"
},
"country_code": {
"$ref": "#/components/schemas/customer_bank_account_country_code"
},
"currency": {
"$ref": "#/components/schemas/customer_bank_account_currency"
},
"account_holder_name": {
"$ref": "#/components/schemas/customer_bank_account_account_holder_name"
},
"account_type": {
"$ref": "#/components/schemas/customer_bank_account_account_type"
},
"account_number_suffix": {
"type": "string",
"nullable": true,
"description": "Account number suffix (only for bank accounts denominated in NZD) - see [local details](#local-bank-details-new-zealand) for more information.",
"example": "00"
},
"pay_id": {
"$ref": "#/components/schemas/billing_request_pay_id"
},
"metadata": {
"$ref": "#/components/schemas/customer_metadata"
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "Ruby",
"label": "Ruby",
"source": "@client.billing_requests.collect_bank_account(\"BR123\", {\n params: {\n account_number: \"55779911\",\n branch_code: \"200000\",\n account_holder_name: \"Frank Osborne\",\n country_code: \"GB\",\n }\n})"
},
{
"lang": "Python",
"label": "Python",
"source": "client.billing_requests.collect_bank_account(\"BR123\", params={\n \"account_number\": \"55779911\",\n \"branch_code\": \"200000\",\n \"account_holder_name\": \"Frank Osborne\",\n \"country_code\": \"GB\"\n})"
},
{
"lang": "JavaScript",
"label": "JavaScript",
"source": "const resp = await client.billingRequests.collectBankAccount(\"BR123\", {\n account_number: \"55779911\",\n branch_code: \"200000\",\n account_holder_name: \"Frank Osborne\",\n country_code: \"GB\",\n});"
},
{
"lang": "PHP",
"label": "PHP",
"source": "$client->billingRequests()->collectBankAccount(\"BR123\", [\n \"params\" => [\n \"account_number\" => \"55779911\",\n \"branch_code\" => \"200000\",\n \"account_holder_name\" => \"Frank Osborne\",\n \"country_code\" => \"GB\"\n ]\n]);"
},
{
"lang": "Java",
"label": "Java",
"source": "client.billingRequests().collectBankAccount(\"BR123\")\n .withAccountNumber(\"55779911\")\n .withBranchCode(\"200000\")\n .withAccountHolderName(\"Frank Osborne\")\n .withCountryCode(\"GB\")\n .execute();"
},
{
"lang": "Go",
"label": "Go",
"source": "billingRequestCollectBankAccountParams := gocardless.BillingRequestCollectBankAccountParams{\n BranchCode: \"200000\",\n CountryCode: \"GB\",\n AccountNumber: \"55779911\",\n AccountHolderName: \"Frank Osborne\",\n}\n\nbillingRequest, err := client.BillingRequests.CollectBankAccount(ctx, \"BR123\", billingRequestCollectBankAccountParams)"
},
{
"lang": "C#",
"label": ".NET",
"source": "var resp = await client.BillingRequests.CollectBankAccountAsync(\"BR123\",\n new GoCardless.Services.BillingRequestCollectBankAccountRequest\n {\n AccountNumber = \"55779911\",\n BranchCode = \"200000\",\n AccountHolderName = \"Frank Osborne\",\n CountryCode = \"GB\",\n });"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_bank_account HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"account_number\": \"55779911\",\n \"branch_code\": \"200000\",\n \"account_holder_name\": \"Frank Osborne\",\n \"country_code\": \"GB\"\n }\n}\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"pending\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_bank_account\": \"BA123\",\n \"creditor\": \"CR123\",\n \"mandate_request\": \"MRQ123\"\n },\n \"actions\": [\n {\n \"type\": \"choose_currency\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_customer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"choose_currency\"\n ],\n \"status\": \"pending\",\n \"collect_customer_details\": {\n \"incomplete_fields\": {\n \"customer\": [\n \"email\",\n \"given_name\",\n \"family_name\"\n ],\n \"customer_billing_detail\": [\n \"address_line1\",\n \"city\",\n \"postal_code\",\n \"country_code\"\n ]\n }\n }\n },\n {\n \"type\": \"select_institution\",\n \"required\": false,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"collect_bank_account\",\n \"required\": true,\n \"completes_actions\": [\n \"choose_currency\"\n ],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"bank_authorisation\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"collect_bank_account\"\n ],\n \"status\": \"pending\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_bank_account\": {\n \"id\": \"BA123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"account_holder_name\": \"Frank Osborne\",\n \"account_number_ending\": \"11\",\n \"country_code\": \"GB\",\n \"currency\": \"GBP\",\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"metadata\": {},\n \"enabled\": true,\n \"links\": {\n \"customer\": \"CU123\"\n }\n }\n }\n }\n}"
}
]
}
},
"/billing_requests/{billing_request_id}/actions/confirm_payer_details": {
"post": {
"operationId": "confirm_payer_details_billing_request",
"summary": "Confirm the payer details",
"description": "This is needed when you have a mandate request. As a scheme compliance rule we are required to\nallow the payer to crosscheck the details entered by them and confirm it.\n\nRestricted: this endpoint is restricted to [GoCardless Pro](https://gocardless.com/pricing) and [GoCardless Enterprise](https://gocardless.com/pricing) accounts with the [custom payment pages upgrade](https://hub.gocardless.com/s/article/Custom-payment-pages).
", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_requests": { "type": "object", "additionalProperties": false, "properties": { "payer_requested_dual_signature": { "$ref": "#/components/schemas/billing_request_payer_requested_dual_signature" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.confirm_payer_details(\"BR123\")" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.confirm_payer_details(\"BR123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequests.confirmPayerDetails(\"BR123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->confirmPayerDetails(\"BR123\");" }, { "lang": "Java", "label": "Java", "source": "client.billingRequests().confirmPayerDetails(\"BR123\").execute();" }, { "lang": "Go", "label": "Go", "source": "BillingRequestConfirmPayerDetailsParams := gocardless.BillingRequestConfirmPayerDetailsParams{}\nbillingRequest, err := client.BillingRequests.ConfirmPayerDetails(ctx, \"BR123\", BillingRequestConfirmPayerDetailsParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequests.ConfirmPayerDetailsAsync(\"BR123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/confirm_payer_details HTTP/1.1\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"ready_to_fulfil\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": null,\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_bank_account\": \"BA123\",\n \"creditor\": \"CR123\",\n \"mandate_request\": \"MRQ123\"\n },\n \"actions\": [\n {\n \"type\": \"choose_currency\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_customer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"choose_currency\"\n ],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_bank_account\",\n \"required\": true,\n \"completes_actions\": [\n \"choose_currency\"\n ],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"confirm_payer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"collect_customer_details\",\n \"collect_bank_account\"\n ],\n \"status\": \"completed\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_bank_account\": {\n \"id\": \"BA123\",\n \"created_at\": \"2022-11-01T16:30:37.969Z\",\n \"account_number_ending\": \"11\",\n \"account_holder_name\": \"HOME LOAN ACCOUNT\",\n \"account_type\": null,\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"currency\": \"GBP\",\n \"country_code\": \"GB\",\n \"metadata\": {},\n \"enabled\": true,\n \"links\": {\n \"customer\": \"CU123\"\n }\n }\n }\n }\n}" } ] } }, "/billing_requests/{billing_request_id}/actions/fulfil": { "post": { "operationId": "fulfil_billing_request", "summary": "Fulfil a Billing Request", "description": "If a billing request is ready to be fulfilled, call this endpoint to cause\nit to fulfil, executing the payment.", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_requests": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.fulfil(\"BR123\")" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.fulfil(\"BR123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequests.fulfil(\"BR123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->fulfil(\"BR123\");" }, { "lang": "Java", "label": "Java", "source": "client.billingRequests().fulfil(\"BR123\").execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestFulfilParams := gocardless.BillingRequestFulfilParams{}\nbillingRequest, err := client.BillingRequests.Fulfil(ctx, \"BR123\", billingRequestFulfilParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequests.FulfilAsync(\"BR123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/fulfil HTTP/1.1\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"fulfilled\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {\n \"mandate\": \"MD123\"\n }\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {\n \"payment\": \"PM123\"\n }\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_billing_detail\": \"CBD123\"\n },\n \"actions\": [],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_billing_detail\": {\n \"id\": \"CBD123\",\n \"created_at\": \"2021-03-22T12:20:04.374Z\",\n \"address_line1\": \"1 Somewhere Lane\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": null,\n \"swedish_identity_number\": null,\n \"danish_identity_number\": null\n }\n }\n }\n}" } ] } }, "/billing_requests/{billing_request_id}/actions/cancel": { "post": { "operationId": "cancel_billing_request", "summary": "Cancel a Billing Request", "description": "Immediately cancels a billing request, causing all billing request flows\nto expire.", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_requests": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.cancel(\"BR123\")" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.cancel(\"BR123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequests.cancel(\"BR123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->cancel(\"BR123\");" }, { "lang": "Java", "label": "Java", "source": "client.billingRequests().cancel(\"BR123\").execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestCancelParams := gocardless.BillingRequestCancelParams{}\nbillingRequest, err := client.BillingRequests.Cancel(ctx, \"BR123\", billingRequestCancelParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequests.CancelAsync(\"BR123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/cancel HTTP/1.1\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"cancelled\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_billing_detail\": \"CBD123\"\n },\n \"actions\": [],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_billing_detail\": {\n \"id\": \"CBD123\",\n \"created_at\": \"2021-03-22T12:20:04.374Z\",\n \"address_line1\": \"1 Somewhere Lane\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": null,\n \"swedish_identity_number\": null,\n \"danish_identity_number\": null\n }\n }\n }\n}" } ] } }, "/billing_requests/{billing_request_id}": { "get": { "operationId": "get_billing_requests", "summary": "Get a single Billing Request", "description": "Fetches a billing request", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.get(\"BR123\")" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.get(\"BR123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequests.find(\"BR123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->get(\"BR123\");" }, { "lang": "Java", "label": "Java", "source": "client.billingRequests().get(\"BR123\").execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequest, err := client.BillingRequests.Get(ctx, \"BR123\")" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequests.GetAsync(\"BR123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/billing_requests/BRQ123 HTTP/1.1\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"pending\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_billing_detail\": \"CBD123\"\n },\n \"actions\": [\n {\n \"type\": \"choose_currency\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_customer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"choose_currency\"\n ],\n \"status\": \"pending\",\n \"collect_customer_details\": {\n \"incomplete_fields\": {\n \"customer\": [\n \"email\",\n \"given_name\",\n \"family_name\"\n ],\n \"customer_billing_detail\": [\n \"address_line1\",\n \"city\",\n \"postal_code\",\n \"country_code\"\n ]\n }\n }\n },\n {\n \"type\": \"select_institution\",\n \"required\": false,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"collect_bank_account\",\n \"required\": true,\n \"completes_actions\": [\n \"choose_currency\"\n ],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"bank_authorisation\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"collect_bank_account\"\n ],\n \"status\": \"pending\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": null,\n \"family_name\": null,\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_billing_detail\": {\n \"id\": \"CBD123\",\n \"created_at\": \"2021-03-22T12:20:04.374Z\",\n \"address_line1\": null,\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": null,\n \"swedish_identity_number\": null,\n \"danish_identity_number\": null\n }\n }\n }\n}" } ] } }, "/billing_requests/{billing_request_id}/actions/notify": { "post": { "operationId": "notify_billing_request", "summary": "Notify the customer", "description": "Notifies the customer linked to the billing request, asking them to authorise it.\nCurrently, the customer can only be notified by email.\n\nThis endpoint is currently supported only for Pay by Bank Billing Requests.", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_requests": { "type": "object", "additionalProperties": false, "required": [ "notification_type" ], "properties": { "notification_type": { "$ref": "#/components/schemas/billing_request_notification_type" }, "redirect_uri": { "type": "string", "description": "URL that the payer can be redirected to after authorising the payment.", "example": "https://example.com/callback" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.notify(\"BR123\", {\n params: {\n notification_type: \"email\",\n redirect_uri: \"https://my-company.com\",\n }\n})" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.notify(\"BR123\", params={\n \"notification_type\": \"email\",\n \"redirect_uri\": \"https://my-company.com\"\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequests.notify(\"BR123\", {\n notification_type: \"email\",\n redirect_uri: \"https://my-company.com\",\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->notify(\"BR123\", [\n \"params\" => [\n \"notification_type\" => \"email\",\n \"redirect_uri\" => \"https://my-company.com\"\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.billingRequests().notify(\"BR123\")\n .withNotificationType(\"email\")\n .withRedirectUri(\"https://my-company.com\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestNotifyParams := gocardless.BillingRequestNotifyParams{\n NotificationType: \"email\",\n RedirectUri: \"https://my-company.com\",\n}\n\nbillingRequest, err := client.BillingRequests.Notify(ctx, \"BR123\", billingRequestNotifyParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequests.NotifyAsync(\"BR123\",\n new GoCardless.Services.BillingRequestNotifyRequest\n {\n NotificationType = \"email\",\n RedirectUri = \"https://my-company.com\",\n });" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/notify HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"notification_type\": \"email\",\n \"redirect_uri\": \"https://my-company.com\"\n }\n}\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"pending\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_billing_detail\": \"CBD123\"\n },\n \"actions\": [\n {\n \"type\": \"choose_currency\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_customer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"choose_currency\"\n ],\n \"status\": \"pending\",\n \"collect_customer_details\": {\n \"incomplete_fields\": {\n \"customer\": [\n \"email\",\n \"given_name\",\n \"family_name\"\n ],\n \"customer_billing_detail\": [\n \"address_line1\",\n \"city\",\n \"postal_code\",\n \"country_code\"\n ]\n }\n }\n },\n {\n \"type\": \"select_institution\",\n \"required\": false,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"collect_bank_account\",\n \"required\": true,\n \"completes_actions\": [\n \"choose_currency\"\n ],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"bank_authorisation\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"collect_bank_account\"\n ],\n \"status\": \"pending\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_billing_detail\": {\n \"id\": \"CBD123\",\n \"created_at\": \"2021-03-22T12:20:04.374Z\",\n \"address_line1\": \"1 Somewhere Lane\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": null,\n \"swedish_identity_number\": null,\n \"danish_identity_number\": null\n }\n }\n }\n}" } ] } }, "/billing_requests/{billing_request_id}/actions/fallback": { "post": { "operationId": "fallback_billing_request", "summary": "Trigger fallback", "description": "Triggers a fallback from the open-banking flow to direct debit. Note, the billing request must have fallback enabled.\n\nRestricted: this endpoint is restricted to [GoCardless Pro](https://gocardless.com/pricing) and [GoCardless Enterprise](https://gocardless.com/pricing) accounts with the [custom payment pages upgrade](https://hub.gocardless.com/s/article/Custom-payment-pages).
", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.fallback(\"BR123\")" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.fallback(\"BR123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequests.fallback(\"BR123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->fallback(\"BR123\");" }, { "lang": "Java", "label": "Java", "source": "client.billingRequests().fallback(\"BR123\").execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequest, err := client.BillingRequests.Fallback(ctx, \"BR123\", gocardless.BillingRequestFallbackParams{})" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequests.FallbackAsync(\"BR123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/fallback HTTP/1.1\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"pending\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_billing_detail\": \"CBD123\"\n },\n \"actions\": [\n {\n \"type\": \"choose_currency\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_customer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"choose_currency\"\n ],\n \"status\": \"pending\",\n \"collect_customer_details\": {\n \"incomplete_fields\": {\n \"customer\": [\n \"email\",\n \"given_name\",\n \"family_name\"\n ],\n \"customer_billing_detail\": [\n \"address_line1\",\n \"city\",\n \"postal_code\",\n \"country_code\"\n ]\n }\n }\n },\n {\n \"type\": \"select_institution\",\n \"required\": false,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_bank_account\",\n \"required\": true,\n \"completes_actions\": [\n \"choose_currency\"\n ],\n \"requires_actions\": [],\n \"status\": \"pending\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_billing_detail\": {\n \"id\": \"CBD123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"address_line1\": null,\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": null,\n \"swedish_identity_number\": null,\n \"danish_identity_number\": null\n }\n },\n \"fallback_enabled\": true,\n \"fallback_occurred\": true\n }\n}" } ] } }, "/billing_requests/{billing_request_id}/actions/choose_currency": { "post": { "operationId": "choose_currency_billing_request", "summary": "Change currency", "description": "This will allow for the updating of the currency and subsequently the scheme if\nneeded for a Billing Request. This will only be available for mandate only flows\nwhich do not have the lock_currency flag set to true on the Billing Request Flow. It\nwill also not support any request which has a payments request.", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_requests": { "type": "object", "additionalProperties": false, "required": [ "currency" ], "properties": { "currency": { "$ref": "#/components/schemas/customer_bank_account_currency" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_requests.choose_currency(\"BR123\", {\n params: {\n currency: \"GBP\"\n }\n})" }, { "lang": "Python", "label": "Python", "source": "client.billing_requests.choose_currency(\"BR123\", params={\n \"currency\": \"GBP\"\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequests.chooseCurrency(\"BR123\", {\n currency: \"GBP\"\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequests()->chooseCurrency(\"BR123\", [\n \"params\" => [\n \"currency\" => \"GBP\"\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.billingRequests().chooseCurrency(\"BR123\")\n .withCurrency(\"GBP\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestChooseCurrencyParams := gocardless.BillingRequestChooseCurrencyParams{\n Currency: \"GBP\",\n}\n\nbillingRequest, err := client.BillingRequests.ChooseCurrency(ctx, \"BR123\", billingRequestChooseCurrencyParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequests.ChooseCurrencyAsync(\"BR123\",\n new GoCardless.Services.BillingRequestChooseCurrencyRequest\n {\n Currency = \"GBP\",\n });" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/choose_currency HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"currency\": \"GBP\"\n }\n}" } ] } }, "/billing_requests/{billing_request_id}/actions/select_institution": { "post": { "operationId": "select_institution_billing_request", "summary": "Select institution for a Billing Request", "description": "Creates an Institution object and attaches it to the Billing Request\n\nRestricted: this endpoint is restricted to [GoCardless Pro](https://gocardless.com/pricing) and [GoCardless Enterprise](https://gocardless.com/pricing) accounts with the [custom payment pages upgrade](https://hub.gocardless.com/s/article/Custom-payment-pages).
", "tags": [ "Billing Request" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_requests": { "type": "object", "additionalProperties": false, "required": [ "institution", "country_code" ], "properties": { "institution": { "$ref": "#/components/schemas/institution_id" }, "country_code": { "$ref": "#/components/schemas/institution_country_code" } } } } } } } }, "x-codeSamples": [ { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests/BRQ123/actions/select_institution HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"institution\": \"monzo\",\n \"country_code\": \"GB\"\n }\n}\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2021-03-22T12:20:04.397Z\",\n \"status\": \"pending\",\n \"mandate_request\": {\n \"currency\": \"GBP\",\n \"scheme\": \"bacs\",\n \"links\": {}\n },\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"currency\": \"GBP\",\n \"amount\": 500,\n \"scheme\": \"faster_payments\",\n \"links\": {}\n },\n \"metadata\": {},\n \"links\": {\n \"customer\": \"CU123\",\n \"customer_billing_detail\": \"CBD123\"\n },\n \"actions\": [\n {\n \"type\": \"choose_currency\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_customer_details\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"choose_currency\"\n ],\n \"status\": \"pending\",\n \"collect_customer_details\": {\n \"incomplete_fields\": {\n \"customer\": [\n \"email\",\n \"given_name\",\n \"family_name\"\n ],\n \"customer_billing_detail\": [\n \"address_line1\",\n \"city\",\n \"postal_code\",\n \"country_code\"\n ]\n }\n }\n },\n {\n \"type\": \"select_institution\",\n \"required\": false,\n \"completes_actions\": [],\n \"requires_actions\": [],\n \"status\": \"completed\"\n },\n {\n \"type\": \"collect_bank_account\",\n \"required\": true,\n \"completes_actions\": [\n \"choose_currency\"\n ],\n \"requires_actions\": [],\n \"status\": \"pending\"\n },\n {\n \"type\": \"bank_authorisation\",\n \"required\": true,\n \"completes_actions\": [],\n \"requires_actions\": [\n \"collect_bank_account\"\n ],\n \"status\": \"pending\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"created_at\": \"2021-03-22T12:20:04.238Z\",\n \"email\": null,\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"metadata\": {}\n },\n \"customer_billing_detail\": {\n \"id\": \"CBD123\",\n \"created_at\": \"2021-03-22T12:20:04.374Z\",\n \"address_line1\": \"1 Somewhere Lane\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": null,\n \"swedish_identity_number\": null,\n \"danish_identity_number\": null\n }\n }\n }\n}" } ] } }, "/billing_request_flows": { "post": { "operationId": "create_billing_request_flow", "summary": "Create a Billing Request Flow", "description": "Creates a new billing request flow.", "tags": [ "Billing Request Flow" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_flow_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_request_flows": { "type": "object", "additionalProperties": false, "required": [ "links" ], "properties": { "auto_fulfil": { "$ref": "#/components/schemas/billing_request_flow_auto_fulfil" }, "customer_details_captured": { "$ref": "#/components/schemas/billing_request_flow_customer_details_captured" }, "lock_bank_account": { "$ref": "#/components/schemas/billing_request_flow_lock_bank_account" }, "lock_currency": { "$ref": "#/components/schemas/billing_request_flow_lock_currency" }, "lock_customer_details": { "$ref": "#/components/schemas/billing_request_flow_lock_customer_details" }, "show_redirect_buttons": { "$ref": "#/components/schemas/billing_request_flow_show_redirect_buttons" }, "show_success_redirect_button": { "$ref": "#/components/schemas/billing_request_flow_show_success_redirect_button" }, "redirect_uri": { "$ref": "#/components/schemas/billing_request_flow_redirect_uri" }, "skip_success_screen": { "$ref": "#/components/schemas/billing_request_flow_skip_success_screen" }, "exit_uri": { "$ref": "#/components/schemas/billing_request_flow_exit_uri" }, "prefilled_customer": { "$ref": "#/components/schemas/billing_request_flow_prefilled_customer" }, "prefilled_bank_account": { "$ref": "#/components/schemas/billing_request_flow_prefilled_bank_account" }, "language": { "$ref": "#/components/schemas/billing_request_flow_language" }, "links": { "$ref": "#/components/schemas/billing_request_flow_links" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_request_flows.create(\n params: {\n redirect_uri: \"https://my-company.com/landing\",\n exit_uri: \"https://my-company.com/exit\",\n prefilled_customer: {\n given_name: \"Frank\",\n family_name: \"Osborne\",\n email: \"frank.osborne@acmeplc.com\"\n },\n links: {\n billing_request: \"BRQ123\",\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.billing_request_flows.create(params={\n \"redirect_uri\": \"https://my-company.com/landing\",\n \"exit_uri\": \"https://my-company.com/exit\",\n \"prefilled_customer\": {\n \"given_name\": \"Frank\",\n \"family_name\": \"Osborne\",\n \"email\": \"frank.osborne@acmeplc.com\"\n },\n \"links\": {\n \"billing_request\": \"BRQ123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const billingRequestFlow = await client.billingRequestFlows.create({\n redirect_uri: \"https://my-company.com/landing\",\n exit_uri: \"https://my-company.com/exit\",\n prefilled_customer: {\n given_name: \"Frank\",\n family_name: \"Osborne\",\n email: \"frank.osborne@acmeplc.com\"\n },\n links: {\n billing_request: \"BRQ123\",\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequestFlows()->create([\n \"params\" => [\n \"redirect_uri\" => \"https://my-company.com/landing\",\n \"exit_uri\" => \"https://my-company.com/exit\",\n \"prefilled_customer\" => [\n \"given_name\" => \"Frank\",\n \"family_name\" => \"Osborne\",\n \"email\" => \"frank.osborne@acmeplc.com\"\n ],\n \"links\" => [\n \"billing_request\" => \"BRQ123\"\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "BillingRequestFlow billingRequestFlow = client.billingRequestFlows().create()\n .withRedirectUri(\"https://my-company.com/landing\")\n .withExitUri(\"https://my-company.com/exit\")\n .withPrefilledCustomerGivenName(\"Frank\")\n .withPrefilledCustomerFamilyName(\"Osborne\")\n .withPrefilledCustomerEmail(\"frank.osborne@acmeplc.com\")\n .withLinksBillingRequest(\"BRQ123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestFlowCreateParams := gocardless.BillingRequestFlowCreateParams{\n RedirectUri: \"https://my-company.com/landing\",\n ExitUri: \"https://my-company.com/exit\",\n PrefilledCustomer: &gocardless.BillingRequestFlowCreateParamsPrefilledCustomer{\n AddressLine1: \"338-346 Goswell Road\",\n City: \"London\",\n GivenName: \"Tim\",\n FamilyName: \"Rogers\",\n Email: \"tim@gocardless.com\",\n PostalCode: \"EC1V 7LQ\",\n },\n Links: gocardless.BillingRequestFlowCreateParamsLinks{\n BillingRequest: \"BR123\",\n },\n}\n\nbillingRequestFlow, err := client.BillingRequestFlows.Create(ctx, billingRequestFlowCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var prefilledCustomer = new GoCardless.Services.BillingRequestFlowCreateRequest.BillingRequestFlowPrefilledCustomer()\n{\n AddressLine1 = \"338 Goswell Road\",\n Email = \"api@gocardless.com\",\n GivenName = \"Bobby\",\n FamilyName = \"Tables\"\n};\n\nvar resp = await client.BillingRequestFlows.CreateAsync(\n new GoCardless.Services.BillingRequestFlowCreateRequest()\n {\n RedirectUri = \"https://my-company.com/landing\",\n ExitUri = \"https://my-company.com/exit\",\n PrefilledCustomer = prefilledCustomer,\n Links = new GoCardless.Services.BillingRequestFlowCreateRequest.BillingRequestFlowLinks\n {\n BillingRequest = \"BRQ123\",\n },\n }\n);\n\nGoCardless.Resources.BillingRequestFlow billingRequestFlow = resp.BillingRequestFlow;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_request_flows HTTP/1.1\nContent-Type: application/json\n{\n \"billing_request_flows\": {\n \"redirect_uri\": \"https://my-company.com/landing\",\n \"exit_uri\": \"https://my-company.com/exit\",\n \"prefilled_customer\": {\n \"given_name\": \"Frank\",\n \"family_name\": \"Osborne\",\n \"email\": \"frank.osborne@acmeplc.com\"\n },\n \"links\": {\n \"billing_request\": \"BRQ123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /billing_request_flows/BRF123456\nContent-Type: application/json\n{\n \"billing_request_flows\": {\n \"id\": \"BRF123456\",\n \"auto_fulfil\": true,\n \"redirect_uri\": \"https://my-company.com/landing\",\n \"exit_uri\": \"https://my-company.com/exit\",\n \"authorisation_url\": \"https://pay.gocardless.com/billing/static/flow?id=BRF123456\",\n \"lock_customer_details\": false,\n \"lock_currency\": false,\n \"lock_bank_account\": false,\n \"skip_success_screen\": false,\n \"session_token\": null,\n \"expires_at\": \"2021-07-30T16:25:16.982Z\",\n \"created_at\": \"2021-07-23T16:25:16.983Z\",\n \"links\": {\n \"billing_request\": \"BRQ123\"\n },\n \"show_redirect_buttons\": false,\n \"show_success_redirect_button\": false,\n \"customer_details_captured\": false\n }\n}" } ] } }, "/billing_request_flows/{billing_request_flow_id}/actions/initialise": { "post": { "operationId": "initialise_billing_request_flow", "summary": "Initialise a Billing Request Flow", "description": "Returns the flow having generated a fresh session token which can be used to power\nintegrations that manipulate the flow.", "tags": [ "Billing Request Flow" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_flow_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request flow id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_flow_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_request_flows.initialise(\"BRF123\")" }, { "lang": "Python", "label": "Python", "source": "client.billing_request_flows.initialise(\"BRF123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequestFlows.initialise(\"BRF123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequestFlows()->initialise(\"BRF123\");" }, { "lang": "Java", "label": "Java", "source": "client.billingRequestFlows().initialise(\"BRF123\").execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestFlowInitialiseParams := gocardless.BillingRequestFlowInitialiseParams{}\nbillingRequestFlow, err := client.BillingRequestFlows.Initialise(ctx, \"BRF123\", billingRequestFlowInitialiseParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequestFlows.InitialiseAsync(\"BRF123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_request_flows/BRF123/actions/initialise HTTP/1.1\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_request_flows\":{\n \"id\":\"BRF123\",\n \"auto_fulfil\":true,\n \"redirect_uri\":null,\n \"exit_uri\":null,\n \"authorisation_url\":\"https://pay-sandbox.gocardless.com/billing/static/flow?id=BRF123\",\n \"lock_customer_details\":false,\n \"lock_bank_account\":false,\n \"lock_currency\": false,\n \"skip_success_screen\": false,\n \"session_token\":\"sesh_sandbox_DHTMvJAUajbd9KTCoXNFcTv4RSoWdMbauhnalxiqwbdsb\",\n \"expires_at\":\"2021-09-01T08:45:38.016Z\",\n \"created_at\":\"2021-08-25T08:45:38.017Z\",\n \"links\":{\n \"billing_request\":\"BRQ123\"\n },\n \"show_redirect_buttons\": false,\n \"show_success_redirect_button\": false,\n \"customer_details_captured\": false\n }\n}" } ] } }, "/billing_request_templates": { "get": { "operationId": "list_billing_request_template", "summary": "List Billing Request Templates", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your Billing Request Templates.", "tags": [ "Billing Request Template" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "payment_request_scheme", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/billing_request_template_payment_request_scheme" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_template_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_request_templates.list" }, { "lang": "Python", "label": "Python", "source": "client.billing_request_templates.list().records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const billingRequestTemplates = await client.billingRequestTemplates.list();" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequestTemplates()->list();" }, { "lang": "Java", "label": "Java", "source": "for (BillingRequestTemplate billingRequestTemplate : client.billingRequestTemplates().all().execute()) {\n System.out.println(billingRequestTemplate.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "billingRequestTemplateListParams := gocardless.BillingRequestTemplateListParams{}\nbillingRequestTemplateListResult, err := client.BillingRequestTemplates.List(ctx, billingRequestTemplateListParams)\nfor _, billingRequestTemplate := range billingRequestTemplateListResult.BillingRequestTemplates {\n fmt.Println(billingRequestTemplate.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var billingRequestTemplateListResponse = client.BillingRequestTemplates.All();\nforeach (GoCardless.Resources.BillingRequestTemplate billingRequestTemplate in billingRequestTemplateListResponse)\n{\n Console.WriteLine(billingRequestTemplate.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/billing_request_templates HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"billing_request_templates\": [\n {\n \"id\": \"BRT123\",\n \"name\": \"12 Month Gold Plan\",\n \"mandate_request_currency\": \"GBP\",\n \"mandate_request_scheme\": null,\n \"mandate_request_verify\": \"recommended\",\n \"mandate_request_metadata\": null,\n \"payment_request_description\": \"One-time joining fee\",\n \"mandate_request_description\": \"Recurring fee\",\n \"mandate_request_constraints\": {\n \"max_amount_per_payment\": 1000\n },\n \"payment_request_amount\": \"69.99\",\n \"payment_request_currency\": \"GBP\",\n \"payment_request_scheme\": null,\n \"payment_request_metadata\": null,\n \"redirect_uri\": \"https://my-company.com/landing\",\n \"authorisation_url\": \"https://pay.gocardless.com/BRT123\",\n \"metadata\": {\n \"checkout-flow\": \"primary\"\n },\n \"created_at\": \"2021-07-27T17:10:33.784Z\",\n \"updated_at\": \"2021-07-27T17:10:33.784Z\"\n }\n ]\n}" } ] }, "post": { "operationId": "create_billing_request_template", "summary": "Create a Billing Request Template", "description": "", "tags": [ "Billing Request Template" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_template_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_request_templates": { "type": "object", "additionalProperties": false, "properties": { "name": { "$ref": "#/components/schemas/billing_request_template_name" }, "mandate_request_currency": { "$ref": "#/components/schemas/billing_request_template_mandate_request_currency" }, "mandate_request_scheme": { "$ref": "#/components/schemas/billing_request_template_mandate_request_scheme" }, "mandate_request_verify": { "$ref": "#/components/schemas/billing_request_template_mandate_request_verify" }, "mandate_request_metadata": { "$ref": "#/components/schemas/billing_request_template_mandate_request_metadata" }, "payment_request_description": { "$ref": "#/components/schemas/billing_request_template_payment_request_description" }, "mandate_request_description": { "$ref": "#/components/schemas/billing_request_template_mandate_request_description" }, "mandate_request_constraints": { "$ref": "#/components/schemas/billing_request_template_mandate_request_constraints" }, "payment_request_amount": { "$ref": "#/components/schemas/billing_request_template_payment_request_amount" }, "payment_request_currency": { "$ref": "#/components/schemas/billing_request_template_payment_request_currency" }, "payment_request_scheme": { "$ref": "#/components/schemas/billing_request_template_payment_request_scheme" }, "payment_request_metadata": { "$ref": "#/components/schemas/billing_request_template_payment_request_metadata" }, "redirect_uri": { "$ref": "#/components/schemas/billing_request_template_redirect_uri" }, "metadata": { "$ref": "#/components/schemas/billing_request_template_metadata" }, "links": { "type": "object", "description": "", "additionalProperties": false, "properties": { "creditor": { "type": "string", "description": "ID of the associated [creditor](#core-endpoints-creditors). Only required if your account manages multiple creditors.", "example": "CR123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_request_templates.create(\n params: {\n name: \"12 Month Gold Plan\",\n payment_request_description: \"One-time joining fee\",\n mandate_request_description: \"Recurring fee\",\n payment_request_currency: \"GBP\",\n payment_request_amount: \"69.99\",\n mandate_request_currency: \"GBP\",\n redirect_uri: \"https://my-company.com/landing\",\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.billing_request_templates.create(params={\n \"name\": \"12 Month Gold Plan\",\n \"payment_request_description\": \"One-time joining fee\",\n \"mandate_request_description\": \"Recurring fee\",\n \"payment_request_currency\": \"GBP\",\n \"payment_request_amount\": \"69.99\",\n \"mandate_request_currency\": \"GBP\",\n \"redirect_uri\": \"https://my-company.com/landing\",\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const billingRequestTemplate = await client.billingRequestTemplates.create({\n name: \"12 Month Gold Plan\",\n payment_request_description: \"One-time joining fee\",\n mandate_request_description: \"Recurring fee\",\n payment_request_currency: \"GBP\",\n payment_request_amount: \"69.99\",\n mandate_request_currency: \"GBP\",\n redirect_uri: \"https://my-company.com/landing\",\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequestTemplates()->create([\n \"params\" => [\n \"name\" => \"12 Month Gold Plan\",\n \"payment_request_description\" => \"One-time joining fee\",\n \"mandate_request_description\" => \"Recurring fee\",\n \"payment_request_currency\" => \"GBP\",\n \"payment_request_amount\" => \"69.99\",\n \"mandate_request_currency\" => \"GBP\",\n \"redirect_uri\" => \"https://my-company.com/landing\",\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "BillingRequestTemplate billingRequestTemplate = client.billingRequestTemplates().create()\n .withPaymentRequestDescription(\"One-time joining fee\")\n .withPaymentRequestCurrency(\"GBP\")\n .withPaymentRequestAmount(\"69.99\")\n .withMandateRequestCurrency(\"GBP\")\n .withRedirectUri(\"https://my-company.com/landing\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestTemplateCreateParams := gocardless.BillingRequestTemplateCreateParams{\n Name: \"12 Month Gold Plan\",\n PaymentRequestDescription: \"One-time joining fee\",\n PaymentRequestCurrency: \"GBP\",\n PaymentRequestAmount: \"6999\",\n MandateRequestCurrency: \"GBP\",\n RedirectUri: \"https://my-company.com/landing\",\n}\n\nbillingRequestTemplate, err := client.BillingRequestTemplates.Create(ctx, billingRequestTemplateCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequestTemplates.CreateAsync(\n new GoCardless.Services.BillingRequestTemplateCreateRequest()\n {\n PaymentRequestDescription = \"One-time joining fee\",\n PaymentRequestCurrency = \"GBP\",\n PaymentRequestAmount = \"6999\",\n MandateRequestCurrency = \"GBP\",\n RedirectUri = \"https://my-company.com/landing\",\n }\n);\n\nGoCardless.Resources.BillingRequestTemplate billingRequestTemplate = resp.BillingRequestTemplate;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_request_templates HTTP/1.1\nContent-Type: application/json\n{\n \"billing_request_templates\": {\n \"name\": \"12 Month Gold Plan\",\n \"payment_request_description\": \"One-time joining fee\",\n \"mandate_request_description\": \"Recurring fee\",\n \"mandate_request_constraints\": {\n \"max_amount_per_payment\": 1000\n },\n \"payment_request_currency\": \"GBP\",\n \"payment_request_amount\": \"69.99\",\n \"mandate_request_currency\": \"GBP\",\n \"redirect_uri\": \"https://my-company.com/landing\",\n \"metadata\": {\n \"checkout-flow\": \"primary\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /billing_request_templates/BRT123\nContent-Type: application/json\n{\n \"billing_request_templates\": {\n \"id\": \"BRT123\",\n \"name\": \"12 Month Gold Plan\",\n \"mandate_request_currency\": \"GBP\",\n \"mandate_request_scheme\": null,\n \"mandate_request_verify\": \"recommended\",\n \"mandate_request_metadata\": null,\n \"payment_request_description\": \"One-time joining fee\",\n \"mandate_request_description\": \"Recurring fee\",\n \"mandate_request_constraints\": {\n \"max_amount_per_payment\": 1000\n },\n \"payment_request_amount\": \"69.99\",\n \"payment_request_currency\": \"GBP\",\n \"payment_request_scheme\": null,\n \"payment_request_metadata\": null,\n \"redirect_uri\": \"https://my-company.com/landing\",\n \"authorisation_url\": \"https://pay.gocardless.com/BRT123\",\n \"metadata\": {\n \"checkout-flow\": \"primary\"\n },\n \"created_at\": \"2021-07-27T17:10:33.784Z\",\n \"updated_at\": \"2021-07-27T17:10:33.784Z\"\n }\n}" } ] } }, "/billing_request_templates/{billing_request_template_id}": { "get": { "operationId": "get_billing_request_templates", "summary": "Get a single Billing Request Template", "description": "Fetches a Billing Request Template", "tags": [ "Billing Request Template" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_template_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request template id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_template_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_request_templates.get(\"BRT123\")" }, { "lang": "Python", "label": "Python", "source": "client.billing_request_templates.get(\"BRT123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.billingRequestTemplates.find(\"BRT123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequestTemplates()->get(\"BRT123\");" }, { "lang": "Java", "label": "Java", "source": "client.billingRequestTemplates().get(\"BRT123\").execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestTemplate, err := client.BillingRequestTemplates.Get(ctx, \"BRT123\")" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequestTemplates.GetAsync(\"BRT123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/billing_request_templates/BRT123 HTTP/1.1\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"billing_request_templates\": {\n \"id\": \"BRT123\",\n \"name\": \"12 Month Gold Plan\",\n \"mandate_request_currency\": \"GBP\",\n \"mandate_request_scheme\": null,\n \"mandate_request_verify\": \"recommended\",\n \"mandate_request_metadata\": null,\n \"payment_request_description\": \"One-time joining fee\",\n \"mandate_request_description\": \"Recurring fee\",\n \"mandate_request_constraints\": {\n \"max_amount_per_payment\": 1000\n },\n \"payment_request_amount\": \"69.99\",\n \"payment_request_currency\": \"GBP\",\n \"payment_request_scheme\": null,\n \"payment_request_metadata\": null,\n \"redirect_uri\": \"https://my-company.com/landing\",\n \"authorisation_url\": \"https://pay.gocardless.com/BRT123\",\n \"metadata\": {\n \"checkout-flow\": \"primary\"\n },\n \"created_at\": \"2021-07-27T17:10:33.784Z\",\n \"updated_at\": \"2021-07-27T17:10:33.784Z\"\n }\n}" } ] }, "put": { "operationId": "update_billing_request_templates", "summary": "Update a Billing Request Template", "description": "Updates a Billing Request Template, which will affect all future Billing Requests created by this template.", "tags": [ "Billing Request Template" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_template_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request template id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_template_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_request_templates": { "type": "object", "additionalProperties": false, "properties": { "name": { "$ref": "#/components/schemas/billing_request_template_name" }, "mandate_request_currency": { "$ref": "#/components/schemas/billing_request_template_mandate_request_currency" }, "mandate_request_scheme": { "$ref": "#/components/schemas/billing_request_template_mandate_request_scheme" }, "mandate_request_verify": { "$ref": "#/components/schemas/billing_request_template_mandate_request_verify" }, "mandate_request_metadata": { "$ref": "#/components/schemas/billing_request_template_mandate_request_metadata" }, "payment_request_description": { "$ref": "#/components/schemas/billing_request_template_payment_request_description" }, "mandate_request_description": { "$ref": "#/components/schemas/billing_request_template_mandate_request_description" }, "mandate_request_constraints": { "$ref": "#/components/schemas/billing_request_template_mandate_request_constraints" }, "payment_request_amount": { "$ref": "#/components/schemas/billing_request_template_payment_request_amount" }, "payment_request_currency": { "$ref": "#/components/schemas/billing_request_template_payment_request_currency" }, "payment_request_scheme": { "$ref": "#/components/schemas/billing_request_template_payment_request_scheme" }, "payment_request_metadata": { "$ref": "#/components/schemas/billing_request_template_payment_request_metadata" }, "redirect_uri": { "$ref": "#/components/schemas/billing_request_template_redirect_uri" }, "metadata": { "$ref": "#/components/schemas/billing_request_template_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.billing_request_templates.update(\"BRT123\", params: {\n name: \"12 Month Silver Plan\",\n payment_request_amount: \"49.99\",\n})" }, { "lang": "Python", "label": "Python", "source": "client.billing_request_templates.update(\"BRT123\", params={\n \"name\": \"12 Month Silver Plan\",\n \"payment_request_amount\": \"49.99\",\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const billingRequestTemplate = await client.billingRequestTemplates.update(\"BRT123\", {\n name: \"12 Month Silver Plan\",\n payment_request_amount: \"49.99\",\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->billingRequestTemplates()->update(\"BRT123\", [\n \"params\" => [\n \"name\" => \"12 Month Silver Plan\",\n \"payment_request_amount\" => \"49.99\"\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "BillingRequestTemplate billingRequestTemplate = client.billingRequestTemplates().update(\"BRT123\")\n .withName(\"12 Month Silver Plan\")\n .withPaymentRequestAmount(\"49.99\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "billingRequestTemplateUpdateParams := gocardless.BillingRequestTemplateUpdateParams{\n Name: \"12 Month Silver Plan\",\n PaymentRequestAmount: \"4999\",\n}\n\nbillingRequestTemplate, err := client.BillingRequestTemplates.Update(ctx, \"BRT123\", billingRequestTemplateUpdateParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.BillingRequestTemplates.UpdateAsync(\n \"BRT123\",\n new GoCardless.Services.BillingRequestTemplateUpdateRequest()\n {\n Name = \"12 Month Silver Plan\",\n PaymentRequestAmount = \"4999\",\n }\n);\n\nGoCardless.Resources.BillingRequestTemplate billingRequestTemplate = resp.BillingRequestTemplate;" }, { "lang": "HTTP", "label": "HTTP", "source": "PUT https://api.gocardless.com/billing_request_templates/BRT123 HTTP/1.1\nContent-Type: application/json\n{\n \"billing_request_templates\": {\n \"name\": \"12 Month Silver Plan\",\n \"payment_request_amount\": \"49.99\"\n }\n}\n\nHTTP/1.1 200 OK\nLocation: /billing_request_templates/BRT123\nContent-Type: application/json\n{\n \"billing_request_templates\": {\n \"id\": \"BRT123\",\n \"name\": \"12 Month Silver Plan\",\n \"mandate_request_currency\": \"GBP\",\n \"mandate_request_scheme\": null,\n \"mandate_request_verify\": \"recommended\",\n \"mandate_request_metadata\": null,\n \"payment_request_description\": \"One-time joining fee\",\n \"mandate_request_description\": \"Recurring fee\",\n \"mandate_request_constraints\": {\n \"max_amount_per_payment\": 1000\n },\n \"payment_request_amount\": \"49.99\",\n \"payment_request_currency\": \"GBP\",\n \"payment_request_scheme\": null,\n \"payment_request_metadata\": null,\n \"redirect_uri\": \"https://my-company.com/landing\",\n \"authorisation_url\": \"https://pay.gocardless.com/BRT123\",\n \"metadata\": {\n \"checkout-flow\": \"primary\"\n },\n \"created_at\": \"2021-07-27T17:10:33.784Z\",\n \"updated_at\": \"2021-07-30T11:28:11.123Z\"\n }\n}" } ] } }, "/billing_requests/create_with_actions": { "post": { "operationId": "create_with_actions_billing_requests", "summary": "Create a Billing Request with Actions", "description": "Creates a billing request and completes any specified actions in a single request.\nThis endpoint allows you to create a billing request and immediately complete actions\nsuch as collecting customer details, bank account details, or other required actions.\n\nRestricted: this endpoint is restricted to [GoCardless Pro](https://gocardless.com/pricing) and [GoCardless Enterprise](https://gocardless.com/pricing) accounts with the [custom payment pages upgrade](https://hub.gocardless.com/s/article/Custom-payment-pages).
\n\nNote: to modify data on an already created billing request, call individual action endpoints. Calling this endpoint creates a new billing request everytime.
\n\nWarning: ACH/PAD is not supported on this endpoint.
", "tags": [ "Billing Request With Action" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_request_with_action_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_request_with_actions": { "type": "object", "additionalProperties": false, "properties": { "mandate_request": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/billing_request_currency" }, "scheme": { "$ref": "#/components/schemas/billing_request_scheme" }, "verify": { "$ref": "#/components/schemas/billing_request_mandate_request_verify" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "reference": { "$ref": "#/components/schemas/mandate_reference" }, "description": { "$ref": "#/components/schemas/billing_request_description" }, "constraints": { "$ref": "#/components/schemas/billing_request_mandate_request_constraints" }, "sweeping": { "$ref": "#/components/schemas/billing_request_sweeping" }, "authorisation_source": { "$ref": "#/components/schemas/billing_request_authorisation_source" }, "funds_settlement": { "$ref": "#/components/schemas/billing_request_funds_settlement" } } }, "payment_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/billing_request_description" }, "currency": { "$ref": "#/components/schemas/billing_request_payment_currency" }, "scheme": { "$ref": "#/components/schemas/billing_request_payment_scheme" }, "amount": { "$ref": "#/components/schemas/billing_request_amount_stringable" }, "funds_settlement": { "$ref": "#/components/schemas/billing_request_funds_settlement" }, "app_fee": { "$ref": "#/components/schemas/billing_request_app_fee_stringable" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "reference": { "$ref": "#/components/schemas/billing_request_reference" }, "retry_if_possible": { "type": "boolean", "description": "On failure, automatically retry payments using [intelligent retries](/success-plus/overview). Default is `false`.Important: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus).
Important: This is not applicable to Pay by Bank and VRP payments.
" } } }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "links": { "type": "object", "description": "", "additionalProperties": false, "properties": { "customer": { "type": "string", "description": "ID of the [customer](#core-endpoints-customers) against which this request should be made.", "example": "CU123" }, "customer_bank_account": { "type": "string", "description": "(Optional) ID of the [customer_bank_account](#core-endpoints-customer-bank-accounts) against which this request should be made.\n", "example": "BA123" }, "creditor": { "type": "string", "description": "ID of the associated [creditor](#core-endpoints-creditors). Only required if your account manages multiple creditors.", "example": "CR123" } } }, "fallback_enabled": { "$ref": "#/components/schemas/billing_request_fallback_enabled" }, "purpose_code": { "$ref": "#/components/schemas/billing_request_purpose_code" }, "payment_purpose_code": { "$ref": "#/components/schemas/billing_request_payment_purpose_code" }, "payment_context_code": { "$ref": "#/components/schemas/billing_request_payment_context_code" }, "actions": { "type": "object", "description": "Action payloads", "additionalProperties": false, "properties": { "collect_customer_details": { "type": "object", "additionalProperties": false, "properties": { "customer": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/customer_email" }, "given_name": { "$ref": "#/components/schemas/customer_given_name" }, "family_name": { "$ref": "#/components/schemas/customer_family_name" }, "company_name": { "$ref": "#/components/schemas/customer_company_name" }, "language": { "type": "string", "nullable": true, "description": " [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see [compliance requirements](#appendix-compliance-requirements)). Currently only \"en\", \"fr\", \"de\", \"pt\", \"es\", \"it\", \"nl\", \"da\", \"nb\", \"sl\", \"sv\" are supported. If this is not provided and a customer was linked during billing request creation, the linked customer language will be used. Otherwise, the language is default to \"en\".", "example": "en" }, "phone_number": { "$ref": "#/components/schemas/customer_phone_number" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } }, "customer_billing_detail": { "type": "object", "properties": { "address_line1": { "$ref": "#/components/schemas/customer_address_line1" }, "address_line2": { "$ref": "#/components/schemas/customer_address_line2" }, "address_line3": { "$ref": "#/components/schemas/customer_address_line3" }, "city": { "$ref": "#/components/schemas/customer_city" }, "region": { "$ref": "#/components/schemas/customer_region" }, "postal_code": { "$ref": "#/components/schemas/customer_postal_code" }, "country_code": { "$ref": "#/components/schemas/customer_country_code" }, "swedish_identity_number": { "$ref": "#/components/schemas/customer_swedish_identity_number" }, "danish_identity_number": { "$ref": "#/components/schemas/customer_danish_identity_number" }, "ip_address": { "$ref": "#/components/schemas/mandate_payer_ip_address" } } } } }, "collect_bank_account": { "type": "object", "additionalProperties": false, "properties": { "account_number": { "$ref": "#/components/schemas/customer_bank_account_account_number" }, "bank_code": { "$ref": "#/components/schemas/customer_bank_account_bank_code" }, "branch_code": { "$ref": "#/components/schemas/customer_bank_account_branch_code" }, "iban": { "$ref": "#/components/schemas/customer_bank_account_iban" }, "country_code": { "$ref": "#/components/schemas/customer_bank_account_country_code" }, "currency": { "$ref": "#/components/schemas/customer_bank_account_currency" }, "account_holder_name": { "$ref": "#/components/schemas/customer_bank_account_account_holder_name" }, "account_type": { "$ref": "#/components/schemas/customer_bank_account_account_type" }, "account_number_suffix": { "type": "string", "nullable": true, "description": "Account number suffix (only for bank accounts denominated in NZD) - see [local details](#local-bank-details-new-zealand) for more information.", "example": "00" }, "pay_id": { "$ref": "#/components/schemas/billing_request_pay_id" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } }, "select_institution": { "type": "object", "additionalProperties": false, "required": [ "institution", "country_code" ], "properties": { "institution": { "$ref": "#/components/schemas/institution_id" }, "country_code": { "$ref": "#/components/schemas/institution_country_code" } } }, "confirm_payer_details": { "type": "object", "additionalProperties": false, "properties": { "payer_requested_dual_signature": { "$ref": "#/components/schemas/billing_request_payer_requested_dual_signature" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } }, "create_bank_authorisation": { "type": "boolean", "description": "Create a bank authorisation object as part of this request" }, "bank_authorisation_redirect_uri": { "$ref": "#/components/schemas/bank_authorisation_url" } } } } } } } } } }, "x-codeSamples": [ { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/billing_requests/create_with_actions HTTP/1.1\nContent-Type: application/json\n{\n \"billing_request_with_actions\": {\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"amount\": \"500\",\n \"currency\": \"GBP\"\n },\n \"actions\": {\n \"collect_customer_details\": {\n \"customer\": {\n \"email\": \"alice@example.com\",\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\"\n }\n },\n \"select_institution\": {\n \"institution\": \"IN123\",\n \"country_code\": \"GB\"\n },\n \"create_bank_authorisation\": true\n }\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"billing_request_with_actions\": {\n \"billing_requests\": {\n \"id\": \"BRQ123\",\n \"created_at\": \"2025-03-06T21:36:43Z\",\n \"status\": \"pending\",\n \"payment_request\": {\n \"description\": \"First Payment\",\n \"amount\": 500,\n \"currency\": \"GBP\"\n },\n \"actions\": [\n {\n \"type\": \"bank_authorisation\",\n \"required\": true,\n \"status\": \"pending\"\n }\n ],\n \"resources\": {\n \"customer\": {\n \"id\": \"CU123\",\n \"email\": \"alice@example.com\",\n \"given_name\": \"Alice\",\n \"family_name\": \"Smith\",\n \"company_name\": null,\n \"language\": \"en\",\n \"phone_number\": null,\n \"created_at\": \"2025-03-06T21:36:43Z\"\n }\n },\n \"links\": {\n \"customer\": \"CU123\"\n }\n },\n \"bank_authorisations\": {\n \"id\": \"BAU123\",\n \"created_at\": \"2025-03-06T21:36:43Z\",\n \"expires_at\": \"2025-03-06T21:51:43Z\",\n \"url\": \"https://pay.gocardless.com/obauth/BAU123\",\n \"qr_code_url\": \"https://pay.gocardless.com/obauth/BAU123/qr_code\",\n \"authorisation_type\": \"payment\",\n \"links\": {\n \"billing_request\": \"BRQ123\"\n }\n }\n }\n}" } ] } }, "/blocks": { "post": { "operationId": "create_block", "summary": "Create a block", "description": "Creates a new Block of a given type. By default it will be active.\n\nNote: Block will be enabled if you try to create a block that already exists and is disabled.
", "tags": [ "Block" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "object", "additionalProperties": false, "properties": { "block_type": { "$ref": "#/components/schemas/block_block_type" }, "reason_type": { "$ref": "#/components/schemas/block_reason_type" }, "reason_description": { "$ref": "#/components/schemas/block_reason_description" }, "resource_reference": { "$ref": "#/components/schemas/block_resource_reference" }, "active": { "$ref": "#/components/schemas/block_active" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "block = @client.blocks.create(\n params: {\n block_type: \"email\",\n reason_type: \"no_intent_to_pay\",\n resource_reference: \"example@example.com\"\n }\n)" }, { "lang": "Python", "label": "Python", "source": "block = client.blocks.create(\n params={\n \"block_type\": \"email\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"example@example.com\"\n }\n)" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const block = await client.blocks.create({\n block_type: Types.BlockBlockType.Email,\n resource_reference: 'CU123',\n reason_type: Types.BlockReasonType.NoIntentToPay,\n})" }, { "lang": "PHP", "label": "PHP", "source": "$block = $client->blocks()->create([\n \"params\" => [\n \"block_type\" => \"email\",\n \"reason_type\" => \"no_intent_to_pay\",\n \"resource_reference\" => \"example@example.com\",\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "Block block = client.blocks().create()\n .withBlockType(\"email\")\n .withReasonType(\"no_intent_to_pay\")\n .withResourceReference(\"example@example.com\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "blockCreateParams := gocardless.BlockCreateParams{\n BlockType: \"email\",\n ReasonType: \"no_intent_to_pay\",\n ResourceReference: \"example@example.com\",\n}\n\nblock, err := client.Blocks.Create(ctx, blockCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.Blocks.CreateAsync(\n new GoCardless.Services.BlockCreateRequest()\n {\n BlockType = \"email\",\n ReasonType = \"no_intent_to_pay\",\n ResourceReference = \"example@example.com\"\n }\n);\nGoCardless.Resources.Block block = resp.Block;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/blocks HTTP/1.1\nContent-Type: application/json\n{\n \"blocks\": {\n \"block_type\": \"email\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"example@example.com\"\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /block/BLC123\nContent-Type: application/json\n{\n \"blocks\": {\n \"id\": \"BLC123\",\n \"block_type\": \"email\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"example@example.com\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n }\n}\n\nPOST https://api.gocardless.com/blocks HTTP/1.1\nContent-Type: application/json\n{\n \"blocks\": {\n \"block_type\": \"bank_account\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"BA123\"\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /block/BLC456\nContent-Type: application/json\n{\n \"blocks\": {\n \"id\": \"BLC456\",\n \"block_type\": \"bank_account\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"BA123\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n }\n}" } ] }, "get": { "operationId": "list_block", "summary": "List multiple blocks", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your blocks.", "tags": [ "Block" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true }, { "name": "block_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/block_block_type" } }, { "name": "reason_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/block_reason_type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.blocks.all.each do |block|\n puts block.id\n puts block.block_type\nend" }, { "lang": "Python", "label": "Python", "source": "for block in client.blocks.all():\n print(block.id)\n print(block.block_type)" }, { "lang": "JavaScript", "label": "JavaScript", "source": "for await (const block of client.blocks.all({})) {\n console.log(block.id);\n console.log(block.block_type);\n}" }, { "lang": "PHP", "label": "PHP", "source": "foreach ($client->blocks()->all() as $record) {\n echo $record->id;\n echo $record->block_type;\n}" }, { "lang": "Java", "label": "Java", "source": "for (Block block : client.blocks().all().execute()) {\n System.out.println(block.getId());\n System.out.println(block.getBlockType());\n}" }, { "lang": "Go", "label": "Go", "source": "blockListParams := gocardless.BlockListParams{}\nblockListResult, err := client.Blocks.List(ctx, blockListParams)\nfor _, block := range blockListResult.Blocks {\n fmt.Println(block.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "foreach (GoCardless.Resources.Block block in client.Blocks.All())\n{\n Console.WriteLine(block.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/blocks HTTP/1.1\n\nHTTP/1.1 200 OK\nLocation: /blocks\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"blocks\": [\n {\n \"id\": \"BLC123\",\n \"block_type\": \"email\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"example@example.com\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n },\n {\n \"id\": \"BLC456\",\n \"block_type\": \"email_domain\",\n \"reason_type\": \"identity_fraud\",\n \"resource_reference\": \"example.com\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n }\n ]\n}" } ] } }, "/blocks/{block_id}": { "get": { "operationId": "get_blocks", "summary": "Get a single block", "description": "Retrieves the details of an existing block.", "tags": [ "Block" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "block_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The block id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "block = @client.blocks.get(\"BLC456\")" }, { "lang": "Python", "label": "Python", "source": "block = client.blocks.get(\"BLC456\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const block = await client.blocks.find(\"BLC456\");" }, { "lang": "PHP", "label": "PHP", "source": "$block = $client->blocks()->get(\"BLC456\");" }, { "lang": "Java", "label": "Java", "source": "Block block = client.blocks().get(\"BLC456\").execute();" }, { "lang": "Go", "label": "Go", "source": "block, err := client.Blocks.Get(ctx, \"BLC456\")" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.Blocks.GetAsync(\"BLC456\");\nGoCardless.Resources.Block block = resp.Block;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/blocks/BLC456 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"blocks\": {\n \"id\": \"BLC456\",\n \"block_type\": \"email\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"example@example.com\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n }\n}" } ] } }, "/blocks/{block_id}/actions/disable": { "post": { "operationId": "disable_block", "summary": "Disable a block", "description": "Disables a block so that it no longer will prevent mandate creation.", "tags": [ "Block" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "block_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The block id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "block = @client.blocks.disable(\"BLC123\")" }, { "lang": "Python", "label": "Python", "source": "block = client.blocks.disable(\"BLC123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const block = await client.blocks.disable(\"BLC456\");" }, { "lang": "PHP", "label": "PHP", "source": "$block = $client->blocks()->disable(\"BLC123\");" }, { "lang": "Java", "label": "Java", "source": "Block block = client.blocks().disable(\"BLC123\").execute();" }, { "lang": "Go", "label": "Go", "source": "block, err := client.Blocks.Disable(ctx, \"BLC123\")" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.Blocks.DisableAsync(\"BLC123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/blocks/BLC123/actions/disable HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"blocks\": {\n \"id\": \"BLC123\",\n \"block_type\": \"bank_account\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"BA123\",\n \"active\": false,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T19:26:28.305Z\"\n }\n}\n\nPOST https://api.gocardless.com/blocks/BLC123/actions/disable HTTP/1.1\nHTTP/1.1 409 Conflict\n\nPOST https://api.gocardless.com/blocks/MISSING_BLOCK_ID/actions/disable HTTP/1.1\nHTTP/1.1 404 NotFound" } ] } }, "/blocks/{block_id}/actions/enable": { "post": { "operationId": "enable_block", "summary": "Enable a block", "description": "Enables a previously disabled block so that it will prevent mandate creation", "tags": [ "Block" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "block_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The block id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "block = @client.blocks.enable(\"BLC123\")" }, { "lang": "Python", "label": "Python", "source": "block = client.blocks.enable(\"BLC123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const block = await client.blocks.enable(\"BLC456\");" }, { "lang": "PHP", "label": "PHP", "source": "$block = $client->blocks()->enable(\"BLC123\");" }, { "lang": "Java", "label": "Java", "source": "Block block = client.blocks().enable(\"BLC123\").execute();" }, { "lang": "Go", "label": "Go", "source": "block, err := client.Blocks.Enable(ctx, \"BLC123\")" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.Blocks.EnableAsync(\"BLC123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/blocks/BLC123/actions/enable HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"blocks\": {\n \"id\": \"BLC123\",\n \"block_type\": \"bank_account\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"BA123\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T19:26:28.305Z\"\n }\n}\n\nPOST https://api.gocardless.com/blocks/BLC123/actions/enable HTTP/1.1\nHTTP/1.1 409 Conflict\n\nPOST https://api.gocardless.com/blocks/MISSING_BLOCK_ID/actions/enable HTTP/1.1\nHTTP/1.1 404 NotFound" } ] } }, "/blocks/block_by_ref": { "post": { "operationId": "block_by_ref_blocks", "summary": "Create blocks by reference", "description": "Creates new blocks for a given reference. By default blocks will be active.\nReturns 201 if at least one block was created. Returns 200 if there were no new\nblocks created.", "tags": [ "Block" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_multi_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "object", "additionalProperties": false, "properties": { "reference_type": { "$ref": "#/components/schemas/block_reference_type" }, "reference_value": { "$ref": "#/components/schemas/block_reference_value" }, "reason_type": { "$ref": "#/components/schemas/block_reason_type" }, "reason_description": { "$ref": "#/components/schemas/block_reason_description" }, "active": { "$ref": "#/components/schemas/block_active" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "resp = @client.blocks.block_by_ref(\n params: {\n reference_type: \"customer\",\n reference_value: \"CU123\",\n reason_type: \"no_intent_to_pay\",\n }\n)\nblocks = resp.records" }, { "lang": "Python", "label": "Python", "source": "response = client.blocks.block_by_ref(\n params={\n \"reference_type\": \"customer\",\n \"reference_value\": \"CU123\",\n \"reason_type\": \"no_intent_to_pay\"\n }\n)\nblocks = response.records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const response = await client.blocks.block_by_ref(\n {\n reference_type: Types.BlockReferenceType.Customer,\n reference_value: 'CU123',\n reason_type: Types.BlockReasonType.NoIntentToPay\n }\n);\nconst blocks = response.blocks;" }, { "lang": "PHP", "label": "PHP", "source": "$block = $client->blocks()->blockByRef([\n \"params\" => [\n \"reference_type\" => \"customer\",\n \"reference_value\" => \"CU123\",\n \"reason_type\" => \"no_intent_to_pay\",\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "for (Block block : client.blocks().blockByRef()\n .withReferenceType(\"customer\")\n .withReferenceValue(\"CU123\")\n .withReasonType(\"no_intent_to_pay\")\n .execute()) {\n System.out.println(block.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "blockBlockByRefParams := gocardless.BlockBlockByRefParams{\n ReferenceType: \"customer\",\n ReferenceValue: \"CU123\",\n ReasonType: \"no_intent_to_pay\",\n}\n\nblockBlockByRefResult, err := client.Blocks.BlockByRef(ctx, blockBlockByRefParams)\nfor _, block := range blockBlockByRefResult.Blocks {\n fmt.Println(block.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.Blocks.BlockByRefAsync(new GoCardless.Services.BlockBlockByRefRequest() {\n ReferenceType = \"customer\",\n ReferenceValue = \"CU123\",\n ReasonType = \"no_intent_to_pay\",\n});\nIReadOnlyList < GoCardless.Resources.Block > blocks = resp.Blocks;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/blocks/block_by_ref HTTP/1.1\nContent-Type: application/json\n{\n \"blocks\": {\n \"reference_type\": \"customer\",\n \"reference_value\": \"CU123\",\n \"reason_type\": \"no_intent_to_pay\"\n }\n}\n\nHTTP/1.1 201 Created\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"blocks\": [\n {\n \"id\": \"BLC123\",\n \"block_type\": \"email\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"example@example.com\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n },\n {\n \"id\": \"BLC456\",\n \"block_type\": \"bank_account\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"BA123\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n }\n ]\n}\n\nPOST https://api.gocardless.com/blocks/block_by_ref HTTP/1.1\nContent-Type: application/json\n{\n \"blocks\": {\n \"reference_type\": \"customer\",\n \"reference_value\": \"CU123\",\n \"reason_type\": \"no_intent_to_pay\"\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"blocks\": [\n {\n \"id\": \"BLC123\",\n \"block_type\": \"email\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"example@example.com\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n },\n {\n \"id\": \"BLC456\",\n \"block_type\": \"bank_account\",\n \"reason_type\": \"no_intent_to_pay\",\n \"resource_reference\": \"BA123\",\n \"active\": true,\n \"created_at\": \"2021-03-25T17:26:28.305Z\",\n \"updated_at\": \"2021-03-25T17:26:28.305Z\"\n }\n ]\n}" } ] } }, "/creditors": { "post": { "operationId": "create_creditor", "summary": "Create a creditor", "description": "Creates a new creditor.\n\nRestricted: This endpoint is restricted to GoCardless Embed customers. Please [contact us](https://forms.gocardless.com/l/305971/2023-01-25/535t8n){:target=\"_blank\"} if you are interested in using this product. Partners should instead manage multiple merchant accounts by building a [partner integration](https://developer.gocardless.com/getting-started/partners/introduction/).
", "tags": [ "Creditor" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditor_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "creditors": { "type": "object", "additionalProperties": false, "required": [ "name", "country_code", "creditor_type" ], "properties": { "name": { "$ref": "#/components/schemas/creditor_name" }, "country_code": { "$ref": "#/components/schemas/creditor_country_code" }, "creditor_type": { "$ref": "#/components/schemas/creditor_creditor_type" }, "bank_reference_prefix": { "$ref": "#/components/schemas/creditor_bank_reference_prefix" }, "links": { "type": "object", "description": "", "additionalProperties": false, "properties": {} } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.creditors.create(\n params: {\n name: \"Acme\",\n country_code: \"GB\",\n creditor_type: \"company\",\n bank_reference_prefix: \"ACME\",\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.creditors.create(params={\n \"name\": \"Acme\",\n \"country_code\": \"GB\",\n \"creditor_type\": \"company\",\n \"bank_reference_prefix\": \"ACME\",\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const creditor = await client.creditors.create({\n name: \"Acme\",\n country_code: \"GB\",\n creditor_type: \"company\",\n bank_reference_prefix: \"ACME\",\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->creditors()->create([\n 'params' => ['name' => 'Acme',\n 'country_code' => 'GB',\n 'bank_reference_prefix' => 'ACME',\n 'creditor_type' => 'company']\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.CreditorService.CreditorCreateRequest.CreditorType;\n\nCreditor creditor = client.creditors().create()\n .withName(\"Acme\")\n .withCountryCode(\"GB\")\n .withCreditorType(CreditorType.COMPANY)\n .withBankReferencePrefix(\"ACME\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "creditorCreateParams := gocardless.CreditorCreateParams{\n Name: \"Acme\",\n CountryCode: \"GB\",\n CreditorType: \"company\",\n BankReferencePrefix: \"ACME\",\n}\n\ncreditor, err := client.Creditors.Create(ctx, creditorCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var creditorRequest = new GoCardless.Services.CreditorCreateRequest()\n{\n Name = \"Acme\",\n CountryCode = \"GB\",\n CreditorType = GoCardless.Services.CreditorCreateRequest.CreditorCreditorType.Company,\n BankReferencePrefix = \"ACME\",\n};\n\nvar creditorResponse = await client.Creditors.CreateAsync(creditorRequest);\nGoCardless.Resources.Creditor creditor = creditorResponse.Creditor;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/creditors HTTP/1.1\nContent-Type: application/json\n{\n \"creditors\": {\n \"name\": \"Acme\",\n \"country_code\": \"GB\",\n \"creditor_type\": \"company\",\n \"bank_reference_prefix\": \"ACME\"\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /creditors/CR123\nContent-Type: application/json\n{\n \"creditors\": {\n \"id\": \"CR123\",\n \"created_at\": \"2017-02-16T12:34:56.000Z\",\n \"name\": \"Acme\",\n \"address_line1\": null,\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": \"GB\",\n \"creditor_type\": \"company\",\n \"logo_url\": null,\n \"scheme_identifiers\": [],\n \"verification_status\": \"successful\",\n \"can_create_refunds\": false,\n \"fx_payout_currency\": null,\n \"mandate_imports_enabled\": false,\n \"custom_payment_pages_enabled\": true,\n \"merchant_responsible_for_notifications\": true,\n \"bank_reference_prefix\": \"ACME\",\n \"links\": {}\n }\n}" } ] }, "get": { "operationId": "list_creditor", "summary": "List creditors", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your creditors.", "tags": [ "Creditor" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditor_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.creditors.list\n\n@client.creditors.list(params: { limit: 2 })" }, { "lang": "Python", "label": "Python", "source": "client.creditors.list().records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const creditors = await client.creditors.list();\n\n// List the first three creditors.\nconst limitedCreditors = await client.creditors.list({ limit: 3 });" }, { "lang": "PHP", "label": "PHP", "source": "$client->creditors()->list();\n\n$client->creditors()->list([\n 'params' => ['created_at[gt]' => '2014-05-08T17:01:06.000Z']\n]);" }, { "lang": "Java", "label": "Java", "source": "for (Creditor creditor : client.creditors().all().execute()) {\n System.out.println(creditor.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "creditorListParams := gocardless.CreditorListParams{\n Limit: 3,\n}\n\n// List the first three creditors.\ncreditorListResult, err := client.Creditors.List(ctx, creditorListParams)\nfor _, creditor := range creditorListResult.Creditors {\n fmt.Println(creditor.Name)\n}" }, { "lang": "C#", "label": ".NET", "source": "var creditorListResponse = client.Creditors.All();\nforeach (GoCardless.Resources.Creditor creditor in creditorListResponse)\n{\n Console.WriteLine(creditor.Name);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/creditors HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"creditors\":[{\n \"id\": \"CR123\",\n \"created_at\": \"2017-02-16T12:34:56.000Z\",\n \"name\": \"Acme\",\n \"address_line1\": null,\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": \"GB\",\n \"creditor_type\": \"company\",\n \"logo_url\": null,\n \"scheme_identifiers\": [],\n \"verification_status\": \"successful\",\n \"can_create_refunds\": false,\n \"fx_payout_currency\": null,\n \"mandate_imports_enabled\": false,\n \"custom_payment_pages_enabled\": true,\n \"merchant_responsible_for_notifications\": true,\n \"bank_reference_prefix\": \"ACME\",\n \"links\": {}\n }]\n}" } ] } }, "/creditors/{creditor_id}": { "get": { "operationId": "get_creditors", "summary": "Get a single creditor", "description": "Retrieves the details of an existing creditor.", "tags": [ "Creditor" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "creditor_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The creditor id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditor_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.creditors.get(\"CR123\")" }, { "lang": "Python", "label": "Python", "source": "client.creditors.get(\"CR123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const creditor = await client.creditors.find(\"CR123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->creditors()->get('CR123');" }, { "lang": "Java", "label": "Java", "source": "Creditor creditor = client.creditors().get(\"CR123\").execute();" }, { "lang": "Go", "label": "Go", "source": "creditor, err := client.Creditors.Get(ctx, \"CR123\", gocardless.CreditorGetParams{})" }, { "lang": "C#", "label": ".NET", "source": "var creditorResponse = await client.Creditors.GetAsync(\"CR0123\");\nGoCardless.Resources.Creditor creditor = creditorResponse.Creditor;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/creditors/CR123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"creditors\": {\n \"id\": \"CR123\",\n \"created_at\": \"2017-02-16T12:34:56.000Z\",\n \"name\": \"Acme\",\n \"address_line1\": null,\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": \"GB\",\n \"creditor_type\": \"company\",\n \"logo_url\": null,\n \"scheme_identifiers\": [],\n \"verification_status\": \"successful\",\n \"can_create_refunds\": false,\n \"fx_payout_currency\": null,\n \"mandate_imports_enabled\": false,\n \"custom_payment_pages_enabled\": true,\n \"merchant_responsible_for_notifications\": true,\n \"bank_reference_prefix\": \"ACME\",\n \"links\": {}\n }\n}" } ] }, "put": { "operationId": "update_creditors", "summary": "Update a creditor", "description": "Updates a creditor object. Supports all of the fields supported when creating a creditor.", "tags": [ "Creditor" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "creditor_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The creditor id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditor_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "creditors": { "type": "object", "additionalProperties": false, "properties": { "name": { "$ref": "#/components/schemas/creditor_name" }, "address_line1": { "$ref": "#/components/schemas/creditor_address_line1" }, "address_line2": { "$ref": "#/components/schemas/creditor_address_line2" }, "address_line3": { "$ref": "#/components/schemas/creditor_address_line3" }, "city": { "$ref": "#/components/schemas/creditor_city" }, "region": { "$ref": "#/components/schemas/creditor_region" }, "postal_code": { "$ref": "#/components/schemas/creditor_postal_code" }, "country_code": { "$ref": "#/components/schemas/creditor_country_code" }, "bank_reference_prefix": { "$ref": "#/components/schemas/creditor_bank_reference_prefix" }, "links": { "type": "object", "description": "", "additionalProperties": false, "properties": { "default_aud_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in AUD.", "example": "BA234" }, "default_gbp_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in GBP.", "example": "BA123" }, "default_eur_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in EUR.", "example": "BA456" }, "default_sek_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in SEK.", "example": "BA789" }, "default_dkk_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in DKK.", "example": "BA790" }, "default_nzd_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in NZD.", "example": "BA791" }, "default_cad_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in CAD.", "example": "BA792" }, "default_usd_payout_account": { "type": "string", "nullable": true, "description": "ID of the [bank account](#core-endpoints-creditor-bank-accounts) which is set up to receive payouts in USD.", "example": "BA792" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.creditors.update(\n \"CR123\",\n params: {\n links: { default_gbp_payout_account: \"BA789\" }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.creditors.update(\"CR123\", params={\n \"links\": {\n \"default_gbp_payout_account\": \"BA789\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const creditor = await client.creditors.update(\n \"CR123\",\n {\n links: {\n default_gbp_payout_account: \"BA789\"\n }\n }\n);" }, { "lang": "PHP", "label": "PHP", "source": "$client->creditors()->update('CR123', [\n 'params' => ['links' => ['default_gbp_payout_account' => 'BA789']]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.creditors().update(\"CR123\")\n .withLinksDefaultGbpPayoutAccount(\"BA789\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "creditorUpdateParams := gocardless.CreditorUpdateParams{\n Links: &gocardless.CreditorUpdateParamsLinks{\n DefaultGbpPayoutAccount: \"BA789\",\n },\n}\n\ncreditor, err := client.Creditors.Update(ctx, \"CR123\", creditorUpdateParams)" }, { "lang": "C#", "label": ".NET", "source": "var creditorRequest = new GoCardless.Services.CreditorUpdateRequest()\n{\n Links = new GoCardless.Services.CreditorUpdateRequest.CreditorLinks()\n {\n DefaultGbpPayoutAccount = \"BA789\"\n }\n};\n\nvar creditorResponse = await client.Creditors.UpdateAsync(\"CR0123\", creditorRequest);" }, { "lang": "HTTP", "label": "HTTP", "source": "PUT https://api.gocardless.com/creditors/CR123 HTTP/1.1\nContent-Type: application/json\n{\n \"creditors\": {\n \"links\": {\n \"default_gbp_payout_account\": \"BA789\"\n }\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"creditors\": {\n \"id\": \"CR123\",\n \"created_at\": \"2017-02-16T12:34:56.000Z\",\n \"name\": \"Acme\",\n \"address_line1\": null,\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": null,\n \"region\": null,\n \"postal_code\": null,\n \"country_code\": \"GB\",\n \"creditor_type\": \"company\",\n \"logo_url\": null,\n \"scheme_identifiers\": [],\n \"verification_status\": \"successful\",\n \"can_create_refunds\": false,\n \"fx_payout_currency\": null,\n \"mandate_imports_enabled\": false,\n \"custom_payment_pages_enabled\": true,\n \"merchant_responsible_for_notifications\": true,\n \"bank_reference_prefix\": \"ACME\",\n \"links\": {\n \"default_gbp_payout_account\": \"BA789\"\n }\n }\n}" } ] } }, "/creditor_bank_accounts": { "post": { "operationId": "create_creditor_bank_account", "summary": "Create a creditor bank account", "description": "Creates a new creditor bank account object.", "tags": [ "Creditor Bank Account" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditor_bank_account_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "creditor_bank_accounts": { "type": "object", "additionalProperties": false, "required": [ "account_holder_name", "links" ], "properties": { "account_number": { "$ref": "#/components/schemas/creditor_bank_account_account_number" }, "bank_code": { "$ref": "#/components/schemas/creditor_bank_account_bank_code" }, "branch_code": { "$ref": "#/components/schemas/creditor_bank_account_branch_code" }, "iban": { "$ref": "#/components/schemas/creditor_bank_account_iban" }, "country_code": { "$ref": "#/components/schemas/creditor_bank_account_country_code" }, "currency": { "$ref": "#/components/schemas/creditor_bank_account_currency" }, "account_holder_name": { "$ref": "#/components/schemas/creditor_bank_account_account_holder_name" }, "account_type": { "$ref": "#/components/schemas/creditor_bank_account_account_type" }, "set_as_default_payout_account": { "$ref": "#/components/schemas/creditor_bank_account_set_as_default_payout_account" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "links": { "type": "object", "description": "", "additionalProperties": false, "required": [ "creditor" ], "properties": { "creditor": { "type": "string", "description": "ID of the [creditor](#core-endpoints-creditors) that owns this bank account.", "example": "CR123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.creditor_bank_accounts.create(\n params: {\n account_holder_name: \"Example Ltd\",\n account_number: \"55779911\",\n branch_code: \"200000\",\n country_code: \"GB\",\n links: {\n creditor: \"CR123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.creditor_bank_accounts.create(params={\n \"account_number\": \"55779911\",\n \"branch_code\": \"200000\",\n \"country_code\": \"GB\",\n \"account_holder_name\": \"Acme\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const creditorBankAccount = await client.creditorBankAccounts.create({\n account_number: \"55779911\",\n branch_code: \"200000\",\n country_code: \"GB\",\n account_holder_name: \"Acme\",\n links: {\n creditor: \"CR123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->creditorBankAccounts()->create([\n \"params\" => [\"account_number\" => \"55779911\",\n \"branch_code\" => \"200000\",\n \"country_code\" => \"GB\",\n \"account_holder_name\" => \"Acme\",\n \"links\" => [\"creditor\" => \"CR123\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().create()\n .withAccountNumber(\"55779911\")\n .withBranchCode(\"200000\")\n .withCountryCode(\"GB\")\n .withAccountHolderName(\"Acme\")\n .withLinksCreditor(\"CR123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "creditorBankAccountCreateParams := gocardless.CreditorBankAccountCreateParams{\n AccountNumber: \"55779911\",\n BranchCode: \"200000\",\n CountryCode: \"GB\",\n AccountHolderName: \"Acme\",\n}\n\ncreditorBankAccount, err := client.CreditorBankAccounts.Create(ctx, creditorBankAccountCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var creditorBankAccountRequest = new GoCardless.Services.CreditorBankAccountCreateRequest()\n{\n AccountHolderName = \"Example Ltd\",\n AccountNumber = \"55779911\",\n BranchCode = \"200000\",\n CountryCode = \"GB\",\n Links = new GoCardless.Services.CreditorBankAccountCreateRequest.CreditorBankAccountLinks()\n {\n Creditor = \"CR0123\"\n }\n};\n\nvar creditorBankAccountResponse = await client.CreditorBankAccounts.CreateAsync(creditorBankAccountRequest);\nGoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1\nContent-Type: application/json\n{\n \"creditor_bank_accounts\": {\n \"account_number\": \"55779911\",\n \"branch_code\": \"200000\",\n \"country_code\": \"GB\",\n \"account_holder_name\": \"Acme\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /creditor_bank_accounts/BA123\nContent-Type: application/json\n{\n \"creditor_bank_accounts\": {\n \"id\": \"BA123\",\n \"created_at\": \"2014-05-27T12:43:17.000Z\",\n \"account_holder_name\": \"Acme\",\n \"account_number_ending\": \"11\",\n \"account_type\": null,\n \"country_code\": \"GB\",\n \"currency\": \"GBP\",\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"enabled\": true,\n \"links\": {\n \"creditor\": \"CR123\"\n },\n \"verification_status\": \"pending\"\n }\n}" } ] }, "get": { "operationId": "list_creditor_bank_account", "summary": "List creditor bank accounts", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your creditor bank accounts.", "tags": [ "Creditor Bank Account" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true }, { "name": "creditor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/creditor_identity" } }, { "name": "enabled", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "true", "false" ], "type": "string" }, { "type": "boolean" } ] }, "description": "If `true`, only return enabled bank accounts. If `false`, only return disabled bank accounts." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditor_bank_account_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.creditor_bank_accounts.list\n\n@client.creditor_bank_accounts.list(params: { enabled: true })" }, { "lang": "Python", "label": "Python", "source": "client.creditor_bank_accounts.list().records\n\nclient.creditor_bank_accounts.list(params={\"creditor\": \"CR123\"}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const creditorBankAccounts = await client.creditorBankAccounts.list();\n\n// List all 'enabled' creditor bank accounts.\nconst enabledCreditorBankAccounts = await client.creditorBankAccounts.list({ enabled: true });" }, { "lang": "PHP", "label": "PHP", "source": "$client->creditorBankAccounts()->list();\n\n$client->creditorBankAccounts()->list([\n \"params\" => [\"enabled\" => true]\n]);" }, { "lang": "Java", "label": "Java", "source": "for (CreditorBankAccount creditorBankAccount : client.creditorBankAccounts().all().withCreditor(\"CR123\").execute()) {\n System.out.println(creditorBankAccount.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "creditorBankAccountListParams := gocardless.CreditorBankAccountListParams{}\ncreditorBankAccountListResult, err := client.CreditorBankAccounts.List(ctx, creditorBankAccountListParams)\nfor _, creditorBankAccount := range creditorBankAccountListResult.CreditorBankAccounts {\n fmt.Println(creditorBankAccount.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var creditorBankAccountRequest = new GoCardless.Services.CreditorBankAccountListRequest()\n{\n Creditor = \"CR000123\"\n};\n\nvar creditorBankAccountListResponse = client.CreditorBankAccounts.All(creditorBankAccountRequest);\nforeach (GoCardless.Resources.CreditorBankAccount creditorBankAccount in creditorBankAccountListResponse)\n{\n Console.WriteLine(creditorBankAccount.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/creditor_bank_accounts HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": \"BA123\"\n },\n \"limit\": 50\n },\n \"creditor_bank_accounts\":[{\n \"id\": \"BA123\",\n \"created_at\": \"2014-05-27T12:43:17.000Z\",\n \"account_holder_name\": \"Acme\",\n \"account_number_ending\": \"11\",\n \"account_type\": null,\n \"country_code\": \"GB\",\n \"currency\": \"GBP\",\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"enabled\": true,\n \"links\": {\n \"creditor\": \"CR123\"\n },\n \"verification_status\": \"pending\"\n }]\n}" } ] } }, "/creditor_bank_accounts/{creditor_bank_account_id}": { "get": { "operationId": "get_creditor_bank_accounts", "summary": "Get a single creditor bank account", "description": "Retrieves the details of an existing creditor bank account.", "tags": [ "Creditor Bank Account" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "creditor_bank_account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The creditor bank account id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditor_bank_account_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.creditor_bank_accounts.get(\"BA123\")" }, { "lang": "Python", "label": "Python", "source": "client.creditor_bank_accounts.get(\"BA123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const creditorBankAccount = await client.creditorBankAccounts.find('BA123');" }, { "lang": "PHP", "label": "PHP", "source": "$client->creditorBankAccounts()->get(\"BA123\");" }, { "lang": "Java", "label": "Java", "source": "CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().get(\"BA123\").execute();" }, { "lang": "Go", "label": "Go", "source": "creditorBankAccount, err := client.CreditorBankAccounts.Get(ctx, \"BA123\")" }, { "lang": "C#", "label": ".NET", "source": "var creditorBankAccountResponse = await client.CreditorBankAccounts.GetAsync(\"BA0123\");\nGoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/creditor_bank_accounts/BA123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"creditor_bank_accounts\": {\n \"id\": \"BA123\",\n \"created_at\": \"2014-05-27T12:43:17.000Z\",\n \"account_holder_name\": \"Acme\",\n \"account_number_ending\": \"11\",\n \"account_type\": null,\n \"country_code\": \"GB\",\n \"currency\": \"GBP\",\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"enabled\": true,\n \"links\": {\n \"creditor\": \"CR123\"\n },\n \"verification_status\": \"pending\"\n }\n}" } ] } }, "/creditor_bank_accounts/{creditor_bank_account_id}/actions/disable": { "post": { "operationId": "disable_creditor_bank_account", "summary": "Disable a creditor bank account", "description": "Immediately disables the bank account, no money can be paid out to a disabled account.\n\nThis will return a `disable_failed` error if the bank account has already been disabled.\n\nA disabled bank account can be re-enabled by creating a new bank account resource with the same details.", "tags": [ "Creditor Bank Account" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "creditor_bank_account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The creditor bank account id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditor_bank_account_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.creditor_bank_accounts.disable(\"BA123\")" }, { "lang": "Python", "label": "Python", "source": "client.creditor_bank_accounts.disable(\"BA123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const creditorBankAccountResponse = await client.creditorBankAccounts.disable(\"BA123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->creditorBankAccounts()->disable(\"BA123\");" }, { "lang": "Java", "label": "Java", "source": "client.creditorBankAccounts().disable(\"BA123\").execute();" }, { "lang": "Go", "label": "Go", "source": "creditorBankAccount, err := client.CreditorBankAccounts.Disable(ctx, \"BA123\")" }, { "lang": "C#", "label": ".NET", "source": "var creditorBankAccountResponse = await client.CreditorBankAccounts.DisableAsync(\"BA0123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/creditor_bank_accounts/BA123/actions/disable HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"creditor_bank_accounts\": {\n \"id\": \"BA123\",\n \"created_at\": \"2014-05-27T12:43:17.000Z\",\n \"account_holder_name\": \"Acme\",\n \"account_number_ending\": \"11\",\n \"account_type\": null,\n \"country_code\": \"GB\",\n \"currency\": \"GBP\",\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"enabled\": false,\n \"links\": {\n \"creditor\": \"CR123\"\n },\n \"verification_status\": \"pending\"\n }\n}" } ] } }, "/currency_exchange_rates": { "get": { "operationId": "list_currency_exchange_rate", "summary": "List exchange rates", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of all exchange rates.", "tags": [ "Currency Exchange Rate" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "source", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/currency_exchange_rate_source" } }, { "name": "target", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/currency_exchange_rate_target" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/currency_exchange_rate_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.currency_exchange_rates.list(params: { source: \"EUR\", target: \"GBP\" })" }, { "lang": "Python", "label": "Python", "source": "client.currency_exchange_rates.list(params={\"source\": \"EUR\", \"target\": \"GBP\"}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const currencyExchangeRates = await client.currencyExchangeRates.list();\n\n// List the currency exchange rate for a source and target currency.\nconst filteredRates = await client.currencyExchangeRates.list({ source: 'EUR', target: 'GBP' });" }, { "lang": "PHP", "label": "PHP", "source": "$client->currencyExchangeRates()->list([\n \"params\" => [\"source\" => \"EUR\", \"target\" => \"GBP\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.currencyExchangeRates().all().withSource(\"EUR\").withTarget(\"GBP\").execute();" }, { "lang": "Go", "label": "Go", "source": "currencyExchangeRateListParams := gocardless.CurrencyExchangeRateListParams{\n Source: \"EUR\",\n Target: \"GBP\",\n}\n\ncurrencyExchangeRateListResult, err := client.CurrencyExchangeRates.List(ctx, currencyExchangeRateListParams)\nfor _, currencyExchangeRate := range currencyExchangeRateListResult.CurrencyExchangeRates {\n fmt.Println(currencyExchangeRate.Rate)\n}" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.CurrencyExchangeRateListRequest()\n{\n Source = \"EUR\",\n Target = \"GBP\"\n};\n\nvar response = client.CurrencyExchangeRates.All(request);\nforeach (GoCardless.Resources.CurrencyExchangeRate rate in response)\n{\n Console.WriteLine(rate.Rate);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/currency_exchange_rates?source=GBP&target=EUR HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"currency_exchange_rates\": [\n {\n \"rate\": \"1.19111\",\n \"source\": \"GBP\",\n \"target\": \"EUR\",\n \"time\": \"2020-02-24T23:50:04.000Z\"\n }\n ],\n \"meta\": {\n \"cursors\": {\n \"after\": null,\n \"before\": null\n },\n \"limit\": 50\n }\n}" } ] } }, "/customers": { "post": { "operationId": "create_customer", "summary": "Create a customer", "description": "Creates a new customer object.\n\nRestricted: this endpoint is [restricted](#overview-restrictions) to [GoCardless Pro](https://gocardless.com/pricing) and [GoCardless Enterprise](https://gocardless.com/pricing) accounts with approved payment pages.
\n\nWarning: this endpoint is a legacy API endpoint and does not support GoCardless' newest features. We recommend using the [Billing Requests API](/billing-requests/overview) instead.
", "tags": [ "Customer" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "object", "additionalProperties": false, "properties": { "email": { "$ref": "#/components/schemas/customer_email" }, "given_name": { "$ref": "#/components/schemas/customer_given_name" }, "family_name": { "$ref": "#/components/schemas/customer_family_name" }, "company_name": { "$ref": "#/components/schemas/customer_company_name" }, "address_line1": { "$ref": "#/components/schemas/customer_address_line1" }, "address_line2": { "$ref": "#/components/schemas/customer_address_line2" }, "address_line3": { "$ref": "#/components/schemas/customer_address_line3" }, "city": { "$ref": "#/components/schemas/customer_city" }, "region": { "$ref": "#/components/schemas/customer_region" }, "postal_code": { "$ref": "#/components/schemas/customer_postal_code" }, "country_code": { "$ref": "#/components/schemas/customer_country_code" }, "language": { "$ref": "#/components/schemas/customer_language" }, "phone_number": { "$ref": "#/components/schemas/customer_phone_number" }, "swedish_identity_number": { "$ref": "#/components/schemas/customer_swedish_identity_number" }, "danish_identity_number": { "$ref": "#/components/schemas/customer_danish_identity_number" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.customers.create(\n params: {\n email: \"user@example.com\",\n given_name: \"Jacob\",\n family_name: \"Pargin\",\n country_code: \"GB\"\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.customers.create(params={\n \"email\": \"user@example.com\",\n \"given_name\": \"Frank\",\n \"family_name\": \"Osborne\",\n \"address_line1\": \"27 Acer Road\",\n \"address_line2\": \"Apt 2\",\n \"city\": \"London\",\n \"postal_code\": \"E8 3GX\",\n \"country_code\": \"GB\",\n \"metadata\": {\n \"salesforce_id\": \"ABCD1234\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const customer = await client.customers.create({\n email: \"user@example.com\",\n given_name: \"Frank\",\n family_name: \"Osborne\",\n address_line1: \"27 Acer Road\",\n address_line2: \"Apt 2\",\n city: \"London\",\n postal_code: \"E8 3GX\",\n country_code: \"GB\",\n metadata: {\n salesforce_id: \"ABCD1234\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->customers()->create([\n \"params\" => [\"email\" => \"tim@gocardless.com\",\n \"given_name\" => \"Tim\",\n \"family_name\" => \"Rogers\",\n \"country_code\" => \"GB\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "Customer customer = client.customers().create()\n .withEmail(\"user@example.com\")\n .withGivenName(\"Frank\")\n .withFamilyName(\"Osborne\")\n .withAddressLine1(\"27 Acer Road\")\n .withAddressLine2(\"Apt 2\")\n .withCity(\"London\")\n .withPostalCode(\"E8 3GX\")\n .withCountryCode(\"GB\")\n .withMetadata(\"salesforce_id\", \"ABCD1234\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "customerCreateParams := gocardless.CustomerCreateParams{\n AddressLine1: \"27 Acer Road\",\n AddressLine2: \"Apt 2\",\n City: \"London\",\n PostalCode: \"E8 3GX\",\n CountryCode: \"GB\",\n Email: \"user@example.com\",\n GivenName: \"Frank\",\n FamilyName: \"Osborne\",\n}\n\ncustomer, err := client.Customers.Create(ctx, customerCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var customerRequest = new GoCardless.Services.CustomerCreateRequest()\n{\n Email = \"user@example.com\",\n GivenName = \"Frank\",\n FamilyName = \"Osborne\",\n AddressLine1 = \"27 Acer Road\",\n AddressLine2 = \"Apt 2\",\n City = \"London\",\n PostalCode = \"E8 3GX\",\n CountryCode = \"GB\",\n Metadata = new DictionaryThe action of removing a customer cannot be reversed, so please use with care.
", "tags": [ "Customer" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer id" } ], "responses": { "204": { "description": "Resource deleted successfully (no content)" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "object", "additionalProperties": false } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.customers.remove(\"CU123\")" }, { "lang": "Python", "label": "Python", "source": "client.customers.remove(\"CU123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const customer = await client.customers.remove(\"CU123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->customers()->remove(\"CU123\");" }, { "lang": "Java", "label": "Java", "source": "client.customers().remove(\"CU123\").execute();" }, { "lang": "Go", "label": "Go", "source": "customer, err := client.Customers.Remove(ctx, \"CU123\", gocardless.CustomerRemoveParams{})" }, { "lang": "C#", "label": ".NET", "source": "await client.Customers.RemoveAsync(\"CU0123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "DELETE https://api.gocardless.com/customers/CU123 HTTP/1.1\n\nHTTP/1.1 204 No Content\n\nDELETE https://api.gocardless.com/customers/CU123 HTTP/1.1\n\nHTTP/1.1 410 Gone\nContent-Type: application/json\n{\n \"error\": {\n \"documentation_url\": \"https://developer.gocardless.com/api-reference#customer_data_removed\",\n \"message\": \"This customer data has been removed\",\n \"type\": \"invalid_api_usage\",\n \"errors\": [\n {\n \"reason\": \"customer_removed\",\n \"message\": \"This customer data has been removed\"\n }\n ],\n \"code\": 410,\n \"request_id\": \"deadbeef-0000-4000-0000-444400004444\"\n }\n}" } ] } }, "/customer_bank_accounts": { "post": { "operationId": "create_customer_bank_account", "summary": "Create a customer bank account", "description": "Creates a new customer bank account object.\n\nThere are three different ways to supply bank account details:\n\n- [Local details](#appendix-local-bank-details)\n\n- IBAN\n\n- [Customer Bank Account Tokens](#javascript-flow-create-a-customer-bank-account-token)\n\nFor more information on the different fields required in each country, see [local bank details](#appendix-local-bank-details).\n\nRestricted: this endpoint requires approved [custom payment pages](https://support.gocardless.com/hc/en-gb/articles/115004521925-Custom-Payment-Pages).
\n\nNote: this endpoint is a legacy API endpoint and does not support GoCardless' newest features. We recommend using the [Billing Requests API](/billing-requests/overview) instead.
", "tags": [ "Customer Bank Account" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_bank_account_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_bank_accounts": { "type": "object", "additionalProperties": false, "required": [ "links" ], "properties": { "account_number": { "$ref": "#/components/schemas/customer_bank_account_account_number" }, "bank_code": { "$ref": "#/components/schemas/customer_bank_account_bank_code" }, "branch_code": { "$ref": "#/components/schemas/customer_bank_account_branch_code" }, "iban": { "$ref": "#/components/schemas/customer_bank_account_iban" }, "country_code": { "$ref": "#/components/schemas/customer_bank_account_country_code" }, "currency": { "$ref": "#/components/schemas/customer_bank_account_currency" }, "account_holder_name": { "$ref": "#/components/schemas/customer_bank_account_account_holder_name" }, "account_type": { "$ref": "#/components/schemas/customer_bank_account_account_type" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "links": { "type": "object", "description": "", "additionalProperties": false, "required": [ "customer" ], "properties": { "customer": { "type": "string", "description": "ID of the [customer](#core-endpoints-customers) that owns this bank account." }, "customer_bank_account_token": { "type": "string", "description": "ID of a [customer bank account token](#javascript-flow-customer-bank-account-tokens) to use in place of bank account parameters." } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.customer_bank_accounts.create(\n params: {\n account_holder_name: \"Fran Cosborne\",\n account_number: \"55779911\",\n branch_code: \"200000\",\n country_code: \"GB\",\n links: {\n customer: \"CU123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.customer_bank_accounts.create(params={\n \"account_number\": \"55779911\",\n \"branch_code\": \"200000\",\n \"account_holder_name\": \"Frank Osborne\",\n \"country_code\": \"GB\",\n \"links\": {\n \"customer\": \"CU123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const customerBankAccount = await client.customerBankAccounts.create({\n account_number: \"55779911\",\n branch_code: \"200000\",\n account_holder_name: \"Frank Osborne\",\n country_code: \"GB\",\n links: {\n customer: \"CU123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->customerBankAccounts()->create([\n \"params\" => [\"account_number\" => \"55779911\",\n \"branch_code\" => \"200000\",\n \"account_holder_name\" => \"Frank Osborne\",\n \"country_code\" => \"GB\",\n \"links\" => [\"customer\" => \"CU123\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "CustomerBankAccount customerBankAccount = client.customerBankAccounts().create()\n .withAccountNumber(\"55779911\")\n .withBranchCode(\"200000\")\n .withAccountHolderName(\"Frank Osborne\")\n .withCountryCode(\"GB\")\n .withLinksCustomer(\"CU123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "customerBankAccountCreateParams := gocardless.CustomerBankAccountCreateParams{\n AccountNumber: \"55779911\",\n BranchCode: \"200000\",\n AccountHolderName: \"Frank Osborne\",\n CountryCode: \"GB\",\n Links: gocardless.CustomerBankAccountCreateParamsLinks{\n Customer: \"CU123\",\n },\n}\n\ncustomerBankAccount, err := client.CustomerBankAccounts.Create(ctx, customerBankAccountCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountCreateRequest()\n{\n AccountHolderName = \"Example Ltd\",\n AccountNumber = \"55779911\",\n BranchCode = \"200000\",\n CountryCode = \"GB\",\n Links = new GoCardless.Services.CustomerBankAccountCreateRequest.CustomerBankAccountLinks()\n {\n Customer = \"CU0123\"\n }\n};\n\nvar customerBankAccountResponse = await client.CustomerBankAccounts.CreateAsync(customerBankAccountRequest);\nGoCardless.Resources.CustomerBankAccount customerBankAccount = customerBankAccountResponse.CustomerBankAccount;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1\nContent-Type: application/json\n{\n \"customer_bank_accounts\": {\n \"account_number\": \"55779911\",\n \"branch_code\": \"200000\",\n \"account_holder_name\": \"Frank Osborne\",\n \"country_code\": \"GB\",\n \"links\": {\n \"customer\": \"CU123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /customer_bank_accounts/BA123\nContent-Type: application/json\n{\n \"customer_bank_accounts\": {\n \"id\": \"BA123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"account_holder_name\": \"Frank Osborne\",\n \"account_number_ending\": \"11\",\n \"country_code\": \"GB\",\n \"currency\": \"GBP\",\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"metadata\": {},\n \"enabled\": true,\n \"links\": {\n \"customer\": \"CU123\"\n }\n }\n}" } ] }, "get": { "operationId": "list_customer_bank_account", "summary": "List customer bank accounts", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your bank accounts.", "tags": [ "Customer Bank Account" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true }, { "name": "customer", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/customer_identity" } }, { "name": "enabled", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "true", "false" ], "type": "string" }, { "type": "boolean" } ] }, "description": "Get enabled or disabled customer bank accounts." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_bank_account_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.customer_bank_accounts.list\n\n@client.customer_bank_accounts.list(\n params: {\n customer: \"CU123\",\n enabled: true\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.customer_bank_accounts.list(params={\"customer\": \"CU123\"}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const customerBankAccount = await client.customerBankAccounts.list();\n\n// List all 'enabled' customer bank accounts.\nawait client.customerBankAccounts.list({ enabled: true });" }, { "lang": "PHP", "label": "PHP", "source": "$client->customerBankAccounts()->list();\n\n$client->customerBankAccounts()->list([\n \"params\" => [\"customer\" => \"CU123\",\n \"enabled\" => true]\n]);" }, { "lang": "Java", "label": "Java", "source": "for (CustomerBankAccount customerBankAccount : client.customerBankAccounts().all().withCustomer(\"CU123\").withEnabled(true).execute()) {\n System.out.println(customerBankAccount.getAccountHolderName());\n}" }, { "lang": "Go", "label": "Go", "source": "customerBankAccountListParams := gocardless.CustomerBankAccountListParams{\n Enabled: true,\n}\n\ncustomerBankAccountListResult, err := client.CustomerBankAccounts.List(ctx, customerBankAccountListParams)\nfor _, customerBankAccount := range customerBankAccountListResult.CustomerBankAccounts {\n fmt.Println(customerBankAccount.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountListRequest()\n{\n Customer = \"CU000123\"\n};\n\nvar customerBankAccountListResponse = client.CustomerBankAccounts.All(customerBankAccountRequest);\nforeach (GoCardless.Resources.CustomerBankAccount customerBankAccount in customerBankAccountListResponse)\n{\n Console.WriteLine(customerBankAccount.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/customer_bank_accounts HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"customer_bank_accounts\": [{\n \"id\": \"BA123\",\n \"created_at\": \"2014-05-08T17:01:06.001Z\",\n \"account_holder_name\": \"Frank Osborne\",\n \"account_number_ending\": \"11\",\n \"account_type\": null,\n \"country_code\": \"GB\",\n \"currency\": \"GBP\",\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"metadata\": {},\n \"enabled\": true,\n \"links\": {\n \"customer\": \"CU123\"\n }\n }]\n}" } ] } }, "/customer_bank_accounts/{customer_bank_account_id}": { "get": { "operationId": "get_customer_bank_accounts", "summary": "Get a single customer bank account", "description": "Retrieves the details of an existing bank account.", "tags": [ "Customer Bank Account" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "customer_bank_account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer bank account id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_bank_account_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.customer_bank_accounts.get(\"BA123\")" }, { "lang": "Python", "label": "Python", "source": "client.customer_bank_accounts.get(\"BA123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const customerBankAccount = await client.customerBankAccounts.find(\"BA123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->customerBankAccounts()->get(\"BA123\");" }, { "lang": "Java", "label": "Java", "source": "CustomerBankAccount customerBankAccount = client.customerBankAccounts().get(\"BA123\").execute();" }, { "lang": "Go", "label": "Go", "source": "customerBankAccount, err := client.CustomerBankAccounts.Get(ctx, \"BA123\")" }, { "lang": "C#", "label": ".NET", "source": "var customerBankAccountResponse = await client.CustomerBankAccounts.GetAsync(\"BA0123\");\nGoCardless.Resources.CustomerBankAccount customerBankAccount = customerBankAccountResponse.CustomerBankAccount;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"customer_bank_accounts\": {\n \"id\": \"BA123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"account_number_ending\": \"11\",\n \"account_holder_name\": \"Frank Osborne\",\n \"account_type\": null,\n \"country_code\": \"GB\",\n \"currency\": \"GBP\",\n \"bank_name\": \"BARCLAYS BANK PLC\",\n \"metadata\": {},\n \"enabled\": true,\n \"links\": {\n \"customer\": \"CU123\"\n }\n }\n}\n\nGET https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1\n\nHTTP/1.1 410 Gone\nContent-Type: application/json\n{\n \"error\": {\n \"documentation_url\": \"https://developer.gocardless.com/api-reference#customer_data_removed\",\n \"message\": \"This customer data has been removed\",\n \"type\": \"invalid_api_usage\",\n \"errors\": [\n {\n \"reason\": \"customer_removed\",\n \"message\": \"This customer data has been removed\"\n }\n ],\n \"code\": 410,\n \"request_id\": \"deadbeef-0000-4000-0000-444400004444\"\n }\n}" } ] }, "put": { "operationId": "update_customer_bank_accounts", "summary": "Update a customer bank account", "description": "Updates a customer bank account object. Only the metadata parameter is allowed.", "tags": [ "Customer Bank Account" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "customer_bank_account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The customer bank account id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_bank_account_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_bank_accounts": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.customer_bank_accounts.update(\n \"BA123\",\n params: {\n metadata: { description: \"Business account\" }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.customer_bank_accounts.update(\"BA123\", params={\n \"metadata\": {\"key\": \"value\"}\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const customerBankAccount = await client.customerBankAccounts.update(\n \"BA123\",\n {\n metadata: {\n key: \"value\"\n }\n }\n);" }, { "lang": "PHP", "label": "PHP", "source": "$client->customerBankAccounts()->update(\"BA123\", [\n \"params\" => [\"metadata\" => [\"key\" => \"value\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.customerBankAccounts().update(\"BA123\")\n .withMetadata(\"description\", \"Business account\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "customerBankAccountUpdateParams := gocardless.CustomerBankAccountUpdateParams{\n Metadata: map[string]string{\"key\": \"value\"},\n}\n\ncustomerBankAccount, err := client.CustomerBankAccounts.Update(ctx, \"BA123\", customerBankAccountUpdateParams)" }, { "lang": "C#", "label": ".NET", "source": "var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountUpdateRequest()\n{\n Metadata = new DictionaryImportant: 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.
", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true }, { "name": "billing_request", "in": "query", "required": false, "schema": { "type": "string", "example": "BRQ123" }, "description": "ID of a [billing request](#billing-requests-billing-requests). If specified, this endpoint will return all events for the given billing request." }, { "name": "creditor", "in": "query", "required": false, "schema": { "type": "string", "example": "CR123" }, "description": "ID of an [creditor](#core-endpoints-creditors). If specified, this endpoint will return all events for the given creditor." }, { "name": "export", "in": "query", "required": false, "schema": { "type": "string", "example": "EX123" }, "description": "ID of an export. If specified, this endpoint will return all events for the given export." }, { "name": "instalment_schedule", "in": "query", "required": false, "schema": { "type": "string", "example": "IS123" }, "description": "ID of an [instalment schedule](#core-endpoints-instalment-schedules). If specified, this endpoint will return all events for the given instalment schedule." }, { "name": "mandate", "in": "query", "required": false, "schema": { "type": "string", "example": "MD123" }, "description": "ID of a [mandate](#core-endpoints-mandates). If specified, this endpoint will return all events for the given mandate." }, { "name": "outbound_payment", "in": "query", "required": false, "schema": { "type": "string", "example": "OUT123" }, "description": "ID of an [outbound_payment](#core-endpoints-outbound-payments). If specified, this endpoint will return all events for the given payment." }, { "name": "payer_authorisation", "in": "query", "required": false, "schema": { "type": "string", "example": "PAU123" }, "description": "ID of a [payer authorisation](#core-endpoints-payer-authorisations)." }, { "name": "payment", "in": "query", "required": false, "schema": { "type": "string", "example": "PM123" }, "description": "ID of a [payment](#core-endpoints-payments). If specified, this endpoint will return all events for the given payment." }, { "name": "payment_account_transaction", "in": "query", "required": false, "schema": { "type": "string", "example": "PATR123" }, "description": "ID of a payment account transaction. If specified, this endpoint will return all events for the given transaction." }, { "name": "payout", "in": "query", "required": false, "schema": { "type": "string", "example": "PO123" }, "description": "ID of a [payout](#core-endpoints-payouts). If specified, this endpoint will return all events for the given payout." }, { "name": "refund", "in": "query", "required": false, "schema": { "type": "string", "example": "RF123" }, "description": "ID of a [refund](#core-endpoints-refunds). If specified, this endpoint will return all events for the given refund." }, { "name": "subscription", "in": "query", "required": false, "schema": { "type": "string", "example": "SB123" }, "description": "ID of a [subscription](#core-endpoints-subscriptions). If specified, this endpoint will return all events for the given subscription." }, { "name": "scheme_identifier", "in": "query", "required": false, "schema": { "type": "string", "example": "SB123" }, "description": "ID of a [scheme identifier](#core-endpoints-scheme-identifiers). If specified, this endpoint will return all events for the given scheme identifier." }, { "name": "parent_event", "in": "query", "required": false, "schema": { "type": "string", "example": "EV123" }, "description": "ID of an event. If specified, this endpoint will return all events whose parent_event is the given event ID." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit to events with a given `action`." }, { "name": "resource_type", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/event_resource_type" }, { "description": "Type of resource that you'd like to get all events for.\nCannot be used together with the `billing_request`, `creditor`, `export`,`instalment_schedule`, `mandate`, `payer_authorisation`, `payment`, `payout`, `refund`, `scheme_identifier`, `subscription`, `outbound_payment` or `payment_account_transaction` parameters." } ] } }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/event_include_resource_type" } ] }, "description": "Includes linked resources in the response. Must be used with the `resource_type` parameter specified." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/event_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.events.list\n\n@client.events.list(params: { resource_type: \"payments\" })\n\n@client.events.list.records.each { |event| puts event.inspect }" }, { "lang": "Python", "label": "Python", "source": "client.events.list().records\n\nclient.events.list(params={\"resource_type\": \"payments\"}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const events = await client.events.list();\n\n// List all events of a given resource type.\nconst paymentEvents = await client.events.list({ resource_type: \"payments\" });" }, { "lang": "PHP", "label": "PHP", "source": "$client->events()->list();\n\n$client->events()->list([\n \"params\" => [\"resource_type\" => \"payments\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.EventService.EventListRequest.ResourceType;\n\nfor (Event event : client.events().all().withResourceType(ResourceType.PAYMENTS).execute()) {\n System.out.println(event.getAction());\n}" }, { "lang": "Go", "label": "Go", "source": "eventListParams := gocardless.EventListParams{\n ResourceType: \"payments\",\n}\n\neventListResult, err := client.Events.List(ctx, eventListParams)\nfor _, event := range eventListResult.Events {\n fmt.Println(event.Action)\n}" }, { "lang": "C#", "label": ".NET", "source": "var eventRequest = new GoCardless.Services.EventListRequest()\n{\n ResourceType = GoCardless.Services.EventListRequest.EventResourceType.Payments\n};\n\nvar eventListResponse = client.Events.All(eventRequest);\nforeach (GoCardless.Resources.Event eventResource in eventListResponse)\n{\n Console.WriteLine(eventResource.Action);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/events HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"after\": null,\n \"before\": null\n },\n \"limit\": 50\n },\n \"events\":[\n {\n \"id\": \"EV123\",\n \"created_at\": \"2014-04-08T17:01:06.000Z\",\n \"resource_type\": \"mandates\",\n \"action\": \"cancelled\",\n \"details\": {\n \"origin\": \"bank\",\n \"cause\": \"bank_account_disabled\",\n \"description\": \"Customer's bank account closed\",\n \"scheme\": \"bacs\",\n \"reason_code\": \"ADDACS-B\"\n },\n \"metadata\": {},\n \"resource_metadata\": { \"order_id\": \"123\" },\n \"links\": {\n \"mandate\": \"MD123\"\n }\n },\n {\n \"id\": \"EV456\",\n \"created_at\": \"2014-04-08T17:01:06.000Z\",\n \"resource_type\": \"payments\",\n \"action\": \"cancelled\",\n \"details\": {\n \"origin\": \"bank\",\n \"cause\": \"mandate_cancelled\",\n \"description\": \"The mandate for this payment was cancelled at a bank branch.\",\n \"scheme\": \"bacs\",\n \"reason_code\": \"ADDACS-B\"\n },\n \"metadata\": {},\n \"resource_metadata\": { \"order_dispatch_date\": \"2014-05-22\" },\n \"links\": {\n \"payment\": \"PM123\",\n \"parent_event\": \"EV123\"\n }\n }\n ]\n}\n\nGET https://api.gocardless.com/events?resource_type=payments&include=payment HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"after\": null,\n \"before\": null\n },\n \"limit\": 50\n },\n \"events\":[\n {\n \"id\": \"EV456\",\n \"created_at\": \"2014-04-08T17:01:06.000Z\",\n \"resource_type\": \"payments\",\n \"action\": \"cancelled\",\n \"details\": {\n \"origin\": \"bank\",\n \"cause\": \"mandate_cancelled\",\n \"description\": \"The mandate for this payment was cancelled at a bank branch.\",\n \"scheme\": \"bacs\",\n \"reason_code\": \"ADDACS-B\"\n },\n \"metadata\": {},\n \"resource_metadata\": { \"order_dispatch_date\": \"2014-05-22\" },\n \"links\": {\n \"payment\": \"PM123\",\n \"parent_event\": \"EV123\"\n }\n }\n ],\n \"linked\": {\n \"payments\": [\n {\n \"id\": \"PM123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"charge_date\": \"2014-05-15\",\n \"amount\": 100,\n \"description\": null,\n \"currency\": \"GBP\",\n \"status\": \"paid_out\",\n \"reference\": \"WINEBOX001\",\n \"metadata\": {\n \"order_dispatch_date\": \"2014-05-22\"\n },\n \"amount_refunded\": 0,\n \"links\": {\n \"mandate\": \"MD123\",\n \"creditor\": \"CR123\"\n }\n }\n ]\n }\n}" } ] } }, "/events/{event_id}": { "get": { "operationId": "get_events", "summary": "Get a single event", "description": "Retrieves the details of a single event.", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The event id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/event_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.events.get(\"EV123\")" }, { "lang": "Python", "label": "Python", "source": "client.events.get(\"EV123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const event = await client.events.find(\"EV123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->events()->get(\"EV123\");" }, { "lang": "Java", "label": "Java", "source": "Event event = client.events().get(\"EV123\").execute();" }, { "lang": "Go", "label": "Go", "source": "event, err := client.Events.Get(ctx, \"EV123\")" }, { "lang": "C#", "label": ".NET", "source": "var eventResponse = await client.Events.GetAsync(\"EV0123\");\nGoCardless.Resources.Event eventResource = eventResponse.Event;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/events/EV123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"events\": {\n \"id\": \"EV123\",\n \"created_at\": \"2014-04-08T17:01:06.000Z\",\n \"resource_type\": \"payments\",\n \"action\": \"confirmed\",\n \"details\": {\n \"origin\": \"gocardless\",\n \"cause\": \"payment_confirmed\",\n \"description\": \"Payment confirmed\"\n },\n \"metadata\": {},\n \"resource_metadata\": { \"order_dispatch_date\": \"2014-05-22\" },\n \"links\": {\n \"payment\": \"PM123\"\n }\n }\n}" } ] } }, "/exports/{export_id}": { "get": { "operationId": "get_exports", "summary": "Get a single export", "description": "Returns a single export.\n\nRestricted: This endpoint is restricted to GoCardless Embed customers. Please [contact us](https://forms.gocardless.com/l/305971/2023-01-25/535t8n){:target=\"_blank\"} if you are interested in using this product.
", "tags": [ "Export" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The export id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/export_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.exports.get(\"EX123\")" }, { "lang": "Python", "label": "Python", "source": "client.exports.get(\"EX123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const exportData = await client.exports.find(\"EX123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->exports()->get('EX123');" }, { "lang": "Java", "label": "Java", "source": "Export export = client.exports().get(\"EX123\").execute();" }, { "lang": "Go", "label": "Go", "source": "export, err := client.Exports.Get(ctx, \"EX123\")" }, { "lang": "C#", "label": ".NET", "source": "var exportResponse = await client.Exports.GetAsync(\"EX123\");\nGoCardless.Resources.Export export = exportResponse.Export;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/exports/EX123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"exports\": {\n \"id\": \"EX123\",\n \"created_at\": \"2014-01-01T12:00:00.000Z\",\n \"export_type\": \"payout_transactions_reconciliation\",\n \"download_url\": \"https://downloads.gocardless.com/EX123/example.csv\",\n \"currency\": \"GBP\",\n \"error_message\": null\n }\n}" } ] } }, "/exports": { "get": { "operationId": "list_export", "summary": "List exports", "description": "Returns a list of exports which are available for download.\n\nRestricted: This endpoint is restricted to GoCardless Embed customers. Please [contact us](https://forms.gocardless.com/l/305971/2023-01-25/535t8n){:target=\"_blank\"} if you are interested in using this product.
", "tags": [ "Export" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/export_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.exports.list" }, { "lang": "Python", "label": "Python", "source": "client.exports.list().records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const exports = await client.exports.list();" }, { "lang": "PHP", "label": "PHP", "source": "$client->exports()->list();" }, { "lang": "Java", "label": "Java", "source": "for (Export export : client.exports().all().execute()) {\n System.out.println(export.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "exportListParams := gocardless.ExportListParams{}\nexportListResult, err := client.Exports.List(ctx, exportListParams)\nfor _, export := range exportListResult.Exports {\n fmt.Println(export.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var exportListResponse = client.Exports.All();\nforeach (GoCardless.Resources.Export export in exportListResponse)\n{\n Console.WriteLine(export.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/exports HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n\"exports\": [\n {\n \"id\": \"EX123\",\n \"created_at\": \"2014-01-01T12:00:00.000Z\",\n \"export_type\": \"payout_transactions_reconciliation\",\n \"currency\": \"GBP\"\n },\n {\n \"id\": \"EX456\",\n \"created_at\": \"2014-01-01T12:00:00.000Z\",\n \"export_type\": \"payout_transactions_reconciliation\",\n \"currency\": \"EUR\"\n }\n ]\n}" } ] } }, "/funds_availability/{mandate_id}": { "get": { "operationId": "get_funds_availability", "summary": "Funds availability", "description": "Checks if the payer's current balance is sufficient to cover the amount\nthe merchant wants to charge within the consent parameters defined on the mandate.\n\nWarning: Funds availability check is available for VRP mandates only.
", "tags": [ "Funds Availability" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "mandate_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The mandate id" }, { "name": "amount", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/funds_availability_amount" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "$ref": "#/components/schemas/funds_availability_available" } } } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.funds_availabilities.check(\"MD123\", params: { amount: \"1000\" })" }, { "lang": "Python", "label": "Python", "source": "client.funds_availabilities.check(\"MD123\", params={\"amount\": \"1000\"})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.fundsAvailabilities.check(\"MD123\", {\n amount: \"1000\"\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->fundsAvailabilities()->check(\"MD123\", [\n \"params\" => [\"amount\" => \"1000\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.fundsAvailabilities().check(\"MD123\")\n .withAmount(\"1000\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "fundsAvailabilityCheckParams := gocardless.FundsAvailabilityCheckParams{\n Amount: \"1000\",\n}\n\nfundsAvailability, err := client.FundsAvailabilities.Check(ctx, \"MD123\", fundsAvailabilityCheckParams)" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.FundsAvailabilityCheckRequest()\n{\n Amount = \"1000\"\n};\n\nvar resp = await client.FundsAvailabilities.CheckAsync(\"MD123\", request);" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/funds_availability/MD123?amount=1000 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"available\": true\n}" } ] } }, "/instalment_schedules/create_with_dates": { "post": { "operationId": "create_with_dates_instalment_schedules", "summary": "Create (with dates)", "description": "Creates a new instalment schedule object, along with the associated payments. This\nAPI is recommended if you know the specific dates you wish to charge. Otherwise,\nplease check out the [scheduling version](#instalment-schedules-create-with-schedule).\n\nThe `instalments` property is an array of payment properties (`amount` and\n`charge_date`).\n\nIt can take quite a while to create the associated payments, so the API will return\nthe status as `pending` initially. When processing has completed, a subsequent GET\nrequest for the instalment schedule will either have the status `success` and link\nto the created payments, or the status `error` and detailed information about the\nfailures.", "tags": [ "Instalment Schedule" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/instalment_schedule_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instalment_schedules": { "type": "object", "additionalProperties": false, "required": [ "total_amount", "currency", "links", "instalments", "name" ], "properties": { "name": { "$ref": "#/components/schemas/instalment_schedule_name" }, "total_amount": { "$ref": "#/components/schemas/instalment_schedule_total_amount_stringable" }, "currency": { "$ref": "#/components/schemas/instalment_schedule_currency" }, "app_fee": { "$ref": "#/components/schemas/subscription_app_fee_stringable" }, "payment_reference": { "$ref": "#/components/schemas/instalment_schedule_payment_reference" }, "retry_if_possible": { "$ref": "#/components/schemas/instalment_schedule_retry_if_possible" }, "instalments": { "type": "array", "description": "An explicit array of instalment payments, each specifying at least an `amount` and `charge_date`. See [create (with dates)](#instalment-schedules-create-with-dates)", "example": [ { "amount": 250, "charge_date": "2020-11-03" } ], "items": { "type": "object", "additionalProperties": false, "required": [ "charge_date", "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/payment_amount_stringable" }, "charge_date": { "$ref": "#/components/schemas/instalment_schedule_charge_date" }, "description": { "$ref": "#/components/schemas/payment_description" } } } }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "links": { "type": "object", "additionalProperties": false, "required": [ "mandate" ], "properties": { "mandate": { "$ref": "#/components/schemas/instalment_schedule_mandate" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "instalment_schedule = @client.instalment_schedules.create_with_dates(\n params: {\n name: \"ACME Invoice 103\",\n total_amount: 10_000, # 100 GBP in pence, collected from the customer\n app_fee: 10, # Your 10 pence fee, applied to each instalment,\n # to be paid out to you\n currency: 'GBP',\n instalments: [\n {\n charge_date: '2019-08-20',\n amount: 3_400\n },\n {\n charge_date: '2019-09-03',\n amount: 3_400\n },\n {\n charge_date: '2019-09-17',\n amount: 3_200\n },\n ],\n links: {\n mandate: 'MD0000XH9A3T4C'\n },\n metadata: {}\n },\n headers: {\n 'Idempotency-Key': 'random_instalment_schedule_specific_string'\n }\n)" }, { "lang": "Python", "label": "Python", "source": "instalment_schedule = client.instalment_schedules.create_with_dates(\n params={\n \"name\": \"ACME Invoice 103\",\n \"total_amount\": 10000, # 100 GBP in pence, collected from the customer\n \"app_fee\": 10, # Your 10 pence fee, applied to each instalment,\n # to be paid out to you\n \"currency\": 'GBP',\n \"instalments\": [\n {\n \"charge_date\": '2019-08-20',\n \"amount\": 3400\n },\n {\n \"charge_date\": '2019-09-03',\n \"amount\": 3400\n },\n {\n \"charge_date\": '2019-09-17',\n \"amount\": 3200\n },\n ],\n \"links\": {\n \"mandate\": 'MD0000XH9A3T4C'\n },\n \"metadata\": {}\n }, headers={\n 'Idempotency-Key': 'random_instalment_schedule_specific_string'\n }\n)" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const instalmentSchedule = await client.instalmentSchedules.createWithDates(\n {\n name: \"ACME Invoice 103\",\n total_amount: 10000, // 100 GBP in pence\n app_fee: 10, // Your 10 pence fee per instalment\n currency: 'GBP',\n instalments: [\n {\n charge_date: '2019-08-20',\n amount: 3400\n },\n {\n charge_date: '2019-09-03',\n amount: 3400\n },\n {\n charge_date: '2019-09-17',\n amount: 3200\n }\n ],\n links: {\n mandate: 'MD0000XH9A3T4C'\n },\n metadata: {}\n },\n \"instalment_schedule_idempotency_key\"\n);" }, { "lang": "PHP", "label": "PHP", "source": "$instalment_schedule = $client->instalmentSchedules()->createWithDates([\n \"params\" => [\n \"name\" => \"ACME Invoice 103\",\n \"total_amount\" => 10000, // 100 GBP in pence, collected from the customer\n \"app_fee\" => 10, // Your 10 pence fee, applied to each instalment,\n // to be paid out to you\n \"currency\" => 'GBP',\n \"instalments\" => [\n [\n \"charge_date\" => '2019-08-20',\n \"amount\" => 3400\n ],\n [\n \"charge_date\" => '2019-09-03',\n \"amount\" => 3400\n ],\n [\n \"charge_date\" => '2019-09-17',\n \"amount\" => 3200\n ],\n ],\n \"links\" => [\n \"mandate\" => 'MD0000XH9A3T4C'\n ],\n \"metadata\" => []\n ],\n \"headers\" => [\n 'Idempotency-Key' => 'random_instalment_schedule_specific_string'\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.InstalmentScheduleService.InstalmentScheduleCreateWithDatesRequest.Currency;\nimport com.gocardless.services.InstalmentScheduleService.InstalmentScheduleCreateWithDatesRequest.Instalments;\nimport java.util.Arrays;\n\nInstalmentSchedule instalmentSchedule = client.instalmentSchedules().createWithDates()\n .withTotalAmount(10000) // 100 GBP in Pence, collected from the end customer.\n .withAppFee(10) // Your 10 pence fee, applied to each instalment, to be\n // paid out to you\n .withCurrency(Currency.GBP)\n .withInstalments(Arrays.asList(\n new Instalments().withAmount(3400).withChargeDate(\"2019-08-20\"),\n new Instalments().withAmount(3400).withChargeDate(\"2019-09-03\"),\n new Instalments().withAmount(3200).withChargeDate(\"2019-09-17\")\n ))\n .withLinksMandate(\"MD0000YTKZKY4J\")\n .withMetadata(\"invoiceId\", \"001\")\n .withIdempotencyKey(\"random_instalment_schedule_specific_string\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "instalmentScheduleCreateWithDatesParams := gocardless.InstalmentScheduleCreateWithDatesParams{\n TotalAmount: 10000,\n AppFee: 10,\n Currency: \"GBP\",\n Instalments: []gocardless.InstalmentScheduleCreateWithDatesParamsInstalments{\n {\n Amount: 3400,\n ChargeDate: \"2019-08-20\",\n },\n {\n Amount: 3400,\n ChargeDate: \"2019-09-03\",\n },\n {\n Amount: 3400,\n ChargeDate: \"2019-09-17\",\n },\n },\n Links: gocardless.InstalmentScheduleCreateWithDatesParamsLinks{\n Mandate: \"MD123\",\n },\n Metadata: map[string]string{\"invoiceId\": \"001\"},\n}\n\nrequestOption := gocardless.WithIdempotencyKey(\"random_instalment_schedule_specific_string\")\ninstalmentSchedule, err := client.InstalmentSchedules.CreateWithDates(ctx, instalmentScheduleCreateWithDatesParams, requestOption)" }, { "lang": "C#", "label": ".NET", "source": "using GoCardless.Services;\nusing System.Collections.Generic;\n\nvar createResponse = await client.InstalmentSchedules.CreateWithDatesAsync(\n new InstalmentScheduleCreateWithDatesRequest\n {\n TotalAmount = 10000, // 100 GBP in pence, collected from the customer\n AppFee = 10, // Your 10 pence fee, applied to each instalment,\n // to be paid out to you\n Currency = InstalmentScheduleCreateWithDatesRequest.InstalmentScheduleCurrency.GBP,\n Name = \"ACME Invoice 103\",\n Instalments = new InstalmentScheduleCreateWithDatesRequest.InstalmentScheduleInstalments[]\n {\n new InstalmentScheduleCreateWithDatesRequest.InstalmentScheduleInstalments\n {\n ChargeDate = \"2019-08-20\",\n Amount = 3400,\n },\n new InstalmentScheduleCreateWithDatesRequest.InstalmentScheduleInstalments\n {\n ChargeDate = \"2019-09-03\",\n Amount = 3400\n },\n new InstalmentScheduleCreateWithDatesRequest.InstalmentScheduleInstalments\n {\n ChargeDate = \"2019-09-17\",\n Amount = 3200\n },\n },\n Links = new InstalmentScheduleCreateWithDatesRequest.InstalmentScheduleLinks\n {\n Mandate = \"MD0000XH9A3T4C\"\n },\n Metadata = new DictionaryRestricted: this endpoint is restricted to [GoCardless Pro](https://gocardless.com/pricing) and [GoCardless Enterprise](https://gocardless.com/pricing) accounts with the [custom payment pages upgrade](https://hub.gocardless.com/s/article/Custom-payment-pages).
", "tags": [ "Institution" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "billing_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The billing request id" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "example": "monzo" }, "description": "A search substring for retrieving institution(s), based on the institution's name." }, { "name": "ids", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "example": "monzo,revolut,barclays" }, "description": "ID(s) of the institution(s) to retrieve. More than one ID can be specified using a comma-separated string." }, { "name": "country_code", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/institution_country_code" } }, { "name": "include_disabled", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "true", "false" ], "type": "string" }, { "type": "boolean" } ] }, "description": "Indicates whether to include temporarily disabled institutions in the response.\nIf not provided or set to false, only enabled institutions will be returned.\n" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "institutions": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/institution_id" }, "name": { "$ref": "#/components/schemas/institution_name" }, "icon_url": { "$ref": "#/components/schemas/institution_icon_url" }, "logo_url": { "$ref": "#/components/schemas/institution_logo_url" }, "country_code": { "$ref": "#/components/schemas/institution_country_code" }, "autocompletes_collect_bank_account": { "$ref": "#/components/schemas/institution_autocompletes_collect_bank_account" }, "status": { "$ref": "#/components/schemas/institution_status" } } } }, "meta": { "$ref": "#/components/schemas/institution_pagination_meta" } } } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.institutions.list_for_billing_request(\"BR123\", {\n params: { country_code: \"GB\" }\n})" }, { "lang": "Python", "label": "Python", "source": "client.institutions.list_for_billing_request(\"BR123\", params={\n \"country_code\": \"GB\"\n}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const institutions = await client.institutions.list_for_billing_request(\"BR123\", { country_code: 'GB'});" }, { "lang": "PHP", "label": "PHP", "source": "$client->institutions()->listForBillingRequest(\"BR123\", [\n \"params\" => [\"country_code\" => \"GB\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.institutions().listForBillingRequest(\"BR123\").withCountryCode(\"GB\").execute();" }, { "lang": "Go", "label": "Go", "source": "institutionListForBillingRequestParams := gocardless.InstitutionListForBillingRequestParams{\n CountryCode: \"GB\",\n}\ninstitutionListForBillingRequestResult, err := client.Institutions.ListForBillingRequest(ctx, \"BR123\", institutionListForBillingRequestParams)\nfor _, institution := range institutionListForBillingRequestResult.Institutions {\n fmt.Println(institution.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.InstitutionListForBillingRequestRequest()\n {\n CountryCode = \"GB\",\n };\n\nvar institutionListResponse = await client.Institutions.ListForBillingRequestAsync(\"BR123\", request);" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/billing_requests/BRQ123/institutions?country_code=GB&include_disabled=true HTTP/1.1\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"institutions\": [\n {\n \"id\": \"BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1\",\n \"name\": \"Bank of Scotland Business\",\n \"logo_url\": \"https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png\",\n \"icon_url\": \"https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png\",\n \"country_code\": \"GB\",\n \"autocompletes_collect_bank_account\": true,\n \"status\": \"enabled\"\n },\n {\n \"id\": \"BANK_OF_SCOTLAND_BOFSGBS1\",\n \"name\": \"Bank of Scotland Personal\",\n \"logo_url\": \"https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png\",\n \"icon_url\": \"https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png\",\n \"country_code\": \"GB\",\n \"autocompletes_collect_bank_account\": true,\n \"status\": \"temporarily_disabled\"\n }\n ]\n}" } ] } }, "/branding/logos": { "post": { "operationId": "logos_branding", "summary": "Create a logo associated with a creditor", "description": "Creates a new logo associated with a creditor. If a creditor already has a logo, this will update the existing logo linked to the creditor.\n\nWe support JPG and PNG formats. Your logo will be scaled to a maximum of 300px by 40px. For more guidance on how to upload logos that will look\ngreat across your customer payment page and notification emails see [here](https://developer.gocardless.com/gc-embed/setting-up-branding#tips_for_uploading_your_logo).\n\nRestricted: This endpoint is restricted to GoCardless Embed customers. Please [contact us](https://forms.gocardless.com/l/305971/2023-01-25/535t8n){:target=\"_blank\"} if you are interested in using this product.
", "tags": [ "Logo" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logo_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "logos": { "type": "object", "additionalProperties": false, "required": [ "image" ], "properties": { "image": { "type": "string", "description": "Base64 encoded string.", "example": "data:image/png;base64,Restricted: this endpoint requires approved [custom payment pages](https://support.gocardless.com/hc/en-gb/articles/115004521925-Custom-Payment-Pages).
\n\nNote: this endpoint is a legacy API endpoint and does not support GoCardless' newest features. We recommend using the [Billing Requests API](/billing-requests/overview) instead.
\n\nWarning: by default, the ability to provide a custom mandate reference is switched off. The banking system rules for valid references are quite complex, and we recommend allowing GoCardless to generate it. If you would like to provide custom references, please contact support.
", "tags": [ "Mandate" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mandates": { "type": "object", "additionalProperties": false, "required": [ "links" ], "properties": { "reference": { "$ref": "#/components/schemas/mandate_reference" }, "scheme": { "$ref": "#/components/schemas/mandate_scheme" }, "payer_ip_address": { "$ref": "#/components/schemas/mandate_payer_ip_address" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "authorisation_source": { "$ref": "#/components/schemas/mandate_authorisation_source" }, "links": { "type": "object", "description": "", "additionalProperties": false, "required": [ "customer_bank_account" ], "properties": { "customer_bank_account": { "type": "string", "description": "ID of the associated [customer bank account](#core-endpoints-customer-bank-accounts) which the mandate is created and submits payments against.", "example": "BA123" }, "creditor": { "type": "string", "description": "ID of the associated [creditor](#core-endpoints-creditors). Only required if your account manages multiple creditors.", "example": "CR123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandates.create(\n params: {\n scheme: \"bacs\",\n links: {\n customer_bank_account: \"BA123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.mandates.create(params={\n \"scheme\": \"bacs\",\n \"metadata\": {\n \"contract\": \"ABCD1234\"\n },\n \"links\": {\n \"customer_bank_account\": \"BA123\",\n \"creditor\": \"CR123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const mandate = await client.mandates.create({\n scheme: \"bacs\",\n metadata: {\n contract: \"ABCD1234\"\n },\n links: {\n customer_bank_account: \"BA123\",\n creditor: \"CR123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandates()->create([\n \"params\" => [\"scheme\" => \"bacs\",\n \"metadata\" => [\"contract\" => \"ABCD1234\"],\n \"links\" => [\"customer_bank_account\" => \"BA123\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "Mandate mandate = client.mandates().create()\n .withScheme(\"bacs\")\n .withLinksCustomerBankAccount(\"BA123\")\n .withMetadata(\"contract\", \"ABCD1234\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "mandateCreateParams := gocardless.MandateCreateParams{\n Scheme: \"bacs\",\n Links: gocardless.MandateCreateParamsLinks{\n CustomerBankAccount: \"BA123\",\n Creditor: \"CR123\",\n },\n Metadata: map[string]string{\"contract\": \"ABCD1234\"},\n}\n\nmandate, err := client.Mandates.Create(ctx, mandateCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var mandateRequest = new GoCardless.Services.MandateCreateRequest()\n{\n Links = new GoCardless.Services.MandateCreateRequest.MandateLinks()\n {\n CustomerBankAccount = \"BA0123\"\n },\n Metadata = new DictionaryRestricted: this endpoint requires approved\n[custom payment pages](https://support.gocardless.com/hc/en-gb/articles/115004521925-Custom-Payment-Pages). To instead use the GoCardless hosted payment pages,\nsee the [redirect flows](#core-endpoints-redirect-flows) endpoint.
\n\nWarning: A mandate can only be reinstated if it has been cancelled through the\ndashboard or the API. Any mandate that has been cancelled by the bank\ncannot be reinstated.
", "tags": [ "Mandate" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "mandate_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The mandate id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mandates": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandates.reinstate(\"MD123\")" }, { "lang": "Python", "label": "Python", "source": "client.mandates.reinstate(\"MD123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const mandateResponse = await client.mandates.reinstate(\"MD123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandates()->reinstate(\"MD123\");" }, { "lang": "Java", "label": "Java", "source": "client.mandates().reinstate(\"MD123\").execute();" }, { "lang": "Go", "label": "Go", "source": "mandateReinstateParams := gocardless.MandateReinstateParams{}\nmandate, err := client.Mandates.Reinstate(ctx, \"MD123\", mandateReinstateParams)" }, { "lang": "C#", "label": ".NET", "source": "var mandateResponse = await client.Mandates.ReinstateAsync(\"MD0123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/mandates/MD123/actions/reinstate HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"metadata\": {\n \"ticket_id\": \"TK123\"\n }\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandates\": {\n \"id\": \"MD123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"reference\": \"REF-123\",\n \"status\": \"submitted\",\n \"scheme\": \"bacs\",\n \"next_possible_charge_date\": \"2014-11-10\",\n \"metadata\": {\n \"contract\": \"ABCD1234\"\n },\n \"links\": {\n \"customer_bank_account\": \"BA123\",\n \"creditor\": \"CR123\",\n \"customer\": \"CU123\"\n }\n }\n}" } ] } }, "/mandate_imports": { "post": { "operationId": "create_mandate_import", "summary": "Create a new mandate import", "description": "Mandate imports are first created, before mandates are added one-at-a-time, so\nthis endpoint merely signals the start of the import process. Once you've finished\nadding entries to an import, you should\n[submit](#mandate-imports-submit-a-mandate-import) it.", "tags": [ "Mandate Import" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_import_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mandate_imports": { "type": "object", "additionalProperties": false, "required": [ "scheme" ], "properties": { "scheme": { "description": "A bank payment scheme. Currently \"ach\", \"autogiro\", \"bacs\", \"becs\", \"becs_nz\", \"betalingsservice\", \"faster_payments\", \"pad\", \"pay_to\" and \"sepa_core\" are supported.", "example": "bacs", "enum": [ "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core" ], "type": "string" }, "links": { "type": "object", "description": "Related resources", "properties": { "creditor": { "type": "string", "description": "ID of the associated creditor. Only required if your account manages multiple creditors.", "example": "CR123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandate_imports.create(params: {\n scheme: \"bacs\"\n})" }, { "lang": "Python", "label": "Python", "source": "client.mandate_imports.create(params={\n \"scheme\": \"bacs\"\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const mandateImport = await client.mandateImports.create({\n scheme: \"bacs\"\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandateImports()->create([\n \"params\" => [\"scheme\" => \"bacs\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "MandateImport mandateImport = client.mandateImports().create()\n .withScheme(com.gocardless.services.MandateImportService.MandateImportCreateRequest.Scheme.BACS)\n .execute();" }, { "lang": "Go", "label": "Go", "source": "mandateImportCreateParams := gocardless.MandateImportCreateParams{\n Scheme: \"bacs\",\n}\n\nmandateImport, err := client.MandateImports.Create(ctx, mandateImportCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var importRequest = new GoCardless.Services.MandateImportCreateRequest()\n{\n Scheme = GoCardless.Services.MandateImportCreateRequest.MandateImportScheme.Bacs\n};\n\nvar importResponse = await client.MandateImports.CreateAsync(importRequest);\nGoCardless.Resources.MandateImport mandateImport = importResponse.MandateImport;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/mandate_imports HTTP/1.1\nContent-Type: application/json\n{\n \"mandate_imports\": {\n \"scheme\": \"bacs\"\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /mandate_imports/IM123\nContent-Type: application/json\n{\n \"mandate_imports\": {\n \"id\": \"IM123\",\n \"scheme\": \"bacs\",\n \"status\": \"created\",\n \"created_at\": \"2018-03-12T14:03:04.000Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}" } ] } }, "/mandate_imports/{mandate_import_id}": { "get": { "operationId": "get_mandate_imports", "summary": "Get a mandate import", "description": "Returns a single mandate import.", "tags": [ "Mandate Import" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "mandate_import_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The mandate import id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_import_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandate_imports.get(\"IM123\")" }, { "lang": "Python", "label": "Python", "source": "client.mandate_imports.get(\"IM123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const mandateImport = await client.mandateImports.find(\"IM123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandateImports()->get(\"IM123\");" }, { "lang": "Java", "label": "Java", "source": "MandateImport mandateImport = client.mandateImports().get(\"IM123\").execute();" }, { "lang": "Go", "label": "Go", "source": "mandateImport, err := client.MandateImports.Get(ctx, \"IM123\", gocardless.MandateImportGetParams{})" }, { "lang": "C#", "label": ".NET", "source": "var response = await client.MandateImports.GetAsync(\"IM123\");\nGoCardless.Resources.MandateImport mandateImport = response.MandateImport;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/mandate_imports/IM123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandate_imports\": {\n \"id\": \"IM123\",\n \"scheme\": \"bacs\",\n \"status\": \"created\",\n \"created_at\": \"2018-03-12T14:03:04.000Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}" } ] } }, "/mandate_imports/{mandate_import_id}/actions/submit": { "post": { "operationId": "submit_mandate_import", "summary": "Submit a mandate import", "description": "Submits the mandate import, which allows it to be processed by a member of the\nGoCardless team. Once the import has been submitted, it can no longer have entries\nadded to it.\n\nIn our sandbox environment, to aid development, we automatically process mandate\nimports approximately 10 seconds after they are submitted. This will allow you to\ntest both the \"submitted\" response and wait for the webhook to confirm the\nprocessing has begun.", "tags": [ "Mandate Import" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "mandate_import_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The mandate import id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_import_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mandate_imports": { "type": "object", "additionalProperties": false } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandate_imports.submit(\"IM123\")" }, { "lang": "Python", "label": "Python", "source": "client.mandate_imports.submit(\"IM123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const mandateImport = await client.mandateImports.submit(\"IM123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandateImports()->submit(\"IM123\");" }, { "lang": "Java", "label": "Java", "source": "client.mandateImports().submit(\"IM123\").execute();" }, { "lang": "Go", "label": "Go", "source": "mandateImportSubmitParams := gocardless.MandateImportSubmitParams{}\nmandateImport, err := client.MandateImports.Submit(ctx, \"IM123\", mandateImportSubmitParams)" }, { "lang": "C#", "label": ".NET", "source": "var response = await client.MandateImports.SubmitAsync(\"IM123\");\nGoCardless.Resources.MandateImport mandateImport = response.MandateImport;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/mandate_imports/IM123/actions/submit HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandate_imports\": {\n \"id\": \"IM123\",\n \"scheme\": \"bacs\",\n \"status\": \"submitted\",\n \"created_at\": \"2018-03-12T14:03:04.000Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}\n\nPOST https://api-sandbox.gocardless.com/mandate_imports/IM123/actions/submit HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandate_imports\": {\n \"id\": \"IM123\",\n \"scheme\": \"bacs\",\n \"status\": \"processing\",\n \"created_at\": \"2018-03-12T14:03:04.000Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}" } ] } }, "/mandate_imports/{mandate_import_id}/actions/cancel": { "post": { "operationId": "cancel_mandate_import", "summary": "Cancel a mandate import", "description": "Cancels the mandate import, which aborts the import process and stops the mandates\nbeing set up in GoCardless. Once the import has been cancelled, it can no longer have\nentries added to it. Mandate imports which have already been submitted or processed\ncannot be cancelled.", "tags": [ "Mandate Import" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "mandate_import_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The mandate import id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_import_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mandate_imports": { "type": "object", "additionalProperties": false } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandate_imports.cancel(\"IM123\")" }, { "lang": "Python", "label": "Python", "source": "client.mandate_imports.cancel(\"IM123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const mandateImportResponse = await client.mandateImports.cancel(\"IM123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandateImports()->cancel(\"IM123\");" }, { "lang": "Java", "label": "Java", "source": "client.mandateImports().cancel(\"IM123\").execute();" }, { "lang": "Go", "label": "Go", "source": "mandateImportCancelParams := gocardless.MandateImportCancelParams{}\nmandateImport, err := client.MandateImports.Cancel(ctx, \"IM123\", mandateImportCancelParams)" }, { "lang": "C#", "label": ".NET", "source": "var response = await client.MandateImports.CancelAsync(\"IM123\");\nGoCardless.Resources.MandateImport mandateImport = response.MandateImport;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/mandate_imports/IM123/actions/cancel HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandate_imports\": {\n \"id\": \"IM123\",\n \"scheme\": \"bacs\",\n \"status\": \"cancelled\",\n \"created_at\": \"2018-03-12T14:03:04.000Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}" } ] } }, "/mandate_import_entries": { "post": { "operationId": "create_mandate_import_entry", "summary": "Add a mandate import entry", "description": "For an existing [mandate import](#core-endpoints-mandate-imports), this endpoint can\nbe used to add individual mandates to be imported into GoCardless.\n\nYou can add no more than 30,000 rows to a single mandate import.\nIf you attempt to go over this limit, the API will return a `record_limit_exceeded` error.", "tags": [ "Mandate Import Entry" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_import_entry_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mandate_import_entries": { "type": "object", "additionalProperties": false, "required": [ "links", "customer", "bank_account" ], "properties": { "links": { "type": "object", "additionalProperties": false, "required": [ "mandate_import" ], "properties": { "mandate_import": { "$ref": "#/components/schemas/mandate_import_identity" } } }, "record_identifier": { "$ref": "#/components/schemas/mandate_import_entry_record_identifier" }, "mandate": { "type": "object", "additionalProperties": false, "properties": { "reference": { "$ref": "#/components/schemas/mandate_reference" }, "authorisation_source": { "$ref": "#/components/schemas/mandate_authorisation_source" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } }, "customer": { "type": "object", "description": "", "additionalProperties": false, "properties": { "given_name": { "$ref": "#/components/schemas/customer_given_name" }, "family_name": { "$ref": "#/components/schemas/customer_family_name" }, "company_name": { "$ref": "#/components/schemas/customer_company_name" }, "email": { "$ref": "#/components/schemas/customer_email" }, "language": { "$ref": "#/components/schemas/customer_language" }, "address_line1": { "type": "string", "description": "The first line of the customer's address. Required if mandate import scheme is either `bacs` or `sepa`.\n" }, "address_line2": { "$ref": "#/components/schemas/customer_address_line2" }, "address_line3": { "$ref": "#/components/schemas/customer_address_line3" }, "city": { "$ref": "#/components/schemas/customer_city" }, "region": { "$ref": "#/components/schemas/customer_region" }, "postal_code": { "type": "string", "description": "The customer's postal code. Required if mandate import scheme is either `bacs` or `sepa`.\n" }, "country_code": { "$ref": "#/components/schemas/customer_country_code" }, "phone_number": { "$ref": "#/components/schemas/customer_phone_number" }, "swedish_identity_number": { "$ref": "#/components/schemas/customer_swedish_identity_number" }, "danish_identity_number": { "$ref": "#/components/schemas/customer_danish_identity_number" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } }, "bank_account": { "type": "object", "description": "", "additionalProperties": false, "required": [ "account_holder_name" ], "properties": { "account_holder_name": { "$ref": "#/components/schemas/customer_bank_account_account_holder_name" }, "account_number": { "$ref": "#/components/schemas/customer_bank_account_account_number" }, "bank_code": { "$ref": "#/components/schemas/customer_bank_account_bank_code" }, "branch_code": { "$ref": "#/components/schemas/customer_bank_account_branch_code" }, "country_code": { "$ref": "#/components/schemas/customer_bank_account_country_code" }, "iban": { "$ref": "#/components/schemas/customer_bank_account_iban" }, "account_type": { "$ref": "#/components/schemas/customer_bank_account_account_type" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } }, "amendment": { "type": "object", "description": "", "additionalProperties": false, "required": [ "original_mandate_reference", "original_creditor_id", "original_creditor_name" ], "properties": { "original_mandate_reference": { "type": "string", "description": "The unique SEPA reference for the mandate being amended. Required if mandate\nimport scheme is `sepa`.\n", "example": "REFNMANDATE" }, "original_creditor_id": { "type": "string", "description": "The creditor identifier of the direct debit originator. Required if mandate\nimport scheme is `sepa`.\n", "example": "FR123OTHERBANK" }, "original_creditor_name": { "type": "string", "description": "Data about the original mandate to be moved or modified.\n", "example": "Existing DD Provider" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandate_import_entries.create(params: {\n links: {\n mandate_import: \"IM000010790WX1\"\n },\n record_identifier: \"bank-file.xml/line-1\",\n customer: {\n company_name: \"Jane's widgets\",\n email: \"jane@janeswidgets.fr\"\n },\n bank_account: {\n account_holder_name: \"Jane Doe\",\n iban: \"FR14BARC20000055779911\"\n },\n amendment: {\n original_mandate_reference: \"REFNMANDATE\",\n original_creditor_id: \"FR123OTHERBANK\",\n original_creditor_name: \"Existing DD Provider\"\n }\n})" }, { "lang": "Python", "label": "Python", "source": "client.mandate_import_entries.create(params={\n \"links\": {\n \"mandate_import\": \"IM000010790WX1\"\n },\n \"record_identifier\": \"bank-file.xml/line-1\",\n \"customer\": {\n \"company_name\": \"Jane's widgets\",\n \"email\": \"jane@janeswidgets.fr\"\n },\n \"bank_account\": {\n \"account_holder_name\": \"Jane Doe\",\n \"iban\": \"FR14BARC20000055779911\"\n },\n \"amendment\": {\n \"original_mandate_reference\": \"REFNMANDATE\",\n \"original_creditor_id\": \"FR123OTHERBANK\",\n \"original_creditor_name\": \"Existing DD Provider\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const mandateImportEntry = await client.mandateImportEntries.create({\n links: {\n mandate_import: \"IM000010790WX1\"\n },\n record_identifier: \"bank-file.xml/line-1\",\n customer: {\n company_name: \"Jane's widgets\",\n email: \"jane@janeswidgets.fr\"\n },\n bank_account: {\n account_holder_name: \"Jane Doe\",\n iban: \"FR14BARC20000055779911\"\n },\n amendment: {\n original_mandate_reference: \"REFNMANDATE\",\n original_creditor_id: \"FR123OTHERBANK\",\n original_creditor_name: \"Existing DD Provider\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandateImportEntries()->create([\n \"params\" => [\n \"links\" => [\n \"mandate_import\" => \"IM000010790WX1\"\n ],\n \"record_identifier\" => \"bank-file.xml/line-1\",\n \"customer\" => [\n \"company_name\" => \"Jane's widgets\",\n \"email\" => \"jane@janeswidgets.fr\"\n ],\n \"bank_account\" => [\n \"account_holder_name\" => \"Jane Doe\",\n \"iban\" => \"FR14BARC20000055779911\"\n ],\n \"amendment\" => [\n \"original_mandate_reference\" => \"REFNMANDATE\",\n \"original_creditor_id\" => \"FR123OTHERBANK\",\n \"original_creditor_name\" => \"Existing DD Provider\"\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "MandateImportEntry mandateImportEntry = client.mandateImportEntries().create()\n .withCustomerCompanyName(\"Jane's widgets\")\n .withCustomerEmail(\"jane@janeswidgets.fr\")\n .withBankAccountAccountHolderName(\"Jane Doe\")\n .withBankAccountIban(\"FR14BARC20000055779911\")\n .withAmendmentOriginalMandateReference(\"REFNMANDATE\")\n .withAmendmentOriginalCreditorId(\"FR123OTHERBANK\")\n .withAmendmentOriginalCreditorName(\"Existing DD Provider\")\n .withLinksMandateImport(\"IM000010790WX1\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "mandateImportEntryCreateParams := gocardless.MandateImportEntryCreateParams{\n Customer: gocardless.MandateImportEntryCreateParamsCustomer{\n CompanyName: \"Théâtre du Palais-Royal\",\n Email: \"moliere@tdpr.fr\",\n },\n BankAccount: gocardless.MandateImportEntryCreateParamsBankAccount{\n AccountHolderName: \"Jean-Baptiste Poquelin\",\n Iban: \"FR14BARC20000055779911\",\n },\n Amendment: &gocardless.MandateImportEntryCreateParamsAmendment{\n OriginalMandateReference: \"REFMANDATE\",\n OriginalCreditorId: \"FR123OTHERBANK\",\n OriginalCreditorName: \"Amphitryon\",\n },\n Links: gocardless.MandateImportEntryCreateParamsLinks{\n MandateImport: \"IM000010790WX1\",\n },\n}\n\nmandateImportEntry, err := client.MandateImportEntries.Create(ctx, mandateImportEntryCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.MandateImportEntryCreateRequest()\n{\n Customer = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryCustomer()\n {\n CompanyName = \"Jane's widgets\",\n Email = \"jane@janeswidgets.fr\"\n },\n BankAccount = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryBankAccount()\n {\n AccountHolderName = \"Jane Doe\",\n Iban = \"FR14BARC20000055779911\"\n },\n Amendment = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryAmendment()\n {\n OriginalMandateReference = \"REFNMANDATE\",\n OriginalCreditorId = \"FR123OTHERBANK\",\n OriginalCreditorName = \"Existing DD Provider\"\n },\n Links = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryLinks()\n {\n MandateImport = \"IM000010790WX1\"\n }\n};\n\nvar importResponse = await client.MandateImportEntries.CreateAsync(request);\nGoCardless.Resources.MandateImportEntry entry = importResponse.MandateImportEntry;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/mandate_import_entries HTTP/1.1\nContent-Type: application/json\n{\n \"mandate_import_entries\": {\n \"links\": {\n \"mandate_import\": \"IM000010790WX1\"\n },\n \"record_identifier\": \"bank-file.xml/line-1\",\n \"customer\": {\n \"company_name\": \"Jane's widgets\",\n \"email\": \"jane@janeswidgets.fr\"\n },\n \"bank_account\": {\n \"account_holder_name\": \"Jane Doe\",\n \"iban\": \"FR14BARC20000055779911\"\n },\n \"amendment\": {\n \"original_mandate_reference\": \"REFNMANDATE\",\n \"original_creditor_id\": \"FR123OTHERBANK\",\n \"original_creditor_name\": \"Existing DD Provider\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nContent-Type: application/json\n{\n \"mandate_import_entries\": {\n \"record_identifier\": \"bank-file.xml/line-1\",\n \"created_at\": \"2018-03-03T00:00:00Z\",\n \"links\": {\n \"mandate_import\": \"IM000010790WX1\"\n }\n }\n}" } ] }, "get": { "operationId": "list_mandate_import_entry", "summary": "List all mandate import entries", "description": "For an existing mandate import, this endpoint lists all of the entries attached.\n\nAfter a mandate import has been submitted, you can use this endpoint to associate records\nin your system (using the `record_identifier` that you provided when creating the\nmandate import).\n", "tags": [ "Mandate Import Entry" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "mandate_import", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/mandate_import_identity" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/mandate_import_entry_status" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_import_entry_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandate_import_entries.all(\n params: {\n \"mandate_import\" => \"IM000010790WX1\"\n }\n).each { |entry| puts entry.record_identifier }" }, { "lang": "Python", "label": "Python", "source": "for mandate_import_entry in client.mandate_import_entries.all(\n params= { \"mandate_import\": \"IM000010790WX1\" }\n):\n print(mandate_import_entry.record_identifier)" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const mandateImportEntries = await client.mandateImportEntries.list();" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandateImportEntries()->all([\n \"params\" => [\"mandate_import\" => \"IM000010790WX1\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "for (MandateImportEntry entry : client.mandateImportEntries().all().withMandateImport(\"IM000010790WX1\").execute()) {\n System.out.println(entry.getRecordIdentifier());\n}" }, { "lang": "Go", "label": "Go", "source": "mandateImportEntryListParams := gocardless.MandateImportEntryListParams{\n MandateImport: \"IM000010790WX1\",\n}\n\nmandateImportEntryListPagingIterator := client.MandateImportEntries.All(ctx, mandateImportEntryListParams)\nfor mandateImportEntryListPagingIterator.Next() {\n mandateImportEntryListResult, err := mandateImportEntryListPagingIterator.Value(ctx)\n for _, mandateImportEntry := range mandateImportEntryListResult.MandateImportEntries {\n fmt.Println(mandateImportEntry.RecordIdentifier)\n }\n}" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.MandateImportEntryListRequest()\n{\n MandateImport = \"IM000010790WX1\"\n};\n\nvar response = client.MandateImportEntries.All(request);\nforeach (GoCardless.Resources.MandateImportEntry entry in response)\n{\n Console.WriteLine(entry.RecordIdentifier);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/mandate_import_entries?mandate_import=IM000010790WX1 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandate_import_entries\": [\n {\n \"record_identifier\": \"bank-file.xml/line-2\",\n \"created_at\": \"2018-03-03T00:00:01Z\",\n \"links\": {\n \"mandate_import\": \"IM000010790WX1\"\n },\n \"processing_errors\": null\n },\n {\n \"record_identifier\": \"bank-file.xml/line-1\",\n \"created_at\": \"2018-03-03T00:00:00Z\",\n \"links\": {\n \"mandate_import\": \"IM000010790WX1\"\n },\n \"processing_errors\": {\n \"mandate\": [\"Reference matches the start of the reference used by another mandate\"]\n }\n }\n ],\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n }\n}" } ] } }, "/mandate_pdfs": { "post": { "operationId": "create_mandate_pdf", "summary": "Create a mandate PDF", "description": "Generates a PDF mandate and returns its temporary URL.\n\nCustomer and bank account details can be left blank (for a blank mandate), provided manually, or inferred from the ID of an existing [mandate](#core-endpoints-mandates).\n\nBy default, we'll generate PDF mandates in English.\n\nTo generate a PDF mandate in another language, set the `Accept-Language` header when creating the PDF mandate to the relevant [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code supported for the scheme.\n\n| Scheme | Supported languages |\n| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |\n| ACH | English (`en`) |\n| Autogiro | English (`en`), Swedish (`sv`) |\n| Bacs | English (`en`) |\n| BECS | English (`en`) |\n| BECS NZ | English (`en`) |\n| Betalingsservice | Danish (`da`), English (`en`) |\n| PAD | English (`en`) |\n| SEPA Core | Danish (`da`), Dutch (`nl`), English (`en`), French (`fr`), German (`de`), Italian (`it`), Portuguese (`pt`), Spanish (`es`), Swedish (`sv`) |", "tags": [ "Mandate Pdf" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mandate_pdf_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mandate_pdfs": { "type": "object", "additionalProperties": false, "properties": { "scheme": { "$ref": "#/components/schemas/mandate_pdf_scheme" }, "country_code": { "$ref": "#/components/schemas/mandate_pdf_country_code" }, "iban": { "$ref": "#/components/schemas/mandate_pdf_iban" }, "bic": { "$ref": "#/components/schemas/mandate_pdf_bic" }, "account_number": { "$ref": "#/components/schemas/mandate_pdf_account_number" }, "bank_code": { "$ref": "#/components/schemas/mandate_pdf_bank_code" }, "branch_code": { "$ref": "#/components/schemas/mandate_pdf_branch_code" }, "account_holder_name": { "$ref": "#/components/schemas/mandate_pdf_account_holder_name" }, "given_name": { "$ref": "#/components/schemas/mandate_pdf_given_name" }, "family_name": { "$ref": "#/components/schemas/mandate_pdf_family_name" }, "company_name": { "$ref": "#/components/schemas/mandate_pdf_company_name" }, "mandate_reference": { "$ref": "#/components/schemas/mandate_pdf_mandate_reference" }, "signature_date": { "$ref": "#/components/schemas/mandate_pdf_signature_date" }, "phone_number": { "$ref": "#/components/schemas/mandate_pdf_phone_number" }, "swedish_identity_number": { "$ref": "#/components/schemas/mandate_pdf_swedish_identity_number" }, "danish_identity_number": { "$ref": "#/components/schemas/mandate_pdf_danish_identity_number" }, "address_line1": { "$ref": "#/components/schemas/customer_address_line1" }, "address_line2": { "$ref": "#/components/schemas/customer_address_line2" }, "address_line3": { "$ref": "#/components/schemas/customer_address_line3" }, "city": { "$ref": "#/components/schemas/customer_city" }, "region": { "$ref": "#/components/schemas/customer_region" }, "postal_code": { "$ref": "#/components/schemas/customer_postal_code" }, "account_type": { "$ref": "#/components/schemas/mandate_pdf_account_type" }, "payer_ip_address": { "$ref": "#/components/schemas/mandate_pdf_payer_ip_address" }, "subscription_amount": { "$ref": "#/components/schemas/mandate_pdf_subscription_amount" }, "subscription_frequency": { "$ref": "#/components/schemas/mandate_pdf_subscription_frequency" }, "links": { "type": "object", "description": "", "additionalProperties": false, "properties": { "mandate": { "type": "string", "description": "ID of an existing [mandate](#core-endpoints-mandates) to build the PDF from. The customer's bank details will be censored in the generated PDF. No other parameters may be provided alongside this." }, "creditor": { "type": "string", "description": "ID of an existing [creditor](#core-endpoints-creditors). Only required if your account manages multiple creditors." } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.mandate_pdfs.create(\n params: {\n links: { mandate: \"MD123\" }\n }\n)\n\n@client.mandate_pdfs.create(\n params: {\n account_number: \"55779911\",\n branch_code: \"200000\",\n country_code: \"GB\"\n }\n)\n\n@client.mandate_pdfs.create(\n params: {\n iban: \"FR14BARC20000055779911\",\n },\n headers: {\n \"Accept-Language\" => \"fr\"\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.mandate_pdfs.create(params={\n \"links\": {\"mandate\": \"MD123\"}\n})\n\nclient.mandate_pdfs.create(params={\n \"account_number\": \"44779911\",\n \"branch_code\": \"200000\",\n \"country_code\": \"GB\"\n})\n\nclient.mandate_pdfs.create(params={\n \"iban\": \"FR14BARC20000055779911\"\n}, headers={\n \"Accept-Language\": \"fr\"\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "await client.mandatePdfs.create({\n links: {\n mandate: \"MD123\"\n }\n});\n\nawait client.mandatePdfs.create(\n {\n links: {\n mandate: \"MD123\"\n }\n },\n \"mandate_pdfs_idempotency_key\"\n);\n\nawait client.mandatePdfs.create(\n {\n account_number: \"44779911\",\n branch_code: \"200000\",\n country_code: \"GB\"\n },\n \"\",\n { \"Accept-Language\": \"fr\" }\n);" }, { "lang": "PHP", "label": "PHP", "source": "$client->mandatePdfs()->create([\n \"params\" => [\"links\" => [\"mandate\" => \"MD123\"]]\n]);\n\n$client->mandatePdfs()->create([\n \"params\" => [\"account_number\" => \"44779911\",\n \"branch_code\" => \"200000\",\n \"country_code\" => \"GB\"]\n]);\n\n$client->mandatePdfs()->create([\n \"params\" => [\"iban\" => \"FR14BARC20000055779911\"],\n \"headers\" => ['accept-language' => 'fr']\n]);" }, { "lang": "Java", "label": "Java", "source": "MandatePdf mandatePdfForMandate = client.mandatePdfs().create()\n .withLinksMandate(\"MD123\")\n .execute();\n\nMandatePdf mandatePdfForBankDetails = client.mandatePdfs().create()\n .withAccountNumber(\"44779911\")\n .withBranchCode(\"200000\")\n .withCountryCode(\"GB\")\n .execute();\n\nMandatePdf mandatePdfInFrench = client.mandatePdfs().create()\n .withIban(\"FR14BARC20000055779911\")\n .withHeader(\"Accept-Language\", \"fr\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "mandatePdfCreateParams := gocardless.MandatePdfCreateParams{\n Links: &gocardless.MandatePdfCreateParamsLinks{\n Mandate: \"MD123\",\n },\n}\n\nmandatePdf, err := client.MandatePdfs.Create(ctx, mandatePdfCreateParams)\n\nrequestOption := gocardless.WithIdempotencyKey(\"mandate_pdfs_idempotency_key\")\nmandatePdf, err = client.MandatePdfs.Create(ctx, mandatePdfCreateParams, requestOption)\n\nheaders := map[string]string{\"Accept-Language\": \"fr\"}\nrequestOption = gocardless.WithHeaders(headers)\nmandatePdf, err = client.MandatePdfs.Create(ctx, mandatePdfCreateParams, requestOption)" }, { "lang": "C#", "label": ".NET", "source": "var mandatePdfForMandateRequest = new GoCardless.Services.MandatePdfCreateRequest()\n{\n Links = new GoCardless.Services.MandatePdfCreateRequest.MandatePdfLinks()\n {\n Mandate = \"MD123\"\n }\n};\n\nvar mandatePdfForMandateResponse = await client.MandatePdfs.CreateAsync(mandatePdfForMandateRequest);\nGoCardless.Resources.MandatePdf mandatePdfForMandate = mandatePdfForMandateResponse.MandatePdf;\n\nvar mandatePdfForBankDetailsRequest = new GoCardless.Services.MandatePdfCreateRequest()\n{\n AccountNumber = \"55779911\",\n BranchCode = \"200000\",\n CountryCode = \"GB\"\n};\n\nvar mandatePdfForBankDetailsResponse = await client.MandatePdfs.CreateAsync(mandatePdfForBankDetailsRequest);\nGoCardless.Resources.MandatePdf mandatePdfForBankDetails = mandatePdfForBankDetailsResponse.MandatePdf;\n\nvar mandatePdfWithIbanRequest = new GoCardless.Services.MandatePdfCreateRequest()\n{\n Iban = \"FR14BARC20000055779911\"\n};\n\nvar mandatePdfWithIbanResponse = await client.MandatePdfs.CreateAsync(mandatePdfWithIbanRequest);\nGoCardless.Resources.MandatePdf mandatePdfWithIban = mandatePdfWithIbanResponse.MandatePdf;\n\nvar requestSettings = new GoCardless.Internals.RequestSettings\n{\n CustomiseRequestMessage = (request) =>\n {\n request.Headers.Add(\"Accept-Language\", \"fr\");\n }\n};\n\nvar frenchMandatePdfRequest = new GoCardless.Services.MandatePdfCreateRequest();\nvar frenchMandatePdfResponse = await client.MandatePdfs.CreateAsync(frenchMandatePdfRequest, requestSettings);\nGoCardless.Resources.MandatePdf frenchMandatePdf = frenchMandatePdfResponse.MandatePdf;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/mandate_pdfs HTTP/1.1\nContent-Type: application/json\n{\n \"mandate_pdfs\": {\n \"links\": {\n \"mandate\": \"MD123\"\n }\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandate_pdfs\": {\n \"url\": \"https://mandate-previews.gocardless.com/?token=lhulxcPEbT9v3W0QUpBOxhlGUSYEayQQ4VVrpO7YnUKRYynP5\",\n \"expires_at\": \"2014-05-08T17:01:06.000Z\"\n }\n}\n\nPOST https://api.gocardless.com/mandate_pdfs HTTP/1.1\nContent-Type: application/json\n{\n \"mandate_pdfs\": {\n \"account_number\": \"44779911\",\n \"branch_code\": \"200000\",\n \"country_code\": \"GB\"\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandate_pdfs\": {\n \"url\": \"https://mandate-previews.gocardless.com/?token=vlaPBHzSvm1OPwDNatZYWJCM7XZcCUuLPn7m5XV5\",\n \"expires_at\": \"2014-05-08T17:01:06.000Z\"\n }\n}\n\nPOST https://api.gocardless.com/mandate_pdfs HTTP/1.1\nContent-Type: application/json\nAccept-Language: fr\n{\n \"mandate_pdfs\": {\n \"iban\": \"FR14BARC20000055779911\"\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"mandate_pdfs\": {\n \"url\": \"https://mandate-previews.gocardless.com/?token=vlaPBHzSvm1OPwDNatZYWJCM7XZcCUuLPn7m5XV5\",\n \"expires_at\": \"2014-05-08T17:01:06.000Z\"\n }\n}\n\nPOST https://api.gocardless.com/mandate_pdfs HTTP/1.1\nContent-Type: application/json\n{\n \"mandate_pdfs\": {\n \"account_number\": \"44779911\",\n \"branch_code\": \"200000\",\n \"country_code\": \"GB\",\n \"links\": {\n \"mandate\": \"MD123\"\n }\n }\n}\n\nHTTP/1.1 422 Unprocessable Entity\nContent-Type: application/json\n{\n \"error\": {\n \"message\": \"Cannot provide both a mandate and other details\",\n \"documentation_url\": \"https://developer.gocardless.com/api-reference#validation_failed\",\n \"type\": \"validation_failed\",\n \"request_id\": \"bd271b37-a2f5-47c8-b461-040dfe0e9cb1\",\n \"code\": 422,\n \"errors\": [\n {\n \"reason\": \"validation_failed\",\n \"message\": \"Cannot provide both a mandate and other details\"\n }\n ]\n }\n}" } ] } }, "/negative_balance_limits": { "get": { "operationId": "list_negative_balance_limit", "summary": "List negative balance limits", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of negative balance limits.\n\nRestricted: This endpoint is restricted to GoCardless Embed customers. Please [contact us](https://forms.gocardless.com/l/305971/2023-01-25/535t8n){:target=\"_blank\"} if you are interested in using this product.
", "tags": [ "Negative Balance Limit" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "currency", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/negative_balance_limit_currency" } }, { "name": "creditor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/creditor_identity" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/negative_balance_limit_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.negative_balance_limits.list(\n params: {\n currency: \"GBP\",\n creditor: \"CR123\",\n }\n).records" }, { "lang": "Python", "label": "Python", "source": "client.negative_balance_limits.list(params={\n \"currency\": \"GBP\",\n \"creditor\": \"CR123\",\n}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "await client.negativeBalanceLimits.list({\n currency: \"GBP\",\n creditor: \"CR123\",\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->negativeBalanceLimits()->list([\n \"params\" => [\n \"currency\" => \"GBP\",\n \"creditor\" => \"CR123\",\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.NegativeBalanceLimitService.NegativeBalanceLimitListRequest.Currency;\n\nclient.negativeBalanceLimits().\n all().\n withCreditor(\"CR123\").\n withCurrency(Currency.GBP).\n execute();" }, { "lang": "Go", "label": "Go", "source": "params := gocardless.NegativeBalanceLimitListParams{\n Currency: \"GBP\",\n Creditor: \"CR123\",\n}\n\nresponse, err := client.NegativeBalanceLimits.List(ctx, params)" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.NegativeBalanceLimitListRequest()\n{\n Currency = GoCardless.Services.NegativeBalanceLimitListRequest.NegativeBalanceLimitCurrency.GBP,\n Creditor = \"CR123\",\n};\n\nclient.NegativeBalanceLimits.All(request);" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/negative_balance_limits?currency=GBP&creditor=CR123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"negative_balance_limits\": [\n {\n \"id\": \"NBL123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"balance_limit\": 10000,\n \"currency\": \"GBP\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n ]\n}\n" } ] } }, "/outbound_payments": { "post": { "operationId": "create_outbound_payment", "summary": "Create an outbound payment", "description": "", "tags": [ "Outbound Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/outbound_payment_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outbound_payments": { "type": "object", "additionalProperties": false, "required": [ "amount", "scheme", "links" ], "properties": { "amount": { "$ref": "#/components/schemas/outbound_payment_amount" }, "scheme": { "$ref": "#/components/schemas/outbound_payment_scheme" }, "description": { "$ref": "#/components/schemas/outbound_payment_description" }, "execution_date": { "$ref": "#/components/schemas/outbound_payment_execution_date" }, "metadata": { "$ref": "#/components/schemas/outbound_payment_metadata" }, "reference": { "$ref": "#/components/schemas/outbound_payment_reference" }, "links": { "type": "object", "additionalProperties": false, "required": [ "recipient_bank_account" ], "properties": { "creditor": { "type": "string", "description": "ID of the creditor who sends the outbound payment.", "example": "CR123" }, "recipient_bank_account": { "type": "string", "description": "ID of the customer bank account which receives the outbound payment.", "example": "BA123" }, "outbound_payment_import": { "type": "string", "description": "ID of the outbound payment import that created this outbound payment.", "example": "IM123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.outbound_payments.create(\n params: {\n amount: 1000,\n scheme: \"faster_payments\",\n description: \"Reward Payment (August 2024)\",\n reference: \"Invoice 123\",\n links: {\n creditor: \"CR123\",\n recipient_bank_account: \"BA123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.outbound_payments.create(params={\n \"amount\": 1000,\n \"scheme\": \"faster_payments\",\n \"description\": \"Reward Payment (August 2024)\",\n \"reference\": \"Invoice 123\",\n \"links\": {\n \"creditor\": \"CR123\",\n \"recipient_bank_account\": \"BA123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const outboundPayment = await client.outboundPayments.create({\n amount: 1000,\n scheme: \"faster_payments\",\n description: \"Reward Payment (August 2024)\",\n reference: \"Invoice 123\",\n links: {\n creditor: \"CR123\",\n recipient_bank_account: \"BA123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->outboundPayments()->create([\n \"params\" => [\n \"amount\" => 1000,\n \"scheme\" => \"faster_payments\",\n \"description\" => \"Reward Payment (August 2024)\",\n \"reference\" => \"Invoice 123\",\n \"links\" => [\n \"creditor\" => \"CR123\",\n \"recipient_bank_account\" => \"BA123\"\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.OutboundPaymentService.OutboundPaymentCreateRequest.Scheme;\n\nOutboundPayment outboundPayment = client.outboundPayments().create()\n .withAmount(1000)\n .withScheme(Scheme.FASTER_PAYMENTS)\n .withDescription(\"Reward Payment (August 2024)\")\n .withReference(\"Invoice 123\")\n .withLinksCreditor(\"CR123\")\n .withLinksRecipientBankAccount(\"BA123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "outboundPaymentCreateParams := gocardless.OutboundPaymentCreateParams{\n Amount: 1000,\n Scheme: \"faster_payments\",\n Description: \"Reward Payment (August 2024)\",\n Reference: \"Invoice 123\",\n Links: gocardless.OutboundPaymentCreateParamsLinks{\n Creditor: \"CR123\",\n RecipientBankAccount: \"BA123\",\n },\n}\n\noutboundPayment, err := client.OutboundPayments.Create(ctx, outboundPaymentCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var paymentLinks = new GoCardless.Services.OutboundPaymentCreateRequest.OutboundPaymentLinks\n{\n Creditor = \"CR123\",\n RecipientBankAccount = \"BA123\"\n};\n\nvar resp = await client.OutboundPayments.CreateAsync(\n new GoCardless.Services.OutboundPaymentCreateRequest()\n {\n Amount = 1000,\n Scheme = GoCardless.Services.OutboundPaymentCreateRequest.OutboundPaymentScheme.FasterPayments,\n Description = \"Reward Payment (August 2024)\",\n Reference = \"Invoice 123\",\n Links = paymentLinks,\n }\n);\n\nGoCardless.Resources.OutboundPayment outboundPayment = resp.OutboundPayment;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/outbound_payments HTTP/1.1\nContent-Type: application/json\n{\n \"outbound_payments\": {\n \"amount\": 10,\n \"scheme\": \"faster_payments\",\n \"description\": \"Reward Payment (August 2024)\",\n \"links\": {\n \"recipient_bank_account\": \"BA12343\",\n \"creditor\": \"CR123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nContent-Type: application/json\n{\n \"outbound_payments\": {\n \"id\": \"OUT123\",\n \"created_at\": \"2024-09-05T12:20:04.397Z\",\n \"status\": \"pending_approval\",\n \"amount\": 10,\n \"scheme\": \"faster_payments\",\n \"currency\": \"GBP\",\n \"description\": \"Reward Payment (August 2024)\",\n \"execution_date\": \"2024-09-05\",\n \"reference\": \"GC-QC2FI7GBEW7VCXL\",\n \"is_withdrawal\": false,\n \"links\": {\n \"creditor\": \"CR123\",\n \"recipient_bank_account\": \"BA123\"\n },\n \"verifications\": {\n \"recipient_bank_account_holder_verification\": {\n \"result\": \"full_match\",\n \"type\": \"confirmation_of_payee\",\n \"actual_account_name\": null\n }\n },\n \"metadata\": {}\n }\n}" } ] }, "get": { "operationId": "list_outbound_payment", "summary": "List outbound payments", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of outbound payments.", "tags": [ "Outbound Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_from", "in": "query", "required": false, "schema": { "type": "string", "example": "2024-01-01" }, "description": "The beginning of query period" }, { "name": "created_to", "in": "query", "required": false, "schema": { "type": "string", "example": "2024-01-01" }, "description": "The end of query period" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/outbound_payment_status" } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/outbound_payment_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.outbound_payments.list(params: { limit: 10 })" }, { "lang": "Python", "label": "Python", "source": "client.outbound_payments.list(params={\"limit\": 10})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.outboundPayments.list({\n limit: 10\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->outboundPayments()->list([\n \"params\" => [\"limit\" => 10]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.outboundPayments().list()\n .withLimit(10)\n .execute();" }, { "lang": "Go", "label": "Go", "source": "outboundPaymentListParams := gocardless.OutboundPaymentListParams{\n Limit: 10,\n}\n\noutboundPaymentListResult, err := client.OutboundPayments.List(ctx, outboundPaymentListParams)" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.OutboundPaymentListRequest()\n{\n Limit = 10\n};\n\nvar resp = await client.OutboundPayments.ListAsync(request);" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/outbound_payments HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"outbound_payments\": [{\n \"id\": \"OUT123\",\n \"created_at\": \"2024-09-05T12:20:04.397Z\",\n \"status\": \"cancelled\",\n \"amount\": 10,\n \"scheme\": \"faster_payments\",\n \"currency\": \"GBP\",\n \"description\": \"Reward Payment (August 2024)\",\n \"execution_date\": \"2024-09-05\",\n \"reference\": \"GC-QC2FI7GBEW7VCXL\",\n \"is_withdrawal\": false,\n \"links\": {\n \"creditor\": \"CR123\",\n \"recipient_bank_account\": \"BA123\"\n },\n \"verifications\": {\n \"recipient_bank_account_holder_verification\": {\n \"result\": \"full_match\",\n \"type\": \"confirmation_of_payee\",\n \"actual_account_name\": null\n }\n },\n \"metadata\": {}\n }]\n}" } ] } }, "/outbound_payments/withdrawal": { "post": { "operationId": "withdrawal_outbound_payments", "summary": "Create a withdrawal outbound payment", "description": "Creates an outbound payment to your verified business bank account as the recipient.", "tags": [ "Outbound Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/outbound_payment_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outbound_payments": { "type": "object", "additionalProperties": false, "required": [ "amount", "scheme" ], "properties": { "amount": { "$ref": "#/components/schemas/outbound_payment_amount" }, "scheme": { "$ref": "#/components/schemas/outbound_payment_scheme" }, "description": { "$ref": "#/components/schemas/outbound_payment_description" }, "execution_date": { "$ref": "#/components/schemas/outbound_payment_execution_date" }, "metadata": { "$ref": "#/components/schemas/outbound_payment_metadata" }, "reference": { "$ref": "#/components/schemas/outbound_payment_reference" }, "links": { "type": "object", "additionalProperties": false, "properties": { "creditor": { "type": "string", "description": "ID of the creditor who sends the outbound payment.", "example": "CR123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.outbound_payments.withdraw(\n params: {\n amount: 5000,\n scheme: \"faster_payments\",\n description: \"Withdraw funds to business account\",\n links: {\n creditor: \"CR123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.outbound_payments.withdraw(params={\n \"amount\": 5000,\n \"scheme\": \"faster_payments\",\n \"description\": \"Withdraw funds to business account\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const outboundPayment = await client.outboundPayments.withdraw({\n amount: 5000,\n scheme: \"faster_payments\",\n description: \"Withdraw funds to business account\",\n links: {\n creditor: \"CR123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->outboundPayments()->withdraw([\n \"params\" => [\n \"amount\" => 5000,\n \"scheme\" => \"faster_payments\",\n \"description\" => \"Withdraw funds to business account\",\n \"links\" => [\n \"creditor\" => \"CR123\"\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.OutboundPaymentService.OutboundPaymentWithdrawRequest.Scheme;\n\nOutboundPayment outboundPayment = client.outboundPayments().withdraw()\n .withAmount(5000)\n .withScheme(Scheme.FASTER_PAYMENTS)\n .withDescription(\"Withdraw funds to business account\")\n .withLinksCreditor(\"CR123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "outboundPaymentWithdrawParams := gocardless.OutboundPaymentWithdrawParams{\n Amount: 5000,\n Scheme: \"faster_payments\",\n Description: \"Withdraw funds to business account\",\n Links: &gocardless.OutboundPaymentWithdrawParamsLinks{\n Creditor: \"CR123\",\n },\n}\n\noutboundPayment, err := client.OutboundPayments.Withdraw(ctx, outboundPaymentWithdrawParams)" }, { "lang": "C#", "label": ".NET", "source": "var paymentLinks = new GoCardless.Services.OutboundPaymentWithdrawRequest.OutboundPaymentLinks\n{\n Creditor = \"CR123\"\n};\n\nvar resp = await client.OutboundPayments.WithdrawAsync(\n new GoCardless.Services.OutboundPaymentWithdrawRequest()\n {\n Amount = 5000,\n Scheme = GoCardless.Services.OutboundPaymentWithdrawRequest.OutboundPaymentScheme.FasterPayments,\n Description = \"Withdraw funds to business account\",\n Links = paymentLinks,\n }\n);\n\nGoCardless.Resources.OutboundPayment outboundPayment = resp.OutboundPayment;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/outbound_payments/withdrawal HTTP/1.1\nContent-Type: application/json\n{\n \"outbound_payments\": {\n \"amount\": 10,\n \"scheme\": \"faster_payments\",\n \"description\": \"Withdraw funds to business account.\"\n }\n}\n\nHTTP/1.1 201 Created\nContent-Type: application/json\n{\n \"outbound_payments\": {\n \"id\": \"OUT123\",\n \"created_at\": \"2024-09-05T12:20:04.397Z\",\n \"status\": \"pending_approval\",\n \"amount\": 10,\n \"scheme\": \"faster_payments\",\n \"currency\": \"GBP\",\n \"description\": \"Withdraw funds to business account.\",\n \"execution_date\": \"2024-09-05\",\n \"reference\": \"GC-QC2FI7GBEW7VCXL\",\n \"is_withdrawal\": true,\n \"verifications\": {\n \"recipient_bank_account_holder_verification\": null\n },\n \"links\": {\n \"creditor\": \"CR123\",\n \"recipient_bank_account\": \"BA123\"\n },\n \"metadata\": {}\n }\n}" } ] } }, "/outbound_payments/{outbound_payment_id}/actions/cancel": { "post": { "operationId": "cancel_outbound_payment", "summary": "Cancel an outbound payment", "description": "Cancels an outbound payment. Only outbound payments with either `verifying`, `pending_approval`, or `scheduled` status can be cancelled.\nOnce an outbound payment is `executing`, the money moving process has begun and cannot be reversed.", "tags": [ "Outbound Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "outbound_payment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The outbound payment id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/outbound_payment_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outbound_payments": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/outbound_payment_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.outbound_payments.cancel(\"OUT123\")" }, { "lang": "Python", "label": "Python", "source": "client.outbound_payments.cancel(\"OUT123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.outboundPayments.cancel(\"OUT123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->outboundPayments()->cancel(\"OUT123\");" }, { "lang": "Java", "label": "Java", "source": "client.outboundPayments().cancel(\"OUT123\").execute();" }, { "lang": "Go", "label": "Go", "source": "outboundPayment, err := client.OutboundPayments.Cancel(ctx, \"OUT123\", gocardless.OutboundPaymentCancelParams{})" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.OutboundPayments.CancelAsync(\"OUT123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/outbound_payments/OUT123/actions/cancel\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"outbound_payments\": {\n \"id\": \"OUT123\",\n \"created_at\": \"2024-09-05T12:20:04.397Z\",\n \"status\": \"cancelled\",\n \"amount\": 10,\n \"scheme\": \"faster_payments\",\n \"currency\": \"GBP\",\n \"description\": \"Reward Payment (August 2024)\",\n \"execution_date\": \"2024-09-05\",\n \"reference\": \"GC-QC2FI7GBEW7VCXL\",\n \"is_withdrawal\": false,\n \"links\": {\n \"creditor\": \"CR123\",\n \"recipient_bank_account\": \"BA123\"\n },\n \"verifications\": {\n \"recipient_bank_account_holder_verification\": {\n \"result\": \"full_match\",\n \"type\": \"confirmation_of_payee\",\n \"actual_account_name\": null\n }\n },\n \"metadata\": {}\n }\n}" } ] } }, "/outbound_payments/{outbound_payment_id}/actions/approve": { "post": { "operationId": "approve_outbound_payment", "summary": "Approve an outbound payment", "description": "Approves an outbound payment. Only outbound payments with the \"pending_approval\" status can be approved.", "tags": [ "Outbound Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "outbound_payment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The outbound payment id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/outbound_payment_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outbound_payments": { "type": "object", "additionalProperties": false, "properties": {} } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.outbound_payments.approve(\"OUT123\")" }, { "lang": "Python", "label": "Python", "source": "client.outbound_payments.approve(\"OUT123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.outboundPayments.approve(\"OUT123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->outboundPayments()->approve(\"OUT123\");" }, { "lang": "Java", "label": "Java", "source": "client.outboundPayments().approve(\"OUT123\").execute();" }, { "lang": "Go", "label": "Go", "source": "outboundPayment, err := client.OutboundPayments.Approve(ctx, \"OUT123\", gocardless.OutboundPaymentApproveParams{})" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.OutboundPayments.ApproveAsync(\"OUT123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/outbound_payments/OUT123/actions/approve\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"outbound_payments\": {\n \"id\": \"OUT123\",\n \"created_at\": \"2024-09-05T12:20:04.397Z\",\n \"status\": \"scheduled\",\n \"amount\": 10,\n \"scheme\": \"faster_payments\",\n \"currency\": \"GBP\",\n \"description\": \"Reward Payment (August 2024)\",\n \"execution_date\": \"2024-09-05\",\n \"reference\": \"GC-QC2FI7GBEW7VCXL\",\n \"is_withdrawal\": false,\n \"links\": {\n \"creditor\": \"CR123\",\n \"recipient_bank_account\": \"BA123\"\n },\n \"verifications\": {\n \"recipient_bank_account_holder_verification\": {\n \"result\": \"full_match\",\n \"type\": \"confirmation_of_payee\",\n \"actual_account_name\": null\n }\n },\n \"metadata\": {}\n }\n}" } ] } }, "/outbound_payments/{outbound_payment_id}": { "get": { "operationId": "get_outbound_payments", "summary": "Get an outbound payment", "description": "Fetches an outbound_payment by ID", "tags": [ "Outbound Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "outbound_payment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The outbound payment id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/outbound_payment_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.outbound_payments.get(\"OUT123\")" }, { "lang": "Python", "label": "Python", "source": "client.outbound_payments.get(\"OUT123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.outboundPayments.find(\"OUT123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->outboundPayments()->get(\"OUT123\");" }, { "lang": "Java", "label": "Java", "source": "client.outboundPayments().get(\"OUT123\").execute();" }, { "lang": "Go", "label": "Go", "source": "outboundPayment, err := client.OutboundPayments.Get(ctx, \"OUT123\")" }, { "lang": "C#", "label": ".NET", "source": "var resp = await client.OutboundPayments.GetAsync(\"OUT123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/outbound_payments/OUT123\n\nHTTP/1.1 200\nContent-Type: application/json\n{\n \"outbound_payments\": {\n \"id\": \"OUT123\",\n \"created_at\": \"2024-09-05T12:20:04.397Z\",\n \"status\": \"scheduled\",\n \"amount\": 10,\n \"scheme\": \"faster_payments\",\n \"currency\": \"GBP\",\n \"description\": \"Reward Payment (August 2024)\",\n \"execution_date\": \"2024-09-05\",\n \"reference\": \"GC-QC2FI7GBEW7VCXL\",\n \"is_withdrawal\": false,\n \"links\": {\n \"creditor\": \"CR123\",\n \"recipient_bank_account\": \"BA123\"\n },\n \"verifications\": {\n \"recipient_bank_account_holder_verification\": {\n \"result\": \"full_match\",\n \"type\": \"confirmation_of_payee\",\n \"actual_account_name\": null\n }\n },\n \"metadata\": {}\n }\n}" } ] }, "put": { "operationId": "update_outbound_payments", "summary": "Update an outbound payment", "description": "Updates an outbound payment object. This accepts only the metadata parameter.", "tags": [ "Outbound Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "outbound_payment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The outbound payment id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/outbound_payment_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outbound_payments": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/outbound_payment_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.outbound_payments.update(\n \"OUT123\",\n params: {\n metadata: {\n invoice_id: \"INV-1234\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.outbound_payments.update(\"OUT123\", params={\n \"metadata\": {\n \"invoice_id\": \"INV-1234\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resp = await client.outboundPayments.update(\"OUT123\", {\n metadata: {\n invoice_id: \"INV-1234\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->outboundPayments()->update(\"OUT123\", [\n \"params\" => [\n \"metadata\" => [\n \"invoice_id\" => \"INV-1234\"\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "OutboundPayment outboundPayment = client.outboundPayments().update(\"OUT123\")\n .withMetadata(\"invoice_id\", \"INV-1234\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "outboundPaymentUpdateParams := gocardless.OutboundPaymentUpdateParams{\n Metadata: map[string]string{\n \"invoice_id\": \"INV-1234\",\n },\n}\n\noutboundPayment, err := client.OutboundPayments.Update(ctx, \"OUT123\", outboundPaymentUpdateParams)" }, { "lang": "C#", "label": ".NET", "source": "var metadata = new DictionaryNote that in order to update the `metadata` attribute values it must be sent completely as it overrides the previously existing values.
\n\n**Deprecated:** Payer Authorisation is legacy API and cannot be used by new integrators.\nThe [Billing Request](#billing-requests) API should be used for any new integrations.", "tags": [ "Payer Authorisation" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "payer_authorisation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payer authorisation id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payer_authorisation_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payer_authorisations": { "type": "object", "additionalProperties": false, "required": [ "customer", "bank_account", "mandate" ], "properties": { "customer": { "$ref": "#/components/schemas/payer_authorisation_customer" }, "bank_account": { "$ref": "#/components/schemas/payer_authorisation_bank_account" }, "mandate": { "$ref": "#/components/schemas/payer_authorisation_mandate" } } } } } } } }, "deprecated": true, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.payer_authorisations.update(\n \"PA123\",\n params: {\n \"customer\": {\n \"email\": \"mail@example.com\",\n \"given_name\": \"Name\",\n \"family_name\": \"Surname\",\n \"metadata\": {\n \"salesforce_id\": \"EFGH5678\"\n }\n },\n \"bank_account\": {\n \"account_holder_name\": \"Name Surname\",\n \"branch_code\": \"200000\",\n \"account_number\": \"55779911\",\n },\n \"mandate\": {\n \"reference\": \"XYZ789\",\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.payer_authorisations.update(\"PA123\", params={\n \"customer\": {\n \"email\": \"mail@example.com\",\n \"given_name\": \"Name\",\n \"family_name\": \"Surname\",\n \"metadata\": {\n \"salesforce_id\": \"EFGH5678\"\n }\n },\n \"bank_account\": {\n \"account_holder_name\": \"Name Surname\",\n \"branch_code\": \"200000\",\n \"account_number\": \"55779911\",\n },\n \"mandate\": {\n \"reference\": \"XYZ789\",\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const payerAuthorisation = await client.payerAuthorisations.update(\n \"PA123\",\n {\n \"customer\": {\n \"email\": \"mail@example.com\",\n \"given_name\": \"Name\",\n \"family_name\": \"Surname\",\n \"metadata\": {\n \"salesforce_id\": \"EFGH5678\"\n }\n },\n \"bank_account\": {\n \"account_holder_name\": \"Name Surname\",\n \"branch_code\": \"200000\",\n \"account_number\": \"55779911\",\n \"metadata\": {}\n },\n \"mandate\": {\n \"reference\": \"XYZ789\",\n \"metadata\": {}\n }\n });" }, { "lang": "PHP", "label": "PHP", "source": "$client->payerAuthorisations()->update(\"PA123\", [\n \"params\" => [\"customer\" => [\n \"email\" => \"mail@example.com\",\n \"given_name\" => \"Name\",\n \"family_name\" => \"Surname\",\n \"metadata\" => [\n \"salesforce_id\" => \"EFGH5678\"\n ]\n ],\n \"bank_account\" => [\n \"account_holder_name\" => \"Name Surname\",\n \"branch_code\" => \"200000\",\n \"account_number\" => \"55779911\",\n ],\n \"mandate\" => [\n \"reference\" => \"XYZ789\",\n ]]\n]);" }, { "lang": "Java", "label": "Java", "source": "import java.util.HashMap;\nimport java.util.Map;\n\nMap\n The main use of the confirm endpoint is to enable integrators to acknowledge the end of the setup process.\n They might want to make the payers go through some other steps after they go through our flow or make them go through the necessary verification mechanism (upcoming feature).\n
\n\n**Deprecated:** Payer Authorisation is legacy API and cannot be used by new integrators.\nThe [Billing Request](#billing-requests) API should be used for any new integrations.", "tags": [ "Payer Authorisation" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "payer_authorisation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payer authorisation id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payer_authorisation_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "deprecated": true, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.payer_authorisations.confirm(\"PAU123\")" }, { "lang": "Python", "label": "Python", "source": "client.payer_authorisations.confirm(\"PAU123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const payerAuthorisation = await client.payerAuthorisations.confirm(\"PAU123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->payerAuthorisations()->confirm(\"PAU123\");" }, { "lang": "Java", "label": "Java", "source": "PayerAuthorisation payerAuthorisation = client.payerAuthorisations().confirm(\"PAU123\").execute();" }, { "lang": "Go", "label": "Go", "source": "payerAuthorisation, err := client.PayerAuthorisations.Confirm(ctx, \"PAU123\")" }, { "lang": "C#", "label": ".NET", "source": "var payerAuthorisationResponse = await client.PayerAuthorisations.ConfirmAsync(\"PAU123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/payer_authorisations/PA123/actions/confirm HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"payer_authorisations\": {\n \"id\": \"PA123\",\n \"created_at\": \"2020-04-15T15:00:00.000Z\",\n \"status\": \"confirmed\",\n \"customer\": {\n \"email\": \"mail@example.com\",\n \"given_name\": \"Name\",\n \"family_name\": \"Surname\",\n \"metadata\": {\n \"salesforce_id\": \"EFGH5678\"\n }\n },\n \"bank_account\": {\n \"account_holder_name\": \"Name Surname\",\n \"account_number_ending\": \"11\",\n \"metadata\": {}\n },\n \"mandate\": {\n \"reference\": \"XYZ789\",\n \"metadata\": {}\n },\n \"links\": {},\n \"incomplete_fields\": []\n }\n}\n\nor\n\nHTTP/1.1 422 Bad Request\nContent-Type: application/json\n{\n \"error\": {\n \"message\": \"The Payer Authorisation needs to be submitted before confirmation\",\n \"errors\": [\n {\n \"reason\": \"payer_authorisation_submit_before_confirm\",\n \"message\": \"The Payer Authorisation needs to be submitted before confirmation\"\n }\n ],\n \"documentation_url\": \"https://developer.gocardless.com/api-reference#payer_authorisation_submit_before_confirm\",\n \"type\": \"invalid_state\",\n \"request_id\": \"...\",\n \"code\": 422\n }\n}" } ] } }, "/branding/payer_themes": { "post": { "operationId": "payer_themes_branding", "summary": "Create a payer theme associated with a creditor", "description": "Creates a new payer theme associated with a creditor. If a creditor already has payer themes, this will update the existing payer theme linked to the creditor.\n\nRestricted: This endpoint is restricted to GoCardless Embed customers. Please [contact us](https://forms.gocardless.com/l/305971/2023-01-25/535t8n){:target=\"_blank\"} if you are interested in using this product.
", "tags": [ "Payer Theme" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payer_theme_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payer_themes": { "type": "object", "additionalProperties": false, "properties": { "header_background_colour": { "type": "string", "description": "Colour for header background (hexcode)", "example": "#FFFFFF" }, "link_text_colour": { "type": "string", "description": "Colour for text links (hexcode)", "example": "#3179D9" }, "button_background_colour": { "type": "string", "description": "Colour for buttons background (hexcode)", "example": "#00A87E" }, "content_box_border_colour": { "type": "string", "description": "Colour for content box border (hexcode)", "example": "#D7D9DE" }, "links": { "type": "object", "description": "", "properties": { "creditor": { "type": "string", "nullable": true, "description": "ID of the creditor the payer theme belongs to", "example": "CR1234" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.payer_themes.create_for_creditor(\n params: {\n \"header_background_colour\": \"#BD10E0\",\n \"link_text_colour\": \"#7ED321\",\n \"button_background_colour\": \"#128DAA\",\n \"content_box_border_colour\": \"#BD10E0\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.payer_themes.create_for_creditor(params={\n \"header_background_colour\": \"#BD10E0\",\n \"link_text_colour\": \"#7ED321\",\n \"button_background_colour\": \"#128DAA\",\n \"content_box_border_colour\": \"#BD10E0\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const payerThemes = await client.payerThemes.createForCreditor({\n header_background_colour: \"#BD10E0\",\n link_text_colour: \"#7ED321\",\n button_background_colour: \"#128DAA\",\n content_box_border_colour: \"#BD10E0\",\n links: {\n creditor: \"CR123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->payerThemes()->createForCreditor([\n \"params\" => [\n \"header_background_colour\" => \"#BD10E0\",\n \"link_text_colour\" => \"#7ED321\",\n \"button_background_colour\" => \"#128DAA\",\n \"content_box_border_colour\" => \"#BD10E0\",\n \"links\" => [\n \"creditor\" => \"CR123\"\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "PayerTheme payerTheme = client.payerThemes().createForCreditor()\n .withButtonBackgroundColour(\"#128DAA\")\n .withContentBoxBorderColour(\"#BD10E0\")\n .withHeaderBackgroundColour(\"#BD10E0\")\n .withLinkTextColour(\"#7ED321\")\n .withLinksCreditor(\"CR123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "payerThemeCreateForCreditorParams := gocardless.PayerThemeCreateForCreditorParams{\n ButtonBackgroundColour: \"#128DAA\",\n ContentBoxBorderColour: \"#BD10E0\",\n HeaderBackgroundColour: \"#BD10E0\",\n LinkTextColour: \"#7ED321\",\n Links: &gocardless.PayerThemeCreateForCreditorParamsLinks{\n Creditor: \"CR123\",\n },\n}\n\npayerThemes, err := client.PayerThemes.CreateForCreditor(ctx, payerThemeCreateForCreditorParams)" }, { "lang": "C#", "label": ".NET", "source": "var payerThemeCreateForCreditorRequest = new GoCardless.Services.PayerThemeCreateForCreditorRequest()\n{\n HeaderBackgroundColour = \"#BD10E0\",\n LinkTextColour = \"#7ED321\",\n ButtonBackgroundColour = \"#128DAA\",\n ContentBoxBorderColour = \"#BD10E0\",\n Links = new GoCardless.Services.PayerThemeCreateForCreditorRequest.PayerThemeLinks()\n {\n Creditor = \"CR0123\"\n }\n};\n\nvar payerThemeCreateForCreditorResponse = await client.PayerThemes.CreateForCreditorAsync(payerThemeCreateForCreditorRequest);\nGoCardless.Resources.PayerTheme creditorPayerTheme = payerThemeCreateForCreditorResponse.PayerTheme;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/branding/payer_themes HTTP/1.1\nContent-Type: application/json\n{\n \"payer_themes\": {\n \"header_background_colour\": \"#BD10E0\",\n \"link_text_colour\": \"#7ED321\",\n \"button_background_colour\": \"#128DAA\",\n \"content_box_border_colour\": \"#BD10E0\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}\n\nHTTP/1.1 201 OK\nContent-Type: application/json\n{\n \"payer_themes\": {\n \"id\": \"PTH123\"\n }\n}" } ] } }, "/payments": { "post": { "operationId": "create_payment", "summary": "Create a payment", "description": "Creates a new payment object.\n\nThis fails with a `mandate_is_inactive` error if the linked [mandate](#core-endpoints-mandates) is cancelled or has failed. Payments can be created against mandates with status of: `pending_customer_approval`, `pending_submission`, `submitted`, and `active`.\n\nWarning: in Bacs, you have the option to provide a payment reference up to 10 characters in length. However, if you are providing custom mandate references (which can only be enabled by contacting support), the combined length of the two references separated by a dash character must not exceed 18 characters. Payment references may be up to 140 characters for SEPA, 11 for Autogiro and 30 for Betalingsservice, irrespective of the mandate reference.
", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "object", "additionalProperties": false, "required": [ "amount", "currency", "links" ], "properties": { "amount": { "$ref": "#/components/schemas/payment_amount_stringable" }, "currency": { "$ref": "#/components/schemas/payment_currency" }, "description": { "$ref": "#/components/schemas/payment_description" }, "charge_date": { "$ref": "#/components/schemas/payment_charge_date" }, "reference": { "$ref": "#/components/schemas/payment_reference" }, "app_fee": { "$ref": "#/components/schemas/payment_app_fee_request" }, "retry_if_possible": { "$ref": "#/components/schemas/payment_retry_if_possible" }, "faster_ach": { "$ref": "#/components/schemas/payment_faster_ach_request" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "psu_interaction_type": { "$ref": "#/components/schemas/payment_psu_interaction_type" }, "links": { "type": "object", "description": "", "additionalProperties": false, "required": [ "mandate" ], "properties": { "mandate": { "type": "string", "description": "ID of the [mandate](#core-endpoints-mandates) against which this payment should be collected.", "example": "MD123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.payments.create(\n params: {\n amount: 1000,\n currency: \"GBP\",\n description: \"Club membership fee\",\n links: {\n mandate: \"MD123\"\n }\n },\n headers: {\n \"Idempotency-Key\" => \"aaf50eb0-8ddb-4900-a97b-40ed794570a1\"\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.payments.create(params={\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"charge_date\": \"2014-05-19\",\n \"reference\": \"WINEBOX001\",\n \"metadata\": {\n \"order_dispatch_date\": \"2014-05-22\"\n },\n \"links\": {\n \"mandate\": \"MD123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const payment = await client.payments.create({\n amount: 100,\n currency: \"GBP\",\n charge_date: \"2014-05-19\",\n reference: \"WINEBOX001\",\n metadata: {\n order_dispatch_date: \"2014-05-22\"\n },\n links: {\n mandate: \"MD123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->payments()->create([\n \"params\" => [\"amount\" => 100,\n \"currency\" => \"GBP\",\n \"metadata\" => [\n \"order_dispatch_date\" => \"2016-08-04\"\n ],\n \"links\" => [\n \"mandate\" => \"MD123\"\n ]]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.PaymentService.PaymentCreateRequest.Currency;\n\nPayment payment = client.payments().create()\n .withAmount(100)\n .withCurrency(Currency.GBP)\n .withChargeDate(\"2014-05-19\")\n .withReference(\"WINEBOX001\")\n .withMetadata(\"order_dispatch_date\", \"2014-05-22\")\n .withLinksMandate(\"MD123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "paymentCreateParams := gocardless.PaymentCreateParams{\n Amount: 100,\n Currency: \"GBP\",\n ChargeDate: \"2014-05-19\",\n Reference: \"WINEBOX001\",\n Metadata: map[string]string{\"order_dispatch_date\": \"2014-05-22\"},\n Links: gocardless.PaymentCreateParamsLinks{\n Mandate: \"MD123\",\n },\n}\n\npayment, err := client.Payments.Create(ctx, paymentCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var paymentRequest = new GoCardless.Services.PaymentCreateRequest()\n{\n Amount = 1000,\n Currency = GoCardless.Services.PaymentCreateRequest.PaymentCurrency.GBP,\n Description = \"Membership fee\",\n Links = new GoCardless.Services.PaymentCreateRequest.PaymentLinks()\n {\n Mandate = \"MD0123\"\n }\n};\n\nvar paymentResponse = await client.Payments.CreateAsync(paymentRequest);\nGoCardless.Resources.Payment payment = paymentResponse.Payment;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/payments HTTP/1.1\nContent-Type: application/json\n{\n \"payments\": {\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"charge_date\": \"2014-05-19\",\n \"reference\": \"WINEBOX001\",\n \"metadata\": {\n \"order_dispatch_date\": \"2014-05-22\"\n },\n \"links\": {\n \"mandate\": \"MD123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /payments/PM123\nContent-Type: application/json\n{\n \"payments\": {\n \"id\": \"PM123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"charge_date\": \"2014-05-21\",\n \"amount\": 100,\n \"description\": null,\n \"currency\": \"GBP\",\n \"status\": \"pending_submission\",\n \"reference\": \"WINEBOX001\",\n \"metadata\": {\n \"order_dispatch_date\": \"2014-05-22\"\n },\n \"amount_refunded\": 0,\n \"fx\": {\n \"fx_currency\": \"EUR\",\n \"fx_amount\": null,\n \"exchange_rate\": null,\n \"estimated_exchange_rate\": \"1.1234567890\"\n },\n \"links\": {\n \"mandate\": \"MD123\",\n \"creditor\": \"CR123\"\n },\n \"retry_if_possible\": false\n }\n}" } ] }, "get": { "operationId": "list_payment", "summary": "List payments", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your payments.", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true }, { "name": "currency", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/payment_currency" } }, { "name": "charge_date", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records where the payment was or will be collected from the customer's bank account after the specified date.", "format": "date" }, "lt": { "type": "string", "description": "Limit to records where the payment was or will be collected from the customer's bank account before the specified date.", "format": "date" }, "gte": { "type": "string", "description": "Limit to records where the payment was or will be collected from the customer's bank account on or after the specified date.", "format": "date" }, "lte": { "type": "string", "description": "Limit to records where the payment was or will be collected from the customer's bank account on or before the specified date.", "format": "date" } } }, "style": "deepObject", "explode": true }, { "name": "customer", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/customer_identity" }, { "description": "ID of a customer to filter payments by. If you pass this parameter, you cannot also pass `creditor`." } ] } }, { "name": "sort_field", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/payment_sort_field" } ] } }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/payment_sort_direction" } }, { "name": "creditor", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/creditor_identity" }, { "description": "ID of a creditor to filter payments by. If you pass this parameter, you cannot also pass `customer`." } ] } }, { "name": "subscription", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/subscription_identity" } }, { "name": "mandate", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/mandate_identity" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/payment_status" } }, { "name": "scheme", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/payment_scheme" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.payments.list\n\n@client.payments.list(params: { customer: \"CU123\" })\n\n@client.payments.list.records.each { |payment| puts payment.inspect }" }, { "lang": "Python", "label": "Python", "source": "client.payments.list().records\n\nclient.payments.list(params={\"customer\": \"CU123\"}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const payments = await client.payments.list();\n\n// List all payments past a certain date.\nconst filteredPayments = await client.payments.list({\n created_at: {\n gt: \"2020-01-01T17:01:06.000Z\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->payments()->list();\n\n$client->payments()->list([\n \"params\" => [\"customer\" => \"CU123\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "for (Payment payment : client.payments().all().withCustomer(\"CU123\").execute()) {\n System.out.println(payment.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "paymentListParams := gocardless.PaymentListParams{\n CreatedAt: &gocardless.PaymentListParamsCreatedAt{\n Gt: \"2020-01-01T17:01:06.000Z\",\n },\n}\n\npaymentListResult, err := client.Payments.List(ctx, paymentListParams)\nfor _, payment := range paymentListResult.Payments {\n fmt.Println(payment.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var paymentRequest = new GoCardless.Services.PaymentListRequest()\n{\n Customer = \"CU000123\"\n};\n\nvar paymentListResponse = client.Payments.All(paymentRequest);\nforeach (GoCardless.Resources.Payment payment in paymentListResponse)\n{\n Console.WriteLine(payment.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/payments HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"payments\": [{\n \"id\": \"PM123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"charge_date\": \"2014-05-15\",\n \"amount\": 100,\n \"description\": null,\n \"currency\": \"GBP\",\n \"status\": \"pending_submission\",\n \"reference\": \"WINEBOX001\",\n \"metadata\": {\n \"order_dispatch_date\": \"2014-05-22\"\n },\n \"amount_refunded\": 0,\n \"fx\": {\n \"fx_currency\": \"EUR\",\n \"fx_amount\": null,\n \"exchange_rate\": null,\n \"estimated_exchange_rate\": \"1.1234567890\"\n },\n \"links\": {\n \"mandate\": \"MD123\",\n \"creditor\": \"CR123\"\n },\n \"retry_if_possible\": false\n }]\n}" } ] } }, "/payments/{payment_id}": { "get": { "operationId": "get_payments", "summary": "Get a single payment", "description": "Retrieves the details of a single existing payment.", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payment id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.payments.get(\"PM123\")" }, { "lang": "Python", "label": "Python", "source": "client.payments.get(\"PM123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const payment = await client.payments.find(\"PM123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->payments()->get(\"PM123\");" }, { "lang": "Java", "label": "Java", "source": "Payment payment = client.payments().get(\"PM123\").execute();" }, { "lang": "Go", "label": "Go", "source": "payment, err := client.Payments.Get(ctx, \"PM123\")" }, { "lang": "C#", "label": ".NET", "source": "var paymentResponse = await client.Payments.GetAsync(\"PM0123\");\nGoCardless.Resources.Payment payment = paymentResponse.Payment;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/payments/PM123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"payments\": {\n \"id\": \"PM123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"charge_date\": \"2014-05-15\",\n \"amount\": 100,\n \"description\": null,\n \"currency\": \"GBP\",\n \"status\": \"pending_submission\",\n \"reference\": \"WINEBOX001\",\n \"metadata\": {\n \"order_dispatch_date\": \"2014-05-22\"\n },\n \"amount_refunded\": 0,\n \"fx\": {\n \"fx_currency\": \"EUR\",\n \"fx_amount\": null,\n \"exchange_rate\": null,\n \"estimated_exchange_rate\": \"1.1234567890\"\n },\n \"links\": {\n \"mandate\": \"MD123\",\n \"creditor\": \"CR123\"\n },\n \"retry_if_possible\": false\n }\n}" } ] }, "put": { "operationId": "update_payments", "summary": "Update a payment", "description": "Updates a payment object. This accepts only the metadata parameter.", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payment id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "object", "additionalProperties": false, "properties": { "retry_if_possible": { "$ref": "#/components/schemas/payment_retry_if_possible" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.payments.update(\n \"PM123\",\n params: {\n metadata: { order_id: \"transaction-0HE9WQ0WDE\" }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.payments.update(\"PM123\", params={\n \"metadata\": {\"key\": \"value\"}\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const payment = await client.payments.update(\n \"PM123\",\n {\n metadata: {\n key: \"value\"\n }\n }\n);" }, { "lang": "PHP", "label": "PHP", "source": "$client->payments()->update(\"PM123\", [\n \"params\" => [\"metadata\" => [\"internal_id\" => \"XX123\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.payments().update(\"PM123\")\n .withMetadata(\"order_id\", \"transaction-0HE9WQ0WDE\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "paymentUpdateParams := gocardless.PaymentUpdateParams{\n Metadata: map[string]string{\"key\": \"value\"},\n}\n\npayment, err := client.Payments.Update(ctx, \"PM123\", paymentUpdateParams)" }, { "lang": "C#", "label": ".NET", "source": "var paymentRequest = new GoCardless.Services.PaymentUpdateRequest()\n{\n Metadata = new Dictionary410 Gone.\n",
"tags": [
"Payout Item"
],
"parameters": [
{
"$ref": "#/components/parameters/GoCardlessVersionHeader"
},
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
},
"description": "Cursor pointing to the end of the desired set."
},
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
},
"description": "Cursor pointing to the start of the desired set."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"description": "Number of records to return."
},
{
"name": "payout",
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/payout_id"
}
},
{
"name": "include_2020_tax_cutover",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/payout_item_include_2020_tax_cutover"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payout_item_multi_resource_response"
}
}
},
"description": "Successful response"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "Unauthorised",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "Internal Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "Ruby",
"label": "Ruby",
"source": "@client.payout_items.list(params: {payout: \"PO123\"})"
},
{
"lang": "Python",
"label": "Python",
"source": "client.payout_items.list(params={'payout': 'PO123'})"
},
{
"lang": "JavaScript",
"label": "JavaScript",
"source": "const payoutItems = await client.payoutItems.list({ payout: \"P0123\" });\n\n// List the first three payout items for a payout\nconst limitedPayoutItems = await client.payoutItems.list({ payout: \"P0123\", limit: 3 });"
},
{
"lang": "PHP",
"label": "PHP",
"source": "$client->payoutItems()->list([\n 'params' => ['payout' => 'PO123']\n]);"
},
{
"lang": "Java",
"label": "Java",
"source": "client.payoutItems().all().withPayout(\"PO123\").execute();"
},
{
"lang": "Go",
"label": "Go",
"source": "payoutItemsListParams := gocardless.PayoutItemListParams{\n Payout: \"PO123\",\n}\n\npayoutItemsListResult, err := client.PayoutItems.List(ctx, payoutItemsListParams)\nfor _, payoutItem := range payoutItemsListResult.PayoutItems {\n fmt.Println(payoutItem.Amount)\n}"
},
{
"lang": "C#",
"label": ".NET",
"source": "var itemsRequest = new GoCardless.Services.PayoutItemListRequest()\n{\n Payout = \"PO123\"\n};\n\nvar response = client.PayoutItems.All(itemsRequest);\nforeach (GoCardless.Resources.PayoutItem item in response)\n{\n Console.WriteLine(item.Amount);\n}"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "GET https://api.gocardless.com/payout_items?payout=PO123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"payout_items\": [\n {\n \"amount\": \"4.0\",\n \"type\": \"gocardless_fee\",\n \"taxes\": [{\n \"amount\": \"1.0\",\n \"currency\": \"GBP\",\n \"destination_amount\": \"1.1\",\n \"destination_currency\": \"EUR\",\n \"exchange_rate\": \"1.11205\",\n \"tax_rate_id\": \"FR_VAT_1\"\n }],\n \"links\": {\n \"payment\": \"PM456\"\n }\n },\n {\n \"amount\": \"1000.0\",\n \"type\": \"payment_paid_out\",\n \"taxes\": [],\n \"links\": {\n \"payment\": \"PM123\"\n }\n },\n {\n \"amount\": \"-24.0\",\n \"type\": \"gocardless_fee\",\n \"taxes\": [{\n \"amount\": \"4.0\",\n \"currency\": \"EUR\",\n \"destination_amount\": \"4.0\",\n \"destination_currency\": \"EUR\",\n \"exchange_rate\": null,\n \"tax_rate_id\": \"FR_VAT_1\"\n }],\n \"links\": {\n \"payment\": \"PM123\"\n }\n },\n {\n \"amount\": \"30.0\",\n \"type\": \"payment_paid_out\",\n \"taxes\": [],\n \"links\": {\n \"payment\": \"PM456\"\n }\n },\n {\n \"amount\": \"-500.0\",\n \"type\": \"payment_refunded\",\n \"taxes\": [],\n \"links\": {\n \"payment\": \"PM789\"\n }\n },\n {\n \"amount\": \"4.0\",\n \"type\": \"gocardless_fee\",\n \"taxes\": [{\n \"amount\": \"1.0\",\n \"currency\": \"GBP\",\n \"destination_amount\": \"1.1\",\n \"destination_currency\": \"EUR\",\n \"exchange_rate\": \"1.11205\",\n \"tax_rate_id\": \"FR_VAT_1\"\n }],\n \"links\": {\n \"payment\": \"PM456\"\n }\n },\n {\n \"amount\": \"-1.0\",\n \"type\": \"app_fee\",\n \"taxes\": [],\n \"links\": {\n \"payment\": \"PM456\"\n }\n }\n ],\n \"meta\": {\n \"cursors\": { \"before\": null, \"after\": null },\n \"limit\": 50\n }\n}\n\nGET https://api.gocardless.com/payout_items?payout=PO456 HTTP/1.1\n\nHTTP/1.1 410 Gone\nContent-Type: application/json\n{\n \"error\": {\n \"documentation_url\": \"https://developer.gocardless.com/api-reference#payout_items_data_archived\",\n \"message\": \"Payout items for payouts created more than 6 months ago are archived. Please contact support if you require access to this data.\",\n \"type\": \"invalid_api_usage\",\n \"errors\": [\n {\n \"reason\": \"payout_items_data_archived\",\n \"message\": \"Payout items for payouts created more than 6 months ago are archived. Please contact support if you require access to this data.\"\n }\n ],\n \"code\": 410,\n \"request_id\": \"deadbeef-0000-4000-0000-444400004444\"\n }\n}"
}
]
}
},
"/redirect_flows": {
"post": {
"operationId": "create_redirect_flow",
"summary": "Create a redirect flow",
"description": "Creates a redirect flow object which can then be used to redirect your customer to the GoCardless hosted payment pages.\n\n**Deprecated:** Redirect Flows are legacy APIs and cannot be used by new integrators.\nThe [Billing Request flow](#billing-requests) API should be used for your payment flows.",
"tags": [
"Redirect Flow"
],
"parameters": [
{
"$ref": "#/components/parameters/GoCardlessVersionHeader"
}
],
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/redirect_flow_single_resource_response"
}
}
},
"description": "Resource created successfully"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "Unauthorised",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "Internal Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"redirect_flows": {
"type": "object",
"additionalProperties": false,
"required": [
"session_token",
"success_redirect_url"
],
"properties": {
"description": {
"$ref": "#/components/schemas/redirect_flow_description"
},
"session_token": {
"$ref": "#/components/schemas/redirect_flow_session_token"
},
"scheme": {
"$ref": "#/components/schemas/redirect_flow_scheme"
},
"success_redirect_url": {
"$ref": "#/components/schemas/redirect_flow_success_redirect_url"
},
"prefilled_customer": {
"type": "object",
"description": "Customer information used to prefill the payment page so your customer doesn't have to re-type details you already hold about them. It will be stored unvalidated and the customer will be able to review and amend it before completing the form.",
"additionalProperties": false,
"properties": {
"email": {
"type": "string",
"nullable": true,
"description": "Customer's email address.",
"example": "user@example.com"
},
"given_name": {
"type": "string",
"nullable": true,
"description": "Customer's first name.",
"example": "Frank"
},
"family_name": {
"type": "string",
"nullable": true,
"description": "Customer's surname.",
"example": "Osborne"
},
"company_name": {
"type": "string",
"nullable": true,
"description": "Customer's company name. Company name should only be provided if `given_name` and `family_name` are null.",
"example": "Hamilton Trading Ltd."
},
"address_line1": {
"type": "string",
"nullable": true,
"description": "The first line of the customer's address.",
"example": "221B Baker Street"
},
"address_line2": {
"type": "string",
"nullable": true,
"description": "The second line of the customer's address.",
"example": "Marylebone"
},
"address_line3": {
"type": "string",
"nullable": true,
"description": "The third line of the customer's address.",
"example": "City of Westminster"
},
"city": {
"type": "string",
"nullable": true,
"description": "The city of the customer's address.",
"example": "London"
},
"region": {
"type": "string",
"nullable": true,
"description": "The customer's address region, county or department.",
"example": "Greater London"
},
"postal_code": {
"type": "string",
"nullable": true,
"description": "The customer's postal code.",
"example": "NW1 6XE"
},
"country_code": {
"type": "string",
"nullable": true,
"description": "[ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)",
"example": "GB"
},
"language": {
"type": "string",
"nullable": true,
"description": "[ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code.",
"example": "en"
},
"phone_number": {
"type": "string",
"nullable": true,
"description": "For New Zealand customers only.",
"example": "+64 4 817 9999"
},
"swedish_identity_number": {
"type": "string",
"nullable": true,
"description": "For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.",
"example": "556564-5404"
},
"danish_identity_number": {
"type": "string",
"nullable": true,
"description": "For Danish customers only. The civic/company number (CPR or CVR) of the customer.",
"example": "220550-6218"
}
}
},
"prefilled_bank_account": {
"type": "object",
"description": "Bank account information used to prefill the payment page so your customer doesn't have to re-type details you already hold about them. It will be stored unvalidated and the customer will be able to review and amend it before completing the form.",
"additionalProperties": false,
"properties": {
"account_type": {
"description": "Bank account type for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](#local-bank-details-united-states) for more information.",
"example": "savings",
"enum": [
"savings",
"checking"
],
"nullable": true,
"type": "string"
}
}
},
"links": {
"type": "object",
"description": "",
"additionalProperties": false,
"properties": {
"creditor": {
"type": "string",
"description": "The [creditor](#core-endpoints-creditors) for whom the mandate will be created. The `name` of the creditor will be displayed on the payment page. Required if your account manages multiple creditors.",
"example": "CR123"
}
}
},
"metadata": {
"$ref": "#/components/schemas/redirect_flow_metadata"
}
}
}
}
}
}
}
},
"deprecated": true,
"x-codeSamples": [
{
"lang": "Ruby",
"label": "Ruby",
"source": "@client.redirect_flows.create(\n params: {\n description: \"Team membership\",\n session_token: \"my_unique_tracking_id\",\n success_redirect_url: \"https://example.com/pay/confirm\",\n prefilled_customer: {\n given_name: \"Frank\",\n family_name: \"Osborne\",\n email: \"frank.osborne@acmeplc.com\"\n }\n }\n)"
},
{
"lang": "Python",
"label": "Python",
"source": "client.redirect_flows.create(params={\n \"description\": \"Wine boxes\",\n \"session_token\": \"SESS_wSs0uGYMISxzqOBq\",\n \"success_redirect_url\": \"https://example.com/pay/confirm\",\n \"prefilled_customer\": {\n \"given_name\": \"Frank\",\n \"family_name\": \"Osborne\",\n \"email\": \"frank.osborne@acmeplc.com\"\n }\n})"
},
{
"lang": "JavaScript",
"label": "JavaScript",
"source": "const redirectFlow = await client.redirectFlows.create({\n description: \"Wine boxes\",\n session_token: \"SESS_wSs0uGYMISxzqOBq\",\n success_redirect_url: \"https://example.com/pay/confirm\",\n prefilled_customer: {\n given_name: \"Frank\",\n family_name: \"Osborne\",\n email: \"frank.osborne@acmeplc.com\"\n }\n});"
},
{
"lang": "PHP",
"label": "PHP",
"source": "$client->redirectFlows()->create([\n \"params\" => [\"description\" => \"Wine boxes\",\n \"session_token\" => \"SESS_wSs0uGYMISxzqOBq\",\n \"success_redirect_url\" => \"https://example.com/pay/confirm\",\n \"prefilled_customer\" => [\n \"given_name\" => \"Frank\",\n \"family_name\" => \"Osborne\",\n \"email\" => \"frank.osborne@acmeplc.com\"\n ]]\n]);"
},
{
"lang": "Java",
"label": "Java",
"source": "RedirectFlow redirectFlow = client.redirectFlows().create()\n .withDescription(\"Wine boxes\")\n .withSessionToken(\"SESS_wSs0uGYMISxzqOBq\")\n .withSuccessRedirectUrl(\"https://example.com/pay/confirm\")\n .withPrefilledCustomerGivenName(\"Frank\")\n .withPrefilledCustomerFamilyName(\"Osborne\")\n .withPrefilledCustomerEmail(\"frank.osborne@acmeplc.com\")\n .execute();"
},
{
"lang": "Go",
"label": "Go",
"source": "redirectFlowCreateParams := gocardless.RedirectFlowCreateParams{\n Description: \"Cider Barrels\",\n Links: &gocardless.RedirectFlowCreateParamsLinks{\n Creditor: \"CR00006A7FRJA5\",\n },\n PrefilledCustomer: &gocardless.RedirectFlowCreateParamsPrefilledCustomer{\n AddressLine1: \"338-346 Goswell Road\",\n City: \"London\",\n GivenName: \"Tim\",\n FamilyName: \"Rogers\",\n Email: \"tim@gocardless.com\",\n PostalCode: \"EC1V 7LQ\",\n },\n Scheme: \"bacs\",\n SessionToken: \"dummy_session_token\",\n SuccessRedirectUrl: \"https://developer.gocardless.com/example-redirect-uri/\",\n}\n\nredirectFlow, err := client.RedirectFlows.Create(ctx, redirectFlowCreateParams)"
},
{
"lang": "C#",
"label": ".NET",
"source": "var prefilledCustomer = new GoCardless.Services.RedirectFlowCreateRequest.RedirectFlowPrefilledCustomer()\n{\n AddressLine1 = \"338 Goswell Road\",\n Email = \"api@gocardless.com\",\n GivenName = \"Bobby\",\n FamilyName = \"Tables\"\n};\n\nvar redirectFlowRequest = new GoCardless.Services.RedirectFlowCreateRequest()\n{\n Description = \"Gold package\",\n SessionToken = \"SESS_wSs0uGYMISxzqOBq\",\n SuccessRedirectUrl = \"https://example.com/pay/confirm\",\n PrefilledCustomer = prefilledCustomer\n};\n\nvar redirectFlowResponse = await client.RedirectFlows.CreateAsync(redirectFlowRequest);\nGoCardless.Resources.RedirectFlow redirectFlow = redirectFlowResponse.RedirectFlow;\n\nConsole.WriteLine(redirectFlow.RedirectUrl);"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "POST https://api.gocardless.com/redirect_flows HTTP/1.1\nContent-Type: application/json\n{\n \"redirect_flows\": {\n \"description\": \"Wine boxes\",\n \"session_token\": \"SESS_wSs0uGYMISxzqOBq\",\n \"success_redirect_url\": \"https://example.com/pay/confirm\",\n \"prefilled_customer\": {\n \"given_name\": \"Frank\",\n \"family_name\": \"Osborne\",\n \"email\": \"frank.osborne@acmeplc.com\"\n },\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /redirect_flows/RE123\nContent-Type: application/json\n{\n \"redirect_flows\": {\n \"id\": \"RE123\",\n \"description\": \"Wine boxes\",\n \"session_token\": \"SESS_wSs0uGYMISxzqOBq\",\n \"scheme\": null,\n \"success_redirect_url\": \"https://example.com/pay/confirm\",\n \"redirect_url\": \"http://pay.gocardless.com/flow/RE123\",\n \"created_at\": \"2014-10-22T13:10:06.000Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}"
}
]
}
},
"/redirect_flows/{redirect_flow_id}": {
"get": {
"operationId": "get_redirect_flows",
"summary": "Get a single redirect flow",
"description": "Returns all details about a single redirect flow\n\n**Deprecated:** Redirect Flows are legacy APIs and cannot be used by new integrators.\nThe [Billing Request flow](#billing-requests) API should be used for your payment flows.",
"tags": [
"Redirect Flow"
],
"parameters": [
{
"$ref": "#/components/parameters/GoCardlessVersionHeader"
},
{
"name": "redirect_flow_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The redirect flow id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/redirect_flow_single_resource_response"
}
}
},
"description": "Successful response"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "Unauthorised",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "Internal Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
}
},
"deprecated": true,
"x-codeSamples": [
{
"lang": "Ruby",
"label": "Ruby",
"source": "@client.redirect_flows.get(\"RE123\")"
},
{
"lang": "Python",
"label": "Python",
"source": "client.redirect_flows.get(\"RE123\")"
},
{
"lang": "JavaScript",
"label": "JavaScript",
"source": "const redirectFlow = await client.redirectFlows.find(\"RE123\");"
},
{
"lang": "PHP",
"label": "PHP",
"source": "$client->redirectFlows()->get(\"RE123\");"
},
{
"lang": "Java",
"label": "Java",
"source": "RedirectFlow redirectFlow = client.redirectFlows().get(\"RE123\").execute();"
},
{
"lang": "Go",
"label": "Go",
"source": "redirectFlow, err := client.RedirectFlows.Get(ctx, \"RE123\")"
},
{
"lang": "C#",
"label": ".NET",
"source": "var redirectFlowResponse = await client.RedirectFlows.GetAsync(\"RE123\");\nGoCardless.Resources.RedirectFlow redirectFlow = redirectFlowResponse.RedirectFlow;"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "GET https://api.gocardless.com/redirect_flows/RE123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"redirect_flows\": {\n \"id\": \"RE123\",\n \"description\": \"Wine boxes\",\n \"session_token\": \"SESS_wSs0uGYMISxzqOBq\",\n \"scheme\": null,\n \"success_redirect_url\": \"https://example.com/pay/confirm\",\n \"redirect_url\": \"http://pay.gocardless.com/flow/RE123\",\n \"created_at\": \"2014-10-22T13:10:06.000Z\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}"
}
]
}
},
"/redirect_flows/{redirect_flow_id}/actions/complete": {
"post": {
"operationId": "complete_redirect_flow",
"summary": "Complete a redirect flow",
"description": "This creates a [customer](#core-endpoints-customers), [customer bank account](#core-endpoints-customer-bank-accounts), and [mandate](#core-endpoints-mandates) using the details supplied by your customer and returns the ID of the created mandate.\n\nThis will return a `redirect_flow_incomplete` error if your customer has not yet been redirected back to your site, and a `redirect_flow_already_completed` error if your integration has already completed this flow. It will return a `bad_request` error if the `session_token` differs to the one supplied when the redirect flow was created.\n\n**Deprecated:** Redirect Flows are legacy APIs and cannot be used by new integrators.\nThe [Billing Request flow](#billing-requests) API should be used for your payment flows.",
"tags": [
"Redirect Flow"
],
"parameters": [
{
"$ref": "#/components/parameters/GoCardlessVersionHeader"
},
{
"name": "redirect_flow_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The redirect flow id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/redirect_flow_single_resource_response"
}
}
},
"description": "Action completed successfully"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "Unauthorised",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "Internal Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/error"
}
},
"required": [
"error"
]
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"redirect_flows": {
"type": "object",
"additionalProperties": false,
"required": [
"session_token"
],
"properties": {
"session_token": {
"$ref": "#/components/schemas/redirect_flow_session_token"
}
}
}
}
}
}
}
},
"deprecated": true,
"x-codeSamples": [
{
"lang": "Ruby",
"label": "Ruby",
"source": "@client.redirect_flows.complete(\n \"RE123\",\n params: {\n session_token: \"my_unique_tracking_id\"\n }\n)"
},
{
"lang": "Python",
"label": "Python",
"source": "client.redirect_flows.complete(\"RE123\", params={\n \"session_token\": \"SESS_wSs0uGYMISxzqOBq\"\n})"
},
{
"lang": "JavaScript",
"label": "JavaScript",
"source": "const redirectFlowResponse = await client.redirectFlows.complete(\n \"RE123\",\n {\n session_token: \"SESS_wSs0uGYMISxzqOBq\"\n }\n)"
},
{
"lang": "PHP",
"label": "PHP",
"source": "$client->redirectFlows()->complete(\"RE123\", [\n \"params\" => [\"session_token\" => \"SESS_wSs0uGYMISxzqOBq\"]\n]);"
},
{
"lang": "Java",
"label": "Java",
"source": "client.redirectFlows().complete(\"RE123\")\n .withSessionToken(\"SESS_wSs0uGYMISxzqOBq\")\n .execute();"
},
{
"lang": "Go",
"label": "Go",
"source": "redirectFlowCompleteParams := gocardless.RedirectFlowCompleteParams{\n SessionToken: \"dummy_session_token\",\n}\n\nredirectFlow, err := client.RedirectFlows.Complete(ctx, \"RE0003QNP5DE2101R80QZHJ2X12P93Q4\", redirectFlowCompleteParams)"
},
{
"lang": "C#",
"label": ".NET",
"source": "var redirectFlowRequest = new GoCardless.Services.RedirectFlowCompleteRequest()\n{\n SessionToken = \"SESS_wSs0uGYMISxzqOBq\"\n};\n\nvar redirectFlowResponse = await client.RedirectFlows.CompleteAsync(\"RE123\", redirectFlowRequest);"
},
{
"lang": "HTTP",
"label": "HTTP",
"source": "POST https://api.gocardless.com/redirect_flows/RE123/actions/complete HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"session_token\": \"SESS_wSs0uGYMISxzqOBq\"\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"redirect_flows\": {\n \"id\": \"RE123\",\n \"description\": \"Wine boxes\",\n \"session_token\": \"SESS_wSs0uGYMISxzqOBq\",\n \"scheme\": null,\n \"success_redirect_url\": \"https://example.com/pay/confirm\",\n \"confirmation_url\": \"https://pay.gocardless.com/flow/RE123/success\",\n \"created_at\": \"2014-10-22T13:10:06.000Z\",\n \"mandate_reference\": \"AB1YZ\",\n \"links\": {\n \"creditor\": \"CR123\",\n \"mandate\": \"MD123\",\n \"customer\": \"CU123\",\n \"customer_bank_account\": \"BA123\"\n }\n }\n}"
}
]
}
},
"/refunds": {
"post": {
"operationId": "create_refund",
"summary": "Create a refund",
"description": "Creates a new refund object.\n\nThis fails with:\n\n- `total_amount_confirmation_invalid` if the confirmation amount doesn't match the total amount refunded for the payment. This safeguard is there to prevent two processes from creating refunds without awareness of each other.\n\n- `available_refund_amount_insufficient` if the creditor does not have sufficient balance for refunds available to cover the cost of the requested refund.\n\n\nRestricted: This endpoint is disabled by default. To enable it, you will need to enable refunds on your GoCardless Dashboard.
\n\nWarning: A payment that has been (partially) refunded can still receive a late failure or chargeback from the customer's bank.
\nA refund can only be created once it is outside the safer refund period (7 calendar days after the charge date) otherwise an error is returned. The safer refund period can be disabled by contacting GoCardless.
Restricted: You must request access to Mandate Refunds by contacting our support team.
" } ] } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.refunds.create(\n params: {\n amount: 100,\n total_amount_confirmation: 150,\n reference: \"Service refund\",\n metadata: { reason: \"Late delivery\" },\n links: { payment: \"PM123\"}\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.refunds.create(params={\n \"amount\": 100,\n \"total_amount_confirmation\": 150,\n \"reference\": \"Acme refund\",\n \"metadata\": {\n \"reason\": \"late delivery\"\n },\n \"links\": {\n \"payment\": \"PM123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const refund = await client.refunds.create({\n amount: 100,\n total_amount_confirmation: 150,\n reference: \"Acme refund\",\n metadata: {\n reason: \"late delivery\"\n },\n links: {\n payment: \"PM123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->refunds()->create([\n \"params\" => [\"amount\" => 100,\n \"total_amount_confirmation\" => 150,\n \"reference\" => \"Acme refund\",\n \"metadata\" => [\"reason\" => \"Late delivery\"],\n \"links\" => [\"payment\" => \"PM123\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.refunds().create()\n .withAmount(100)\n .withTotalAmountConfirmation(150)\n .withReference(\"Acme refund\")\n .withMetadata(\"reason\", \"late delivery\")\n .withLinksPayment(\"PM123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "refundCreateParams := gocardless.RefundCreateParams{\n Amount: 100,\n TotalAmountConfirmation: 150,\n Reference: \"Acme refund\",\n Metadata: map[string]string{\"reason\": \"late delivery\"},\n Links: gocardless.RefundCreateParamsLinks{\n Payment: \"PM123\",\n },\n}\n\nrefund, err := client.Refunds.Create(ctx, refundCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var refundRequest = new GoCardless.Services.RefundCreateRequest()\n{\n Amount = 100,\n TotalAmountConfirmation = 150,\n Reference = \"Partial refund\",\n Links = new GoCardless.Services.RefundCreateRequest.RefundLinks()\n {\n Payment = \"PM0123\"\n }\n};\nvar refundResponse = await client.Refunds.CreateAsync(refundRequest);\nGoCardless.Resources.Refund refund = refundResponse.Refund;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/refunds HTTP/1.1\nContent-Type: application/json\n{\n \"refunds\": {\n \"amount\": 100,\n \"total_amount_confirmation\": 150,\n \"reference\": \"Acme refund\",\n \"metadata\": {\n \"reason\": \"late delivery\"\n },\n \"links\": {\n \"payment\": \"PM123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /payments/RF123\nContent-Type: application/json\n{\n \"refunds\": {\n \"id\": \"RF123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"reference\": \"Acme refund\",\n \"fx\": {\n \"fx_currency\": \"EUR\",\n \"fx_amount\": null,\n \"exchange_rate\": null,\n \"estimated_exchange_rate\": \"1.1234567890\"\n },\n \"status\": \"created\",\n \"metadata\": {\n \"reason\": \"late delivery\"\n },\n \"links\": {\n \"payment\": \"PM123\"\n }\n }\n}\n\n// Or, if the creditor does not have a sufficient balance to create the refund:\nHTTP/1.1 422 Validation Failed\nContent-Type: application/json\n{\n \"error\": {\n \"message\": \"It’s not possible to process this refund because you don’t have enough funds in GBP. Your available refund amount for payments in GBP is: 0.9 GBP\",\n \"errors\": [\n {\n \"reason\": \"available_refund_amount_insufficient\",\n \"message\": \"It’s not possible to process this refund because you don’t have enough funds in GBP. Your available refund amount for payments in GBP is: 0.9 GBP\",\n \"metadata\": {\n \"available_refund_amount\": 90\n }\n }\n ],\n \"documentation_url\": \"https://developer.gocardless.com/api-reference#available_refund_amount_insufficient\",\n \"type\": \"validation_failed\",\n \"request_id\": \"...\",\n \"code\": 422\n }\n}" } ] }, "get": { "operationId": "list_refund", "summary": "List refunds", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your refunds.", "tags": [ "Refund" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true }, { "name": "payment", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/payment_identity" } }, { "name": "mandate", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/mandate_identity" } }, { "name": "refund_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/refund_refund_type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.refunds.list\n\n@client.refunds.list(params: { payment: \"PM123\" })\n\n@client.refunds.list.records.each { |refund| puts refund.inspect }" }, { "lang": "Python", "label": "Python", "source": "client.refunds.list().records\n\nclient.refunds.list(params={\"payment\": \"PM123\"}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const refunds = await client.refunds.list();\n\n// List all refunds associated with a given mandate.\nconst mandateRefunds = await client.refunds.list({ mandate: \"MD0123\" });" }, { "lang": "PHP", "label": "PHP", "source": "$client->refunds()->list();\n\n$client->refunds()->list([\n \"params\" => [\"payment\" => \"PM123\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "for (Refund refund : client.refunds().all().withPayment(\"PM123\").execute()) {\n System.out.println(refund.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "refundListParams := gocardless.RefundListParams{\n Mandate: \"MD123\",\n}\nrefundListResult, err := client.Refunds.List(ctx, refundListParams)\nfor _, refund := range refundListResult.Refunds {\n fmt.Println(refund.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var refundRequest = new GoCardless.Services.RefundListRequest()\n{\n Mandate = \"MD0123\"\n};\n\nvar refundListResponse = client.Refunds.All(refundRequest);\nforeach (GoCardless.Resources.Refund refund in refundListResponse)\n{\n Console.WriteLine(refund.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/refunds HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"refunds\": [{\n \"id\": \"RF123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"reference\": \"Acme refund\",\n \"fx\": {\n \"fx_currency\": \"EUR\",\n \"fx_amount\": null,\n \"exchange_rate\": null,\n \"estimated_exchange_rate\": \"1.1234567890\"\n },\n \"status\": \"created\",\n \"metadata\": {\n \"reason\": \"late failure\"\n },\n \"links\": {\n \"payment\": \"PM123\"\n }\n }]\n}" } ] } }, "/refunds/{refund_id}": { "get": { "operationId": "get_refunds", "summary": "Get a single refund", "description": "Retrieves all details for a single refund", "tags": [ "Refund" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "refund_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The refund id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.refunds.get(\"RF123\")" }, { "lang": "Python", "label": "Python", "source": "client.refunds.get(\"RF123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const refund = await client.refunds.find(\"RF123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->refunds()->get(\"RF123\");" }, { "lang": "Java", "label": "Java", "source": "Refund refund = client.refunds().get(\"RF123\").execute();" }, { "lang": "Go", "label": "Go", "source": "refund, err := client.Refunds.Get(ctx, \"RF123\")" }, { "lang": "C#", "label": ".NET", "source": "var refundResponse = await client.Refunds.GetAsync(\"RF0123\");\nGoCardless.Resources.Refund refund = refundResponse.Refund;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/refunds/RF123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"refunds\": {\n \"id\": \"RF123\",\n \"created_at\": \"2014-05-08T17:01:06.000Z\",\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"reference\": \"Acme refund\",\n \"fx\": {\n \"fx_currency\": \"EUR\",\n \"fx_amount\": null,\n \"exchange_rate\": null,\n \"estimated_exchange_rate\": \"1.1234567890\"\n },\n \"status\": \"created\",\n \"metadata\": {\n \"reason\": \"late failure\"\n },\n \"links\": {\n \"payment\": \"PM123\"\n }\n }\n}" } ] }, "put": { "operationId": "update_refunds", "summary": "Update a refund", "description": "Updates a refund object.", "tags": [ "Refund" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "refund_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The refund id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refunds": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.refunds.update(\n \"RF123\",\n params: {\n metadata: { reason: \"Late delivery\", internal_code: \"refund_1A\" }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.refunds.update(\"RF123\", params={\n \"metadata\": {\"key\": \"value\"}\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const refund = await client.refunds.update(\n \"RF123\",\n {\n metadata: {\n key: \"value\"\n }\n }\n);" }, { "lang": "PHP", "label": "PHP", "source": "$client->refunds()->update(\"RF123\", [\n \"params\" => [\"metadata\" => [\"key\" => \"value\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.refunds().update(\"RF123\")\n .withMetadata(\"internal_code\", \"refund_1A\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "refundUpdateParams := gocardless.RefundUpdateParams{\n Metadata: map[string]string{\"key\": \"value\"},\n}\nrefund, err := client.Refunds.Update(ctx, \"RF123\", refundUpdateParams)" }, { "lang": "C#", "label": ".NET", "source": "var refundRequest = new GoCardless.Services.RefundUpdateRequest()\n{\n Metadata = new DictionaryRestricted: This endpoint is restricted to GoCardless Embed customers. Please [contact us](https://forms.gocardless.com/l/305971/2023-01-25/535t8n){:target=\"_blank\"} if you are interested in using this product.
", "tags": [ "Scheme Identifier" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scheme_identifier_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scheme_identifiers": { "type": "object", "additionalProperties": false, "required": [ "name", "scheme" ], "properties": { "name": { "$ref": "#/components/schemas/scheme_identifier_name" }, "scheme": { "$ref": "#/components/schemas/scheme_identifier_scheme" }, "links": { "type": "object", "description": "", "properties": { "creditor": { "type": "string", "description": "required ID of the associated [creditor](#core-endpoints-creditors).\n", "example": "CR123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.scheme_identifiers.create(\n params: {\n scheme: \"bacs\",\n name: \"Example Ltd\",\n links: {\n creditor: \"CR123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.scheme_identifiers.create(params={\n \"scheme\": \"bacs\",\n \"name\": \"Example Ltd\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const schemeIdentifier = await client.schemeIdentifiers.create({\n scheme: \"bacs\",\n name: \"The Wine Club\",\n links: {\n creditor: \"CR123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->schemeIdentifiers()->create([\n 'params' => ['scheme' => 'bacs',\n 'name' => 'Example Ltd',\n 'links' => ['creditor' => 'CR123']\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.SchemeIdentifierService.SchemeIdentifierCreateRequest.Scheme;\n\nSchemeIdentifier schemeIdentifier = client.schemeIdentifiers().create()\n .withScheme(Scheme.BACS)\n .withName(\"The Wine Club\")\n .withLinksCreditor(\"CR123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "schemeIdentifierCreateParams := gocardless.SchemeIdentifierCreateParams{\n Name: \"Durian Co\",\n Scheme: \"bacs\",\n Links: &gocardless.SchemeIdentifierCreateParamsLinks{\n Creditor: \"CR123\",\n },\n}\nschemeIdentifier, err := client.SchemeIdentifiers.Create(ctx, schemeIdentifierCreateParams)\nif err != nil {\n fmt.Printf(\"error creating scheme identifier: %s\", err.Error())\n return\n}" }, { "lang": "C#", "label": ".NET", "source": "var schemeIdentifierRequest = new GoCardless.Services.SchemeIdentifierCreateRequest\n{\n Name = \"The Wine Club\",\n Scheme = GoCardless.Services.SchemeIdentifierCreateRequest.SchemeIdentifierScheme.Bacs,\n Links = new GoCardless.Services.SchemeIdentifierCreateRequest.SchemeIdentifierLinks()\n {\n Creditor = \"CR123\"\n }\n};\n\nvar schemeIdentifierResponse = await client.SchemeIdentifiers.CreateAsync(schemeIdentifierRequest);\n\nGoCardless.Resources.SchemeIdentifier schemeIdentifier = schemeIdentifierResponse.SchemeIdentifier;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/scheme_identifiers HTTP/1.1\nContent-Type: application/json\n{\n \"scheme_identifiers\": {\n \"name\": \"The Wine Club\",\n \"scheme\": \"bacs\",\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}\nHTTP/1.1 201 Created\nLocation: /scheme_identifiers/SU123\nContent-Type: application/json\n{\n \"scheme_identifiers\": {\n \"id\": \"SU123\",\n \"created_at\": \"2021-01-23T13:44:19.006Z\",\n \"name\": \"The Wine Club\",\n \"scheme\": \"bacs\",\n \"reference\": \"REF123\",\n \"status\": \"pending\",\n \"minimum_advance_notice\": 3,\n \"can_specify_mandate_reference\": false,\n \"currency\": \"GBP\",\n \"address_line1\": \"65 Goswell Road\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": \"London\",\n \"region\": null,\n \"postal_code\": \"EC1V 7EN\",\n \"country_code\": \"GB\",\n \"email\": \"name@example.com\",\n \"phone_number\": \"+44 20 8338 9540\"\n }\n}" } ] }, "get": { "operationId": "list_scheme_identifier", "summary": "List scheme identifiers", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your scheme identifiers.", "tags": [ "Scheme Identifier" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "creditor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/creditor_identity" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scheme_identifier_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.scheme_identifiers.list.records" }, { "lang": "Python", "label": "Python", "source": "client.scheme_identifiers.list().records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const schemeIdentifierList = await client.schemeIdentifiers.list();" }, { "lang": "PHP", "label": "PHP", "source": "$client->schemeIdentifiers()->list()->records;" }, { "lang": "Java", "label": "Java", "source": "for (SchemeIdentifier schemeIdentifier: client.schemeIdentifiers().all().execute()) {\n System.out.println(schemeIdentifier.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "schemeIdentifierListParams := gocardless.SchemeIdentifierListParams{}\n\nschemeIdentifeirListResult, err := client.SchemeIdentifiers.List(ctx, schemeIdentifierListParams)\nif err != nil {\n fmt.Printf(\"error listing scheme identifiers: %s\", err.Error())\n return\n}\nfor _, schemeIdentifier := range schemeIdentifeirListResult.SchemeIdentifiers {\n fmt.Println(schemeIdentifier.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var schemeIdentifierListResponse = client.SchemeIdentifiers.All();\n\nforeach (GoCardless.Resources.SchemeIdentifier schemeIdentifier in schemeIdentifierListResponse)\n{\n Console.WriteLine(schemeIdentifier.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/scheme_identifiers HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"scheme_identifiers\": [\n {\n \"id\": \"SU123\",\n \"created_at\": \"2021-01-23T09:41:36.234Z\",\n \"name\": \"The Wine Club\",\n \"scheme\": \"bacs\",\n \"reference\": \"REF123\",\n \"status\": \"active\",\n \"minimum_advance_notice\": 3,\n \"can_specify_mandate_reference\": false,\n \"currency\": \"GBP\",\n \"address_line1\": \"65 Goswell Road\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": \"London\",\n \"region\": null,\n \"postal_code\": \"EC1V 7EN\",\n \"country_code\": \"GB\",\n \"email\": \"name@example.com\",\n \"phone_number\": \"+44 20 8338 9540\"\n }\n ],\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n }\n}" } ] } }, "/scheme_identifiers/{scheme_identifier_id}": { "get": { "operationId": "get_scheme_identifiers", "summary": "Get a single scheme identifier", "description": "Retrieves the details of an existing scheme identifier.", "tags": [ "Scheme Identifier" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "scheme_identifier_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The scheme identifier id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scheme_identifier_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.scheme_identifiers.get(\"SU123\")" }, { "lang": "Python", "label": "Python", "source": "client.scheme_identifiers.get(\"SU123\").attributes" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const schemeIdentifier = await client.schemeIdentifiers.find(\"SU123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->schemeIdentifiers()->get('SU123');" }, { "lang": "Java", "label": "Java", "source": "SchemeIdentifier schemeIdentifier = client.schemeIdentifiers().get(\"SU123\").execute();" }, { "lang": "Go", "label": "Go", "source": "schemeIdentifier, err := client.SchemeIdentifiers.Get(ctx, \"SU123\")\nif err != nil {\n fmt.Printf(\"error getting scheme identifier: %s\", err.Error())\n return\n}" }, { "lang": "C#", "label": ".NET", "source": "var schemeIdentifierResponse = await client.SchemeIdentifiers.GetAsync(\"SU123\");\n\nGoCardless.Resources.SchemeIdentifier schemeIdentifier = schemeIdentifierResponse.SchemeIdentifier;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/scheme_identifiers/SU123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"scheme_identifiers\": {\n \"id\": \"SU123\",\n \"created_at\": \"2021-01-23T09:41:36.234Z\",\n \"name\": \"The Wine Club\",\n \"scheme\": \"bacs\",\n \"reference\": \"REF123\",\n \"status\": \"active\",\n \"minimum_advance_notice\": 3,\n \"can_specify_mandate_reference\": false,\n \"currency\": \"GBP\",\n \"address_line1\": \"65 Goswell Road\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": \"London\",\n \"region\": null,\n \"postal_code\": \"EC1V 7EN\",\n \"country_code\": \"GB\",\n \"email\": \"name@example.com\",\n \"phone_number\": \"+44 20 8338 9540\"\n }\n}" } ] } }, "/subscriptions": { "post": { "operationId": "create_subscription", "summary": "Create a subscription", "description": "Creates a new subscription object", "tags": [ "Subscription" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "object", "additionalProperties": false, "required": [ "amount", "currency", "interval_unit", "links" ], "properties": { "amount": { "$ref": "#/components/schemas/subscription_amount_stringable" }, "name": { "$ref": "#/components/schemas/subscription_name" }, "start_date": { "$ref": "#/components/schemas/subscription_start_date" }, "count": { "$ref": "#/components/schemas/subscription_count_stringable" }, "end_date": { "$ref": "#/components/schemas/subscription_end_date" }, "interval": { "$ref": "#/components/schemas/subscription_interval_stringable" }, "interval_unit": { "$ref": "#/components/schemas/subscription_interval_unit" }, "day_of_month": { "$ref": "#/components/schemas/subscription_day_of_month_stringable" }, "month": { "$ref": "#/components/schemas/subscription_month" }, "currency": { "$ref": "#/components/schemas/subscription_currency" }, "payment_reference": { "$ref": "#/components/schemas/subscription_payment_reference" }, "app_fee": { "$ref": "#/components/schemas/subscription_app_fee_stringable" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "retry_if_possible": { "$ref": "#/components/schemas/subscription_retry_if_possible" }, "links": { "type": "object", "description": "", "additionalProperties": false, "required": [ "mandate" ], "properties": { "mandate": { "type": "string", "description": "ID of the associated [mandate](#core-endpoints-mandates) which the subscription will create payments against.", "example": "MD123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.subscriptions.create(\n params: {\n amount: 2500,\n currency: \"GBP\",\n name: \"Monthly magazine\",\n interval_unit: \"monthly\",\n day_of_month: 1,\n links: {\n mandate: \"MD123\"\n }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.subscriptions.create(params={\n \"amount\": \"2500\",\n \"currency\": \"GBP\",\n \"name\": \"Monthly Magazine\",\n \"interval_unit\": \"monthly\",\n \"day_of_month\": \"1\",\n \"metadata\": {\n \"order_no\": \"ABCD1234\"\n },\n \"links\": {\n \"mandate\": \"MA123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const subscription = await client.subscriptions.create({\n amount: 2500,\n currency: \"GBP\",\n name: \"Monthly Magazine\",\n interval_unit: \"monthly\",\n day_of_month: 1,\n metadata: {\n order_no: \"ABCD1234\"\n },\n links: {\n mandate: \"MA123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->subscriptions()->create([\n \"params\" => [\"amount\" => 2500,\n \"currency\" => \"GBP\",\n \"name\" => \"Monthly Magazine\",\n \"interval_unit\" => \"monthly\",\n \"day_of_month\" => 1,\n \"metadata\" => [\"order_no\" => \"ABCD1234\"],\n \"links\" => [\"mandate\" => \"MA123\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.SubscriptionService.SubscriptionCreateRequest.IntervalUnit;\n\nSubscription subscription = client.subscriptions().create()\n .withAmount(2500)\n .withCurrency(\"GBP\")\n .withName(\"Monthly Magazine\")\n .withIntervalUnit(IntervalUnit.MONTHLY)\n .withDayOfMonth(1)\n .withMetadata(\"order_no\", \"ABCD1234\")\n .withLinksMandate(\"MD123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "subscriptionCreateParams := gocardless.SubscriptionCreateParams{\n Amount: 1500, // 15 GBP in pence\n Currency: \"GBP\",\n IntervalUnit: \"monthly\",\n DayOfMonth: 5,\n Links: gocardless.SubscriptionCreateParamsLinks{\n Mandate: \"MD123\",\n },\n Metadata: map[string]string{\"subscription_number\": \"ABC123\"},\n}\n\nsubscription, err := client.Subscriptions.Create(ctx, subscriptionCreateParams)" }, { "lang": "C#", "label": ".NET", "source": "var subscriptionRequest = new GoCardless.Services.SubscriptionCreateRequest()\n{\n Amount = 1000,\n Currency = \"GBP\",\n Name = \"Monthly subscription\",\n Interval = 1,\n IntervalUnit = GoCardless.Services.SubscriptionCreateRequest.SubscriptionIntervalUnit.Monthly,\n Links = new GoCardless.Services.SubscriptionCreateRequest.SubscriptionLinks()\n {\n Mandate = \"MD0123\"\n }\n};\n\nvar subscriptionResponse = await client.Subscriptions.CreateAsync(subscriptionRequest);\nGoCardless.Resources.Subscription subscription = subscriptionResponse.Subscription;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/subscriptions HTTP/1.1\nContent-Type: application/json\n{\n \"subscriptions\": {\n \"amount\": \"2500\",\n \"currency\": \"GBP\",\n \"name\": \"Monthly Magazine\",\n \"interval_unit\": \"monthly\",\n \"day_of_month\": \"1\",\n \"metadata\": {\n \"order_no\": \"ABCD1234\"\n },\n \"links\": {\n \"mandate\": \"MA123\"\n }\n }\n}\n\nHTTP/1.1 201 Created\nLocation: /subscriptions/SB123\nContent-Type: application/json\n{\n \"subscriptions\": {\n \"id\": \"SB123\",\n \"created_at\": \"2014-10-20T17:01:06.000Z\",\n \"amount\": 2500,\n \"currency\": \"GBP\",\n \"status\": \"active\",\n \"name\": \"Monthly Magazine\",\n \"start_date\": \"2014-11-03\",\n \"end_date\": null,\n \"interval\": 1,\n \"interval_unit\": \"monthly\",\n \"day_of_month\": 1,\n \"month\": null,\n \"payment_reference\": null,\n \"app_fee\": null,\n \"earliest_charge_date_after_resume\": null,\n \"upcoming_payments\": [\n { \"charge_date\": \"2014-11-03\", \"amount\": 2500 },\n { \"charge_date\": \"2014-12-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-01-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-02-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-03-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-04-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-05-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-06-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-07-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-08-03\", \"amount\": 2500 }\n ],\n \"metadata\": {\n \"order_no\": \"ABCD1234\"\n },\n \"links\": {\n \"mandate\": \"MA123\"\n },\n \"retry_if_possible\": false\n }\n}" } ] }, "get": { "operationId": "list_subscription", "summary": "List subscriptions", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your subscriptions. Please note if the subscriptions are related to customers who have been removed, they will not be shown in the response.", "tags": [ "Subscription" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true }, { "name": "mandate", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/mandate_identity" } }, { "name": "customer", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/customer_identity" } }, { "name": "status", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "array" }, { "type": "string" } ] }, "description": "Up to 5 of:\n\n- `pending_customer_approval`\n- `customer_approval_denied`\n- `active`\n- `finished`\n- `cancelled`\n- `paused`\n\nOmit entirely to include subscriptions in all states." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.subscriptions.list\n\n@client.subscriptions.list(params: { customer: \"CU123\" })\n\n@client.subscriptions.list.records.each { |subscription| puts subscription.inspect }" }, { "lang": "Python", "label": "Python", "source": "client.subscriptions.list().records\n\nclient.subscriptions.list(params={\"customer\": \"CU123\"}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const subscriptions = await client.subscriptions.list();\n\n// List all subscriptions associated with a given customer.\nconst customerSubscriptions = await client.subscriptions.list({ customer: \"CU123\" });" }, { "lang": "PHP", "label": "PHP", "source": "$client->subscriptions()->list();\n\n$client->subscriptions()->list([\n \"params\" => [\"customer\" => \"CU123\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "for (Subscription subscription : client.subscriptions().all().withCustomer(\"CU123\").execute()) {\n System.out.println(subscription.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "subscriptionListParams := gocardless.SubscriptionListParams{}\nsubscriptionListResult, err := client.Subscriptions.List(ctx, subscriptionListParams)\nfor _, subscription := range subscriptionListResult.Subscriptions {\n fmt.Println(subscription.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var subscriptionRequest = new GoCardless.Services.SubscriptionListRequest()\n{\n Customer = \"CU000123\"\n};\n\nvar subscriptionListResponse = client.Subscriptions.All(subscriptionRequest);\nforeach (GoCardless.Resources.Subscription subscription in subscriptionListResponse)\n{\n Console.WriteLine(subscription.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/subscriptions HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"before\": null,\n \"after\": null\n },\n \"limit\": 50\n },\n \"subscriptions\": [{\n \"id\": \"SB123\",\n \"created_at\": \"2014-10-20T17:01:06.000Z\",\n \"amount\": 2500,\n \"currency\": \"GBP\",\n \"status\": \"active\",\n \"name\": \"Monthly Magazine\",\n \"start_date\": \"2014-11-03\",\n \"end_date\": null,\n \"interval\": 1,\n \"interval_unit\": \"monthly\",\n \"day_of_month\": 1,\n \"month\": null,\n \"payment_reference\": null,\n \"earliest_charge_date_after_resume\": null,\n \"parent_plan_paused\": false,\n \"upcoming_payments\": [\n { \"charge_date\": \"2014-11-03\", \"amount\": 2500 },\n { \"charge_date\": \"2014-12-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-01-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-02-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-03-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-04-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-05-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-06-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-07-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-08-03\", \"amount\": 2500 }\n ],\n \"metadata\": {\n \"order_no\": \"ABCD1234\"\n },\n \"links\": {\n \"mandate\": \"MA123\"\n },\n \"retry_if_possible\": false\n }]\n}" } ] } }, "/subscriptions/{subscription_id}": { "get": { "operationId": "get_subscriptions", "summary": "Get a single subscription", "description": "Retrieves the details of a single subscription.", "tags": [ "Subscription" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The subscription id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.subscriptions.get(\"SB123\")" }, { "lang": "Python", "label": "Python", "source": "client.subscriptions.get(\"SB123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const subscription = await client.subscriptions.find(\"SB123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->subscriptions()->get(\"SB123\");" }, { "lang": "Java", "label": "Java", "source": "Subscription subscription = client.subscriptions().get(\"SB123\").execute();" }, { "lang": "Go", "label": "Go", "source": "subscription, err := client.Subscriptions.Get(ctx, \"SB123\")" }, { "lang": "C#", "label": ".NET", "source": "var subscriptionResponse = await client.Subscriptions.GetAsync(\"SB0123\");\nGoCardless.Resources.Subscription subscription = subscriptionResponse.Subscription;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/subscriptions/SB123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"subscriptions\": {\n \"id\": \"SB123\",\n \"created_at\": \"2014-10-20T17:01:06.000Z\",\n \"amount\": 2500,\n \"currency\": \"GBP\",\n \"status\": \"active\",\n \"name\": \"Monthly Magazine\",\n \"start_date\": \"2014-11-03\",\n \"end_date\": null,\n \"interval\": 1,\n \"interval_unit\": \"monthly\",\n \"day_of_month\": 1,\n \"month\": null,\n \"payment_reference\": null,\n \"earliest_charge_date_after_resume\": null,\n \"parent_plan_paused\": false,\n \"upcoming_payments\": [\n { \"charge_date\": \"2014-11-03\", \"amount\": 2500 },\n { \"charge_date\": \"2014-12-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-01-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-02-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-03-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-04-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-05-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-06-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-07-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-08-03\", \"amount\": 2500 }\n ],\n \"metadata\": {\n \"order_no\": \"ABCD1234\"\n },\n \"links\": {\n \"mandate\": \"MA123\"\n },\n \"retry_if_possible\": false\n }\n}" } ] }, "put": { "operationId": "update_subscriptions", "summary": "Update a subscription", "description": "Updates a subscription object.\n\nThis fails with:\n\n- `validation_failed` if invalid data is provided when attempting to update a subscription.\n\n- `subscription_not_active` if the subscription is no longer active.\n\n- `subscription_already_ended` if the subscription has taken all payments.\n\n- `mandate_payments_require_approval` if the amount is being changed and the mandate requires approval.\n\n- `number_of_subscription_amendments_exceeded` error if the subscription amount has already been changed 10 times.\n\n- `forbidden` if the amount is being changed, and the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app\n\n- `resource_created_by_another_app` if the app fee is being changed, and the subscription was created by an app other than the app you are authenticated as\n", "tags": [ "Subscription" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The subscription id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "object", "additionalProperties": false, "properties": { "name": { "$ref": "#/components/schemas/subscription_name" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" }, "payment_reference": { "$ref": "#/components/schemas/subscription_payment_reference" }, "amount": { "$ref": "#/components/schemas/subscription_amount_stringable" }, "app_fee": { "$ref": "#/components/schemas/subscription_app_fee_stringable" }, "retry_if_possible": { "$ref": "#/components/schemas/subscription_retry_if_possible" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.subscriptions.update(\n \"SB123\",\n params: {\n metadata: { order_no: \"ABCD4321\" }\n }\n)" }, { "lang": "Python", "label": "Python", "source": "client.subscriptions.update(\"SB123\", params={\n \"name\": \"New name\"\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const subscription = await client.subscriptions.update(\n \"SB123\",\n {\n amount: 42,\n name: \"New Name\"\n }\n);" }, { "lang": "PHP", "label": "PHP", "source": "$client->subscriptions()->update(\"SB123\", [\n \"params\" => [\"name\" => \"New name\",\n \"metadata\" => [\"order_no\" => \"ABCD4321\"]]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.subscriptions().update(\"SB123\")\n .withName(\"New name\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "subscriptionUpdateParams := gocardless.SubscriptionUpdateParams{\n Amount: 4200,\n Name: \"New Name\",\n}\n\nsubscription, err := client.Subscriptions.Update(ctx, \"SB123\", subscriptionUpdateParams)" }, { "lang": "C#", "label": ".NET", "source": "var subscriptionRequest = new GoCardless.Services.SubscriptionUpdateRequest()\n{\n Metadata = new DictionaryWarning: Please note that any payments that have already been created from this\nsubscription will still be collected unless you manually cancel them.
", "tags": [ "Subscription" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The subscription id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "object", "additionalProperties": false, "properties": { "pause_cycles": { "$ref": "#/components/schemas/subscription_pause_cycles" }, "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.subscriptions.pause(\"SB123\")" }, { "lang": "Python", "label": "Python", "source": "client.subscriptions.pause(\"SB123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const subscriptionResponse = await client.subscriptions.pause(\"SB123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->subscriptions()->pause(\"SB123\");" }, { "lang": "Java", "label": "Java", "source": "client.subscriptions().pause(\"SB123\").execute();" }, { "lang": "Go", "label": "Go", "source": "subscriptionPauseParams := gocardless.SubscriptionPauseParams{}\nsubscription, err := client.Subscriptions.Pause(ctx, \"SB123\",subscriptionPauseParams)" }, { "lang": "C#", "label": ".NET", "source": "var subscriptionResponse = await client.Subscriptions.PauseAsync(\"SB0123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/subscriptions/SU123/actions/pause HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"metadata\": {}\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"subscriptions\": {\n \"id\": \"SB123\",\n \"created_at\": \"2014-10-20T17:01:06.000Z\",\n \"amount\": 2500,\n \"currency\": \"GBP\",\n \"status\": \"paused\",\n \"name\": \"Subscription name\",\n \"start_date\": \"2014-11-03\",\n \"end_date\": null,\n \"interval\": 1,\n \"interval_unit\": \"monthly\",\n \"day_of_month\": 1,\n \"month\": null,\n \"payment_reference\": null,\n \"earliest_charge_date_after_resume\": \"2014-10-23\",\n \"parent_plan_paused\": false,\n \"upcoming_payments\": [\n ],\n \"metadata\": {\n \"order_no\": \"ABCD4321\"\n },\n \"links\": {\n \"mandate\": \"MA123\"\n },\n \"retry_if_possible\": false\n }\n}" } ] } }, "/subscriptions/{subscription_id}/actions/resume": { "post": { "operationId": "resume_subscription", "summary": "Resume a subscription", "description": "Resume a subscription object.\nPayments will start to be created again based on the subscriptions recurrence rules.\nThe `charge_date` on the next payment will be the same as the subscriptions `earliest_charge_date_after_resume`\n\nThis fails with:\n\n- `forbidden` if the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app\n\n- `validation_failed` if invalid data is provided when attempting to resume a subscription.\n\n- `subscription_not_paused` if the subscription is not paused.\n\n\nWarning: There is a mandatory minimum 14 business day wait between resuming an `AUD` subscription and its next charge date.\nThere is a mandatory minimum 10 calendar day wait between resuming an `NZD` subscription and its next charge date.
", "tags": [ "Subscription" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The subscription id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.subscriptions.resume(\"SB123\")" }, { "lang": "Python", "label": "Python", "source": "client.subscriptions.resume(\"SB123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const subscriptionResponse = await client.subscriptions.resume(\"SB123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->subscriptions()->resume(\"SB123\");" }, { "lang": "Java", "label": "Java", "source": "client.subscriptions().resume(\"SB123\").execute();" }, { "lang": "Go", "label": "Go", "source": "subscriptionResumeParams := gocardless.SubscriptionResumeParams{}\nsubscription, err := client.Subscriptions.Resume(ctx, \"SB123\", subscriptionResumeParams)" }, { "lang": "C#", "label": ".NET", "source": "var subscriptionResponse = await client.Subscriptions.ResumeAsync(\"SB0123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/subscriptions/SU123/actions/resume HTTP/1.1\nContent-Type: application/json\n{\n \"data\": {\n \"metadata\": {}\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"subscriptions\": {\n \"id\": \"SB123\",\n \"created_at\": \"2014-10-20T17:01:06.000Z\",\n \"amount\": 2500,\n \"currency\": \"GBP\",\n \"status\": \"active\",\n \"name\": \"Subscription name\",\n \"start_date\": \"2014-11-03\",\n \"end_date\": null,\n \"interval\": 1,\n \"interval_unit\": \"monthly\",\n \"day_of_month\": 1,\n \"month\": null,\n \"payment_reference\": null,\n \"earliest_charge_date_after_resume\": null,\n \"parent_plan_paused\": false,\n \"upcoming_payments\": [\n { \"charge_date\": \"2014-11-03\", \"amount\": 2500 },\n { \"charge_date\": \"2014-12-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-01-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-02-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-03-02\", \"amount\": 2500 },\n { \"charge_date\": \"2015-04-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-05-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-06-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-07-01\", \"amount\": 2500 },\n { \"charge_date\": \"2015-08-03\", \"amount\": 2500 }\n ],\n \"metadata\": {\n \"order_no\": \"ABCD4321\"\n },\n \"links\": {\n \"mandate\": \"MA123\"\n },\n \"retry_if_possible\": false\n }\n}" } ] } }, "/subscriptions/{subscription_id}/actions/cancel": { "post": { "operationId": "cancel_subscription", "summary": "Cancel a subscription", "description": "Immediately cancels a subscription; no more payments will be created under it. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.\n\nThis will fail with a cancellation_failed error if the subscription is already cancelled or finished.\n\nWarning: Please note that this will not cancel any payments that have already been created\nfrom this subscription — these payments will still be collected unless you also\nmanually cancel them.
", "tags": [ "Subscription" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The subscription id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/customer_metadata" } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.subscriptions.cancel(\"SB123\")" }, { "lang": "Python", "label": "Python", "source": "client.subscriptions.cancel(\"SB123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const subscriptions = await client.subscriptions.cancel(\"SB123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->subscriptions()->cancel(\"SB123\");" }, { "lang": "Java", "label": "Java", "source": "client.subscriptions().cancel(\"SB123\").execute();" }, { "lang": "Go", "label": "Go", "source": "subscriptionCancelParams := gocardless.SubscriptionCancelParams{}\nsubscription, err := client.Subscriptions.Cancel(ctx, \"SB123\", subscriptionCancelParams)" }, { "lang": "C#", "label": ".NET", "source": "var subscriptionResponse = await client.Subscriptions.CancelAsync(\"SB0123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/subscriptions/SU123/actions/cancel HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"subscriptions\": {\n \"id\": \"SB123\",\n \"created_at\": \"2014-10-20T17:01:06.000Z\",\n \"amount\": 2500,\n \"currency\": \"GBP\",\n \"status\": \"cancelled\",\n \"name\": \"Monthly Magazine\",\n \"start_date\": \"2014-11-03\",\n \"end_date\": null,\n \"interval\": 1,\n \"interval_unit\": \"monthly\",\n \"day_of_month\": 1,\n \"month\": null,\n \"payment_reference\": null,\n \"earliest_charge_date_after_resume\": null,\n \"parent_plan_paused\": false,\n \"upcoming_payments\": [],\n \"metadata\": {\n \"order_no\": \"ABCD1234\"\n },\n \"links\": {\n \"mandate\": \"MA123\"\n },\n \"retry_if_possible\": false\n }\n}" } ] } }, "/tax_rates": { "get": { "operationId": "list_tax_rate", "summary": "List tax rates", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of all tax rates.", "tags": [ "Tax Rate" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "jurisdiction", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/tax_rate_jurisdiction" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tax_rate_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.tax_rates.list(params: { jurisdiction: \"GB\" })" }, { "lang": "Python", "label": "Python", "source": "client.tax_rates.list(params={\"jurisdiction\": \"GB\" }).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const taxRates = await client.taxRates.list();\n\n// List the Tax rate for a jurisdiction.\nconst taxRatesFiltered = await client.taxRates.list({ jurisdiction: 'GB'});" }, { "lang": "PHP", "label": "PHP", "source": "$client->taxRates()->list([\n \"params\" => [\"jurisdiction\" => \"GB\"]\n]);" }, { "lang": "Java", "label": "Java", "source": "client.taxRates().all().withJurisdiction(\"GB\").execute();" }, { "lang": "Go", "label": "Go", "source": "taxRateListParams := gocardless.TaxRateListParams{\n Jurisdiction: \"GB\",\n}\n\ntaxRateListResult, err := client.TaxRates.List(ctx, taxRateListParams)" }, { "lang": "C#", "label": ".NET", "source": "var request = new GoCardless.Services.TaxRateListRequest()\n{\n Jurisdiction = \"GB\",\n};\n\nvar response = client.TaxRates.All(request);\nforeach (GoCardless.Resources.TaxRate rate in response)\n{\n Console.WriteLine(rate.Percentage);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/tax_rates?jurisdiction=GB HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"tax_rates\": [\n {\n \"id\": \"GB_VAT_1\",\n \"jurisdiction\": \"GB\",\n \"type\": \"VAT\",\n \"percentage\": \"20.0\",\n \"start_date\": \"2020-02-24\",\n \"end_date\": null\n }\n ],\n \"meta\": {\n \"cursors\": {\n \"after\": null,\n \"before\": null\n },\n \"limit\": 50\n }\n}" } ] } }, "/tax_rates/{tax_rate_id}": { "get": { "operationId": "get_tax_rates", "summary": "Get a single tax rate", "description": "Retrieves the details of a tax rate.", "tags": [ "Tax Rate" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "tax_rate_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The tax rate id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tax_rate_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.tax_rates.get(\"GB_VAT_1\")" }, { "lang": "Python", "label": "Python", "source": "client.tax_rates.get(\"GB_VAT_1\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const taxRate = await client.taxRates.find(\"GB_VAT_1\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->taxRates()->get(\"GB_VAT_1\");" }, { "lang": "Java", "label": "Java", "source": "TaxRate taxRate = client.taxRates().get(\"GB_VAT_1\").execute();" }, { "lang": "Go", "label": "Go", "source": "taxRate, err := client.TaxRates.Get(ctx, \"GB_VAT_1\")" }, { "lang": "C#", "label": ".NET", "source": "var taxRateResponse = await client.TaxRates.GetAsync(\"GB_VAT_1\");\nGoCardless.Resources.TaxRate taxRate = taxRateResponse.TaxRate;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/tax_rates/GB_VAT_1 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"tax_rates\": {\n \"id\": \"GB_VAT_1\",\n \"jurisdiction\": \"GB\",\n \"type\": \"VAT\",\n \"percentage\": \"20.0\",\n \"start_date\": \"2020-02-24\",\n \"end_date\": null\n }\n}" } ] } }, "/transferred_mandates/{mandate_id}": { "get": { "operationId": "get_transferred_mandates", "summary": "Get updated customer bank details", "description": "Returns new customer bank details for a mandate that's been recently transferred\n\nRestricted: This endpoint is restricted to organisations with the Transfer Bank Accounts upgrade
\n\nNote: See our [Security Requirements](#appendix-security-requirements) before using this feature
", "tags": [ "Transferred Mandate" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "mandate_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The mandate id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transferred_mandate_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.transferred_mandates.transferred_mandates(\"MD123\")" }, { "lang": "Python", "label": "Python", "source": "client.transferred_mandates.transferred_mandates(\"MD123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const transferredMandate = await client.transferredMandates.transferredMandates(\"MD123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->transferredMandates()->transferredMandates(\"MD123\");" }, { "lang": "Java", "label": "Java", "source": "client.transferredMandates().transferredMandates(\"MD123\").execute();" }, { "lang": "Go", "label": "Go", "source": "transferredMandate, err := client.TransferredMandates.TransferredMandates(ctx, \"MD123\", gocardless.TransferredMandateTransferredMandatesParams{})" }, { "lang": "C#", "label": ".NET", "source": "var response = await client.TransferredMandates.TransferredMandatesAsync(\"MD123\");\nGoCardless.Resources.TransferredMandate transferredMandate = response.TransferredMandate;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/transferred_mandates/MD123 HTTP/1.1\nContent-Type: application/json\n\nHTTP/1.1 200 (OK)\nLocation: /transferred_mandates/MD123\nContent-Type: application/json\n{\n \"transferred_mandates\": {\n \"encrypted_decryption_key\": \"bXktZW5jcnlvcHRlZC1hZXMta2V5\",\n \"public_key_id\": \"9770a024c90fb646e48c952ec5d4f53586e62e8154048e6b96dd9f74f164a472\",\n \"encrypted_customer_bank_details\": \"OTc3MGEwMjRjOTBmYjY0NmU0OGM5NTJlYzVkNGY1MzU4NmU2MmU4MTU0MDQ4ZTZiOTZkZDlmNzRmMTY0YTQ3Mg==\",\n \"links\": {\n \"customer_bank_account\": \"BA123\",\n \"mandate\": \"MD123\"\n }\n }\n}" } ] } }, "/verification_details": { "post": { "operationId": "create_verification_detail", "summary": "Create a verification detail", "description": "Creates a new verification detail\n\nWarning: This endpoint only supports UK based limited companies. Therefore the\ncreditor's `creditor_type` must be `'company'` and `country_code` must be `'GB'`.
", "tags": [ "Verification Detail" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/verification_detail_single_resource_response" } } }, "description": "Resource created successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "verification_details": { "type": "object", "additionalProperties": false, "required": [ "links", "name", "company_number", "description", "address_line1", "city", "postal_code", "directors" ], "properties": { "name": { "$ref": "#/components/schemas/verification_detail_name" }, "company_number": { "$ref": "#/components/schemas/verification_detail_company_number" }, "description": { "$ref": "#/components/schemas/verification_detail_description" }, "address_line1": { "$ref": "#/components/schemas/verification_detail_address_line1" }, "address_line2": { "$ref": "#/components/schemas/verification_detail_address_line2" }, "address_line3": { "$ref": "#/components/schemas/verification_detail_address_line3" }, "city": { "$ref": "#/components/schemas/verification_detail_city" }, "postal_code": { "$ref": "#/components/schemas/verification_detail_postal_code" }, "directors": { "$ref": "#/components/schemas/verification_detail_directors" }, "links": { "type": "object", "description": "", "required": [ "creditor" ], "properties": { "creditor": { "type": "string", "description": "ID of the associated [creditor](#core-endpoints-creditors).", "example": "CR123" } } } } } } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.verification_details.create(params: {\n name: \"Acme\",\n company_number: \"03768189\",\n address_line1: \"12 Drury lane\",\n city: \"London\",\n description: \"wine and cheese seller\",\n postal_code: \"B4 7NJ\",\n directors: [{\n given_name: \"Gandalf\",\n family_name: \"Grey\",\n city: \"London\",\n date_of_birth: \"1986-02-19\",\n street: \"Drury lane\",\n postal_code: \"B4 7NJ\",\n country_code: \"GB\",\n }],\n links: {\n creditor: \"CR123\",\n },\n})" }, { "lang": "Python", "label": "Python", "source": "client.verification_details.create(params={\n \"name\": \"Acme\",\n \"company_number\": \"03768189\",\n \"address_line1\": \"12 Drury lane\",\n \"city\": \"London\",\n \"description\": \"wine and cheese seller\",\n \"postal_code\": \"B4 7NJ\",\n \"directors\": [{\n \"given_name\": \"Gandalf\",\n \"family_name\": \"Grey\",\n \"city\": \"London\",\n \"date_of_birth\": \"1986-02-19\",\n \"street\": \"Drury lane\",\n \"postal_code\": \"B4 7NJ\",\n \"country_code\": \"GB\"\n }],\n \"links\": {\n \"creditor\": \"CR123\"\n }\n})" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const verificationDetail = await client.verificationDetails.create({\n name: \"Acme\",\n company_number: \"03768189\",\n address_line1: \"12 Drury lane\",\n city: \"London\",\n description: \"wine and cheese seller\",\n postal_code: \"B4 7NJ\",\n directors: [{\n given_name: \"Gandalf\",\n family_name: \"Grey\",\n city: \"London\",\n date_of_birth: \"1986-02-19\",\n street: \"Drury lane\",\n postal_code: \"B4 7NJ\",\n country_code: \"GB\"\n }],\n links: {\n creditor: \"CR123\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$verification_details = $client->verificationDetails()->create([\n 'params' => [\n 'name' => 'Acme',\n 'company_number' => '03768189',\n 'address_line1' => '12 Drury lane',\n 'city' => 'London',\n 'description' => 'wine and cheese seller',\n 'postal_code' => 'B4 7NJ',\n 'directors' => [[\n 'given_name' => 'Gandalf',\n 'family_name' => 'Grey',\n 'city' => 'London',\n 'date_of_birth' => '1986-02-19',\n 'street' => 'Drury lane',\n 'postal_code' => 'B4 7NJ',\n 'country_code' => 'GB'\n ]],\n 'links' => [\n 'creditor' => 'CR123'\n ]\n ]\n]);" }, { "lang": "Java", "label": "Java", "source": "import com.gocardless.services.VerificationDetailService.VerificationDetailCreateRequest.Directors;\n\nDirectors director = new Directors();\n\ndirector.withCity(\"London\");\ndirector.withCountryCode(\"GB\");\ndirector.withDateOfBirth(\"1986-02-19\");\ndirector.withGivenName(\"Gandalf\");\ndirector.withFamilyName(\"Grey\");\ndirector.withPostalCode(\"B4 7NJ\");\ndirector.withStreet(\"Drury Lane\");\n\nVerificationDetail verificationDetail = client.verificationDetails().create()\n .withName(\"Acme\")\n .withDescription(\"wine and cheese seller\")\n .withCompanyNumber(\"03768189\")\n .withAddressLine1(\"12 Drury Lane\")\n .withCity(\"London\")\n .withPostalCode(\"B4 7NJ\")\n .withDirectors(director)\n .withLinksCreditor(\"CR123\")\n .execute();" }, { "lang": "Go", "label": "Go", "source": "verificationDetailCreateParams := gocardless.VerificationDetailCreateParams{\n Name: \"Acme\",\n CompanyNumber: \"03768189\",\n AddressLine1: \"12 Drury lane\",\n City: \"London\",\n Description: \"wine and cheese seller\",\n PostalCode: \"B4 7NJ\",\n Directors: []gocardless.VerificationDetailCreateParamsDirectors{\n {\n GivenName: \"Gandalf\",\n FamilyName: \"Grey\",\n City: \"London\",\n DateOfBirth: \"1986-02-19\",\n Street: \"Drury Lane\",\n PostalCode: \"B4 7NJ\",\n CountryCode: \"GB\",\n },\n },\n Links: gocardless.VerificationDetailCreateParamsLinks{\n Creditor: \"CR123\",\n },\n}\n\nverificationDetail, err := client.VerificationDetails.Create(ctx, verificationDetailCreateParams)\nif err != nil {\n fmt.Printf(\"error creating verification detail: %s\", err.Error())\n return\n}" }, { "lang": "C#", "label": ".NET", "source": "var verificationDetailCreateRequest = new GoCardless.Services.VerificationDetailCreateRequest()\n{\n Name = \"Acme\",\n CompanyNumber = \"03768189\",\n AddressLine1 = \"12 Drury lane\",\n City = \"London\",\n Description = \"wine and cheese seller\",\n PostalCode = \"B4 7NJ\",\n Directors = new GoCardless.Services.VerificationDetailCreateRequest.VerificationDetailDirectors[]\n {\n new GoCardless.Services.VerificationDetailCreateRequest.VerificationDetailDirectors\n {\n GivenName = \"Gandalf\",\n FamilyName = \"Grey\",\n City = \"London\",\n DateOfBirth = \"1986-02-19\",\n Street = \"Drury lane\",\n PostalCode = \"B4 7NJ\",\n CountryCode = \"GB\"\n }\n },\n Links = new GoCardless.Services.VerificationDetailCreateRequest.VerificationDetailLinks()\n {\n Creditor = \"CR123\"\n }\n};\n\nvar verificationDetailResponse = await client.VerificationDetails.CreateAsync(verificationDetailCreateRequest);\n\nvar verificationDetail = verificationDetailResponse.VerificationDetail;" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/verification_details/ HTTP/1.1\nContent-Type: application/json\n{\n \"verification_details\": {\n \"name\": \"Acme Limited\",\n \"company_number\": \"03768189\",\n \"description\": \"wine and cheese seller\",\n \"address_line1\": \"12 Drury lane\",\n \"city\": \"London\",\n \"postal_code\": \"B4 7NJ\",\n \"directors\": [{\n \"date_of_birth\": \"1986-02-19\",\n \"given_name\": \"Gandalf\",\n \"family_name\": \"Grey\",\n \"city\": \"London\",\n \"street\": \"Drury Lane\",\n \"postal_code\": \"B4 7NJ\",\n \"country_code\": \"GB\"\n }],\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"verification_details\": {\n \"name\": \"Acme Limited\",\n \"company_number\": \"03768189\",\n \"description\": \"wine and cheese seller\",\n \"address_line1\": \"12 Drury lane\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": \"London\",\n \"region\": null,\n \"postal_code\": \"B4 7NJ\",\n \"country_code\": \"GB\",\n \"directors\": [{\n \"given_name\": \"Gandalf\",\n \"family_name\": \"Grey\",\n \"date_of_birth\": \"1986-02-19\",\n \"street\": \"Drury lane\",\n \"city\": \"London\",\n \"postal_code\": \"B4 7NJ\",\n \"country_code\": \"GB\"\n }],\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }\n}" } ] }, "get": { "operationId": "list_verification_detail", "summary": "List verification details", "description": "Returns a list of verification details belonging to a creditor.", "tags": [ "Verification Detail" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "creditor", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/creditor_identity" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/verification_detail_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.verification_details.list(params: {\n creditor: \"CR123\",\n}).records" }, { "lang": "Python", "label": "Python", "source": "client.verification_details.list(params={\n \"creditor\": \"CR123\"\n}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const verificationDetailList = await client.verificationDetails.list({ creditor: \"CR123\" });" }, { "lang": "PHP", "label": "PHP", "source": "$response = $client->verificationDetails()->list([\n 'params' => [\n 'creditor' => 'CR123'\n ]\n])->records;" }, { "lang": "Java", "label": "Java", "source": "for (VerificationDetail verificationDetail: client.verificationDetails().all().withCreditor(\"CR123\").execute()){\n System.out.println(verificationDetail.getDescription());\n}" }, { "lang": "Go", "label": "Go", "source": "verificationDetailListParams := gocardless.VerificationDetailListParams{\n Creditor: \"CR123\",\n}\nverificationDetailList, err := client.VerificationDetails.List(ctx, verificationDetailListParams)\nif err != nil {\n fmt.Printf(\"error listing verification details: %+v\", err)\n return\n}\n\nfor _, verificationDetail := range verificationDetailList.VerificationDetails {\n fmt.Println(verificationDetail.Name)\n fmt.Println(verificationDetail.Description)\n}" }, { "lang": "C#", "label": ".NET", "source": "var verificationDetailListRequest = new GoCardless.Services.VerificationDetailListRequest()\n{\n Creditor = \"CR123\"\n};\n\nvar verificationDetailListResponse = client.VerificationDetails.All(verificationDetailListRequest);\nforeach (var verificationDetail in verificationDetailListResponse)\n{\n Console.WriteLine(verificationDetail.Description);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/verification_details?creditor=CR123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"verification_details\": [{\n \"name\": \"Acme Limited\",\n \"company_number\": \"03768189\",\n \"description\": \"wine and cheese seller\",\n \"address_line1\": \"12 Drury lane\",\n \"address_line2\": null,\n \"address_line3\": null,\n \"city\": \"London\",\n \"region\": null,\n \"postal_code\": \"B4 7NJ\",\n \"country_code\": \"GB\",\n \"directors\": [{\n \"given_name\": \"Gandalf\",\n \"family_name\": \"Grey\",\n \"date_of_birth\": \"1986-02-19\",\n \"street\": \"Drury lane\",\n \"city\": \"London\",\n \"postal_code\": \"B4 7NJ\",\n \"country_code\": \"GB\"\n }],\n \"links\": {\n \"creditor\": \"CR123\"\n }\n }]\n}" } ] } }, "/webhooks": { "get": { "operationId": "list_webhook", "summary": "List webhooks", "description": "Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your webhooks.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the end of the desired set." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Cursor pointing to the start of the desired set." }, { "name": "limit", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Number of records to return." }, { "name": "created_at", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": false, "properties": { "gt": { "type": "string", "description": "Limit to records created after the specified date-time.", "format": "date-time" }, "lt": { "type": "string", "description": "Limit to records created before the specified date-time.", "format": "date-time" }, "gte": { "type": "string", "description": "Limit to records created on or after the specified date-time.", "format": "date-time" }, "lte": { "type": "string", "description": "Limit to records created on or before the specified date-time.", "format": "date-time" } } }, "style": "deepObject", "explode": true }, { "name": "successful", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "true", "false" ], "type": "string" }, { "type": "boolean" } ] }, "description": "Show only successful/failed webhooks" }, { "name": "is_test", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "true", "false" ], "type": "string" }, { "type": "boolean" } ] }, "description": "Show only test/non test webhooks" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_multi_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.webhooks.list\n\n@client.webhooks.list(params: { successful: true })" }, { "lang": "Python", "label": "Python", "source": "client.webhooks.list().records\n\nclient.webhooks.list(params={\"successful\": True}).records" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const webhooks = await client.webhooks.list();\n\n// List all webhooks past a certain date.\nconst filteredWebhooks = await client.webhooks.list({\n created_at: {\n gt: \"2020-01-01T17:01:06.000Z\"\n }\n});" }, { "lang": "PHP", "label": "PHP", "source": "$client->webhooks()->list();\n\n$client->webhooks()->list([\n \"params\" => [\"successful\" => True]\n]);" }, { "lang": "Java", "label": "Java", "source": "for (com.gocardless.resources.Webhook webhook : client.webhooks().all().withSuccessful(true).execute()) {\n System.out.println(webhook.getId());\n}" }, { "lang": "Go", "label": "Go", "source": "webhookListParams := gocardless.WebhookListParams{\n CreatedAt: &gocardless.WebhookListParamsCreatedAt{\n Gt: \"2020-01-01T17:01:06.000Z\",\n },\n}\n\nwebhookListResult, err := client.Webhooks.List(ctx, webhookListParams)\nfor _, webhook := range webhookListResult.Webhooks {\n fmt.Println(webhook.Id)\n}" }, { "lang": "C#", "label": ".NET", "source": "var webhookRequest = new GoCardless.Services.WebhookListRequest()\n{\n Successful = true\n};\n\nvar webhookListResponse = client.Webhooks.All(webhookRequest);\nforeach (GoCardless.Resources.Webhook webhook in webhookListResponse)\n{\n Console.WriteLine(webhook.Id);\n}" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/webhooks/WB123?successful=true HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"meta\": {\n \"cursors\": {\n \"after\": null,\n \"before\": null\n },\n \"limit\": 5\n },\n \"webhooks\": [{\n \"created_at\": \"2018-03-12T15:13:37.416Z\",\n \"id\": \"WB123\",\n \"is_test\": true,\n \"request_body\": \"{\\\"events\\\":[{\\\"id\\\":\\\"EV123\\\",\\\"created_at\\\":\\\"2018-03-12T15:13:37.158Z\\\",\\\"resource_type\\\":\\\"payments\\\",\\\"action\\\":\\\"created\\\",\\\"links\\\":{\\\"payment\\\":\\\"PM123\\\"},\\\"details\\\":{\\\"origin\\\":\\\"api\\\",\\\"cause\\\":\\\"payment_created\\\",\\\"description\\\":\\\"Payment created via the API.\\\"},\\\"metadata\\\":{}}]}\",\n \"request_headers\": {\n \"Content-Type\": \"application/json\",\n \"Origin\": \"https://api.gocardless.com\",\n \"User-Agent\": \"gocardless-webhook-service/1.1\",\n \"Webhook-Signature\": \"e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365\"\n },\n \"response_body\": \"ok\",\n \"response_body_truncated\": false,\n \"response_code\": 200,\n \"response_headers\": {\n \"content-type\": \"text/html; charset=utf-8\",\n \"date\": \"Mon, 12 Mar 2018 15:13:37 GMT\"\n },\n \"response_headers_content_truncated\": false,\n \"response_headers_count_truncated\": false,\n \"successful\": true,\n \"url\": \"https://example.com/webhook_handler\"\n }]\n}" } ] } }, "/webhooks/{webhook_id}": { "get": { "operationId": "get_webhooks", "summary": "Get a single webhook", "description": "Retrieves the details of an existing webhook.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The webhook id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_single_resource_response" } } }, "description": "Successful response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.webhooks.get(\"WB123\")" }, { "lang": "Python", "label": "Python", "source": "client.webhooks.get(\"WB123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const webhook = await client.webhooks.find(\"WB123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->webhooks()->get(\"WB123\");" }, { "lang": "Java", "label": "Java", "source": "com.gocardless.resources.Webhook webhook = client.webhooks().get(\"WB123\").execute();" }, { "lang": "Go", "label": "Go", "source": "webhook, err := client.Webhooks.Get(ctx, \"WB123\")" }, { "lang": "C#", "label": ".NET", "source": "var webhookResponse = await client.Webhooks.GetAsync(\"WB123\");\nGoCardless.Resources.Webhook webhook = webhookResponse.Webhook;" }, { "lang": "HTTP", "label": "HTTP", "source": "GET https://api.gocardless.com/webhooks/WB123 HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"webhooks\": {\n \"created_at\": \"2018-03-12T15:13:37.416Z\",\n \"id\": \"WB123\",\n \"is_test\": true,\n \"request_body\": \"{\\\"events\\\":[{\\\"id\\\":\\\"EV123\\\",\\\"created_at\\\":\\\"2018-03-12T15:13:37.158Z\\\",\\\"resource_type\\\":\\\"payments\\\",\\\"action\\\":\\\"created\\\",\\\"links\\\":{\\\"payment\\\":\\\"PM123\\\"},\\\"details\\\":{\\\"origin\\\":\\\"api\\\",\\\"cause\\\":\\\"payment_created\\\",\\\"description\\\":\\\"Payment created via the API.\\\"},\\\"metadata\\\":{}}]}\",\n \"request_headers\": {\n \"Content-Type\": \"application/json\",\n \"Origin\": \"https://api.gocardless.com\",\n \"User-Agent\": \"gocardless-webhook-service/1.1\",\n \"Webhook-Signature\": \"e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365\"\n },\n \"response_body\": \"ok\",\n \"response_body_truncated\": false,\n \"response_code\": 200,\n \"response_headers\": {\n \"content-type\": \"text/html; charset=utf-8\",\n \"date\": \"Mon, 12 Mar 2018 15:13:37 GMT\"\n },\n \"response_headers_content_truncated\": false,\n \"response_headers_count_truncated\": false,\n \"successful\": true,\n \"url\": \"https://example.com/webhook_handler\"\n }\n}" } ] } }, "/webhooks/{webhook_id}/actions/retry": { "post": { "operationId": "retry_webhook", "summary": "Retry a webhook", "description": "Requests for a previous webhook to be sent again", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/GoCardlessVersionHeader" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The webhook id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_single_resource_response" } } }, "description": "Action completed successfully" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/error" } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "Ruby", "label": "Ruby", "source": "@client.webhooks.retry(\"WB123\")" }, { "lang": "Python", "label": "Python", "source": "client.webhooks.retry(\"WB123\")" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const webhookResponse = await client.webhooks.retry(\"WB123\");" }, { "lang": "PHP", "label": "PHP", "source": "$client->webhooks()->retry(\"WB123\");" }, { "lang": "Java", "label": "Java", "source": "client.webhooks().retry(\"WB123\").execute();" }, { "lang": "Go", "label": "Go", "source": "webhook, err := client.Webhooks.Retry(ctx, \"WB123\")" }, { "lang": "C#", "label": ".NET", "source": "var webhookResponse = await client.Webhooks.RetryAsync(\"WB123\");" }, { "lang": "HTTP", "label": "HTTP", "source": "POST https://api.gocardless.com/webhooks/WB123/actions/retry HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n \"webhooks\": {\n \"created_at\": \"2018-03-12T15:13:37.416Z\",\n \"id\": \"WB123\",\n \"is_test\": true,\n \"request_body\": \"{\\\"events\\\":[{\\\"id\\\":\\\"EV123\\\",\\\"created_at\\\":\\\"2018-03-12T15:13:37.158Z\\\",\\\"resource_type\\\":\\\"payments\\\",\\\"action\\\":\\\"created\\\",\\\"links\\\":{\\\"payment\\\":\\\"PM123\\\"},\\\"details\\\":{\\\"origin\\\":\\\"api\\\",\\\"cause\\\":\\\"payment_created\\\",\\\"description\\\":\\\"Payment created via the API.\\\"},\\\"metadata\\\":{}}]}\",\n \"request_headers\": {\n \"Content-Type\": \"application/json\",\n \"Origin\": \"https://api.gocardless.com\",\n \"User-Agent\": \"gocardless-webhook-service/1.1\",\n \"Webhook-Signature\": \"e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365\"\n },\n \"response_body\": \"ok\",\n \"response_body_truncated\": false,\n \"response_code\": 200,\n \"response_headers\": {\n \"content-type\": \"text/html; charset=utf-8\",\n \"date\": \"Mon, 12 Mar 2018 15:13:37 GMT\"\n },\n \"response_headers_content_truncated\": false,\n \"response_headers_count_truncated\": false,\n \"successful\": true,\n \"url\": \"https://example.com/webhook_handler\"\n }\n}" } ] } } } }