Welcome to GoCardless Python Library’s documentation!

Contents:

Indices and tables

• Index
• Module Index
• Search Page

The GoCardless Python Client Library

This module provides a wrapper around the GoCardless payments API, the interface to the api is provided by the gocardless.Client object. See the documentation for that class for how to obtain a reference.

By default the library will attempt to use the GoCardless production environment, for testing purposes this is not what you want and you should set the gocardless.environment to “sandbox”.

Once you have obtained an instance of a client you can use that client to generate urls for receiving payments. You can also use it to query the api for information about payments resources using an active resource style API. For example, to get all of a merchants bills:

>>> merchant = client.merchant()
>>> merchant.bills()
>>> [<gocardless.resources.Bill at 0x29a6050>]

gocardless.client = None

The client for merchants to use. Does not exist until gocardless.set_details() has been called.

gocardless.environment = 'production'

The environment GoCardless executes API requests against, should be either “production” or “sandbox”

gocardless.set_details(app_id=None, app_secret=None, access_token=None, merchant_id=None)

Set the global account details to use for requests

The parameters are your security details which can be found on your gocardless developer details page. All are mandatory

class gocardless.Client(app_id, app_secret, access_token=None, merchant_id=None)

The main interface to the GoCardless API

This class is the starting point for interacting with GoCardless. If you are a merchant than you can obtain a client instance by setting your account details in gocardless.set_details().

If you are a partner and need OAuth access to other merchants’ accounts then you need to create a client using your app id and app secret, then use the OAuth APIs to obtain authorization over the merchants’ account.

__init__(app_id, app_secret, access_token=None, merchant_id=None)

Create a client

Parameters:

• app_id (string) – Your application id.
• app_secret (string) – Your app secret.
• access_token (string) – The access token for this account, this should be your access token from the developer settings page unless you are trying to manage another merchants’ account via OAuth.
• merchant_id (string) – The merchant id for this account, should be your merchant id unless you are trying to manage another account via OAuth.

__weakref__

list of weak references to the object (if defined)

api_delete(path, **kwargs)

Issue a delete to the API server.

Parameters:

• path – the path that will be added to the API prefix
• params – query string parameters

api_get(path, **kwargs)

Issue an GET request to the API server.

Parameters:path – the path that will be added to the API prefix

api_post(path, data, **kwargs)

Issue a POST request to the API server

Parameters:

• path – The path that will be added to the API prefix
• data – The data to post to the url.

api_put(path, data={}, **kwargs)

Issue a PUT request to the API server

Parameters:

• path – The path that will be added to the API prefix
• data – The data to put to the url.

bill(id)

Find a bill with id id

confirm_resource(params)

Confirm a payment

This send a post request to the confirmation URI for a payment. params should contain these elements from the request - resource_uri - resource_id - resource_type - signature - state (if any)

create_bill(amount, pre_auth_id, name=None, description=None)

Creates a new bill under an existing pre_authorization

Parameters:

• amount – The amount to bill
• pre_auth_id – The id of an existing pre_authorization which has not expire
• name – A name for this bill
• description – A description for this bill

fetch_access_token(redirect_uri, authorization_code)

Fetch the access token for a merchant

Takes the authorization code obtained from a merchant redirect and the redirect_uri used in that same redirect and fetches the corresponding access token. The access token is returned and also set on the client so the client can then be used to make api calls on behalf of the merchant.

Parameters:

• redirect_uri – The redirect_uri used in the request which obtained the authorization code, must match exactly.
• authorization_code – The authorization code obtained in the previous part of the process.

classmethod get_base_url()

Return the correct base URL for the current environment. If one has been manually set, default to that.

merchant()

Returns the current Merchant’s details.

new_bill_url(amount, name=None, description=None, redirect_uri=None, cancel_uri=None, state=None, user=None)

Generate a url for creating a new bill

Parameters:

• amount – The amount to bill the customer
• name – The name of the bill
• description – The description of the bill
• redirect_uri – URI to redirect to after the authorization process
• cancel_uri – URI to redirect the user to if they cancel authorization
• state – String which will be passed to the merchant on redirect.
• user –

  A dictionary which will be used to prepopulate the sign up form the user sees, this can contain keys:

  • first_name
  • last_name
  • email

new_merchant_url(redirect_uri, state=None, merchant=None)

Get a URL for managing a new merchant

This method creates a URL which partners should redirect merchants to in order to obtain permission to manage their GoCardless payments.

Parameters:

