GoCardlessClient.OAuth (GoCardlessClient v2.0.0)

Copy Markdown View Source

GoCardlessClient OAuth2 partner integration.

Partner platforms use OAuth to act on behalf of multiple merchant accounts.

Flow

  1. Build an authorisation URL and redirect the merchant.
  2. GoCardlessClient redirects back with ?code=...
  3. Exchange the code for an access token.
  4. Use the token to make API calls on behalf of the merchant.

Example

config = %{
  client_id: System.get_env("GC_CLIENT_ID"),
  client_secret: System.get_env("GC_CLIENT_SECRET"),
  redirect_uri: "https://yourapp.com/oauth/callback",
  environment: :sandbox
}

# Step 1 — redirect merchant
auth_url = GoCardlessClient.OAuth.authorise_url(config,
  scope: "read_write",
  state: csrf_token
)
redirect(conn, external: auth_url)

# Step 2 — on callback
{:ok, token} = GoCardlessClient.OAuth.exchange_code(config, params["code"])

# Step 3 — use token
client = GoCardlessClient.Client.new!(access_token: token["access_token"])

Summary

Types

config()

Functions

authorise_url(config, opts \\ [])

Builds the GoCardlessClient OAuth authorisation URL.

disconnect(config, access_token)

Revokes an access token, disconnecting the merchant from your app.

exchange_code(config, code)

Exchanges an authorisation code for an access token.

lookup_token(config, access_token)

Looks up which organisation an access token belongs to.

Types

config()

@type config() :: %{
  :client_id => String.t(),
  :client_secret => String.t(),
  :redirect_uri => String.t(),
  optional(:environment) => :sandbox | :live
}

Functions

authorise_url(config, opts \\ [])

@spec authorise_url(
  config(),
  keyword()
) :: String.t()

Builds the GoCardlessClient OAuth authorisation URL.

Options

  • :scope — "read_write" (default) or "read_only"
  • :state — CSRF protection token (recommended)
  • :initial_view — "signup" or "login"
  • :prefill_email — pre-fill the merchant's email

disconnect(config, access_token)

@spec disconnect(config(), String.t()) ::
  :ok
  | {:error,
     GoCardlessClient.Error.t() | %{status: non_neg_integer(), body: term()}}

Revokes an access token, disconnecting the merchant from your app.

exchange_code(config, code)

@spec exchange_code(config(), String.t()) ::
  {:ok, map()}
  | {:error,
     GoCardlessClient.Error.t() | %{status: non_neg_integer(), body: term()}}

Exchanges an authorisation code for an access token.

Returns {:ok, token_response} where the response contains:

  • "access_token" — use with GoCardlessClient.Client.new!/1
  • "token_type" — "Bearer"
  • "scope" — granted scope
  • "organisation_id" — the merchant's GoCardlessClient organisation ID

lookup_token(config, access_token)

@spec lookup_token(config(), String.t()) ::
  {:ok, map()}
  | {:error,
     GoCardlessClient.Error.t() | %{status: non_neg_integer(), body: term()}}

Looks up which organisation an access token belongs to.

Returns {:ok, %{"organisation_id" => ..., "links" => ...}}.