GOgocardless
Billing Request

Create a Billing Request

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.

Warning: 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.

post/billing_requests

Request

  • Base URL
    https://api.gocardless.com
  • Auth
    HTTP bearer

Headers

GoCardless-Versionstring required

Request body

Example request

{
  "billing_requests": {
    "account_information_request": {
      "country_code": "GB"
    },
    "mandate_request": {
      "currency": "GBP",
      "scheme": "bacs",
      "reference": "REF-123",
      "description": "Top-up Payment"
    },
    "payment_request": {
      "description": "Top-up Payment",
      "currency": "GBP",
      "scheme": "faster_payments",
      "reference": "some-custom-ref"
    },
    "subscription_request": {
      "currency": "EUR",
      "interval_unit": "monthly",
      "month": "january",
      "name": "12 month subscription",
      "payment_reference": "GOLDPLAN",
      "start_date": "2014-10-21"
    },
    "instalment_schedule_request": {
      "name": "Invoice 4404",
      "currency": "USD",
      "payment_reference": "GOLDPLAN",
      "instalments_with_dates": [
        {
          "amount": 250,
          "charge_date": "2020-11-03"
        }
      ],
      "instalments_with_schedule": {
        "start_date": "2014-10-21",
        "interval": 1,
        "interval_unit": "monthly"
      }
    },
    "links": {
      "customer": "CU123",
      "customer_bank_account": "BA123",
      "creditor": "CR123"
    }
  }
}

Response

Resource created successfully

Example response

{
  "billing_requests": {
    "id": "BRQ123",
    "created_at": "2015-01-01T12:00:00.000Z",
    "status": "pending",
    "account_information_request": {
      "country_code": "GB"
    },
    "mandate_request": {
      "description": "Top-up Payment",
      "currency": "GBP",
      "scheme": "bacs"
    },
    "payment_request": {
      "description": "Top-up Payment",
      "currency": "GBP",
      "scheme": "faster_payments",
      "amount": 1000,
      "app_fee": 100,
      "reference": "some-custom-ref"
    },
    "subscription_request": {
      "amount": 1000,
      "currency": "USD",
      "interval_unit": "monthly",
      "interval": 1,
      "app_fee": 100,
      "count": 5,
      "day_of_month": 28,
      "month": "january",
      "name": "12 month subscription",
      "payment_reference": "GOLDPLAN",
      "start_date": "2014-10-21"
    },
    "instalment_schedule_request": {
      "name": "Invoice 4404",
      "currency": "USD",
      "total_amount": 1000,
      "payment_reference": "GOLDPLAN",
      "app_fee": 100,
      "instalments_with_dates": [
        {
          "amount": 250,
          "charge_date": "2020-11-03"
        }
      ],
      "instalments_with_schedule": {
        "start_date": "2014-10-21",
        "interval": 1,
        "interval_unit": "monthly",
        "amounts": [
          1000
        ]
      }
    },
    "actions": [
      {
        "type": "collect_bank_account",
        "status": "pending",
        "required": true,
        "completes_actions": [
          "collect_bank_account"
        ],
        "requires_actions": [
          "collect_bank_account"
        ],
        "available_currencies": [
          "GBP"
        ],
        "available_country_codes": [
          "GB"
        ],
        "institution_guess_status": "pending"
      }
    ],
    "resources": {
      "customer": {
        "id": "CU123",
        "created_at": "2014-01-01T12:00:00.000Z",
        "email": "user@example.com",
        "given_name": "Frank",
        "family_name": "Osborne",
        "company_name": "Hamilton Trading Ltd.",
        "language": "en",
        "phone_number": "+64 4 817 9999"
      },
      "customer_billing_detail": {
        "id": "CU123",
        "created_at": "2014-01-01T12:00:00.000Z",
        "address_line1": "221B Baker Street",
        "address_line2": "Marylebone",
        "address_line3": "City of Westminster",
        "city": "London",
        "region": "Greater London",
        "postal_code": "NW1 6XE",
        "country_code": "GB",
        "swedish_identity_number": "556564-5404",
        "danish_identity_number": "2205506218",
        "ip_address": "127.0.0.1"
      },
      "customer_bank_account": {
        "id": "BA123",
        "created_at": "2014-01-01T12:00:00.000Z",
        "account_holder_name": "Billie Jean",
        "account_number_ending": "1234",
        "account_type": "savings",
        "country_code": "GB",
        "currency": "EUR",
        "bank_name": "BARCLAYS BANK PLC",
        "enabled": true,
        "bank_account_token": "bat_f975ab3c-ecee-47a1-9590-5bb1d56fa113",
        "payer_name_verification_result": "full"
      }
    },
    "links": {
      "customer": "CU123",
      "creditor": "CR123",
      "organisation": "OR123",
      "customer_bank_account": "BA123",
      "account_information_request": "AIR123",
      "payment_request": "PRQ123",
      "payment_request_payment": "PM123",
      "mandate_request": "MRQ123",
      "mandate_request_mandate": "MD123",
      "subscription_request": "SBR123",
      "subscription_request_subscription": "SB123",
      "instalment_schedule_request": "ISR123",
      "instalment_schedule_request_instalment_schedule": "IS123",
      "payment_provider": "PP123"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.