• redirect_uri – The URI where the merchant will be sent after authorizing.
• state – An optional string which will be present in the request to the redirect URI, useful for tracking the user.
• merchant –

  A dictionary which will be used to prepopulate the merchant sign up page, can contain any of the keys:

  • “name”
  • “billing_address_1”
  • “billing_address_2”
  • “billing_town”
  • “billing_county”
  • “billing_postcode”
  • “user” which can be a dictionary containing the keys:
    • “first_name”
    • “last_name”
    • “email”

new_pre_authorization_url(max_amount, interval_length, interval_unit, expires_at=None, name=None, description=None, interval_count=None, calendar_intervals=None, redirect_uri=None, cancel_uri=None, state=None, user=None, setup_fee=None)

Get a url for creating new pre_authorizations

Parameters:

• max_amount – A float which is the maximum amount for this pre_authorization
• interval_length – The length of this pre_authorization
• interval_unit – The units in which the interval_length is measured, must be one of - “day” - “week” - “month”
• expires_at – The date that this pre_authorization will expire, must be a datetime object which is in the future.
• name – A short string which is the name of the pre_authorization
• description – A longer string describing what the pre_authorization is for.
• interval_count – calculates expires_at based on the number of payment intervals you would like the resource to have. Must be a positive integer greater than 0. If you specify both an interval_count and an expires_at argument then the expires_at argument will take precedence.
• calendar_intervals – Describes whether the interval resource should be aligned with calendar weeks or months, default is False
• redirect_uri – URI to redirect to after the authorization process
• cancel_uri – URI to redirect the user to if they cancel authorization
• state – String which will be passed to the merchant on redirect.
• user –

  A dictionary which will be used to prepopulate the sign up form the user sees, this can contain keys:

  • first_name
  • last_name
  • email
• setup_fee – A one off payment which will be taken at the start of the subscription.

new_preauthorization_url(max_amount, interval_length, interval_unit, expires_at=None, name=None, description=None, interval_count=None, calendar_intervals=None, redirect_uri=None, cancel_uri=None, state=None, user=None, setup_fee=None)

Get a url for creating new pre_authorizations

Parameters:

• max_amount – A float which is the maximum amount for this pre_authorization
• interval_length – The length of this pre_authorization
• interval_unit – The units in which the interval_length is measured, must be one of - “day” - “week” - “month”
• expires_at – The date that this pre_authorization will expire, must be a datetime object which is in the future.
• name – A short string which is the name of the pre_authorization
• description – A longer string describing what the pre_authorization is for.
• interval_count – calculates expires_at based on the number of payment intervals you would like the resource to have. Must be a positive integer greater than 0. If you specify both an interval_count and an expires_at argument then the expires_at argument will take precedence.
• calendar_intervals – Describes whether the interval resource should be aligned with calendar weeks or months, default is False
• redirect_uri – URI to redirect to after the authorization process
• cancel_uri – URI to redirect the user to if they cancel authorization
• state – String which will be passed to the merchant on redirect.
• user –

  A dictionary which will be used to prepopulate the sign up form the user sees, this can contain keys:

  • first_name
  • last_name
  • email
• setup_fee – A one off payment which will be taken at the start of the subscription.

new_subscription_url(amount, interval_length, interval_unit, name=None, description=None, interval_count=None, start_at=None, expires_at=None, redirect_uri=None, cancel_uri=None, state=None, user=None, setup_fee=None)

Generate a url for creating a new subscription

Parameters:

• amount – The amount to charge each time
• interval_length – The length of time between each charge, this is an integer, the units are specified by interval_unit.
• interval_unit – The unit to measure the interval length, must be one of “day”, “week” or “month”
• name – The name to give the subscription
• description – The description of the subscription
• interval_count – The Calculates expires_at based on the number of intervals you would like to collect. If both interval_count and expires_at are specified the expires_at parameter will take precedence
• expires_at – When the subscription expires, should be a datetime object.
• starts_at – When the subscription starts, should be a datetime object
• redirect_uri – URI to redirect to after the authorization process
• cancel_uri – URI to redirect the user to if they cancel authorization
• state – String which will be passed to the merchant on redirect.
• user –

  A dictionary which will be used to prepopulate the sign up form the user sees, this can contain keys:

  • first_name
  • last_name
  • email
• setup_fee – A one off payment which will be taken at the start of the subscription.

pre_authorization(id)

Find a pre authorization with id id

Params id:The pre authorization id

subscription(id)

Returns a single subscription

Parameters:id – The subscription id, String

user(id)

Find a user by id

Parameters:id – The users id

validate_webhook(params)

Check whether a webhook signature is valid

Takes a dictionary of parameters, including the signature and returns a boolean indicating whether the signature is valid.

Parameters:params – A dictionary of data to validate, must include the key “signature”