GoCardless Outbound Payments API.
Outbound Payments send money from your Payment Account to recipients. They require API request signing with an ECDSA P-256 private key registered in your GoCardless dashboard.
Rate limiting
Outbound Payments has stricter rate limits than other endpoints. Check the
GoCardlessClient.Client.rate_limit_state/1 after each call.
Outbound payment states
created → pending_approval (optional) → executing → executed / failed / cancelled
Example — send a payment
signer = GoCardlessClient.Signing.new!(key_id: "kid", pem: pem)
{:ok, payment} = GoCardlessClient.Resources.OutboundPayments.create(client,
%{
amount: 50_000,
currency: "GBP",
description: "Supplier invoice #1234",
recipient_bank_account: %{
account_holder_name: "Acme Ltd",
account_number: "12345678",
branch_code: "204514",
country_code: "GB"
},
links: %{creditor: "CR123", payment_account: "PA123"}
},
signer: signer,
idempotency_key: GoCardlessClient.new_idempotency_key()
)Example — withdraw funds to your own bank account
{:ok, withdrawal} = GoCardlessClient.Resources.OutboundPayments.withdrawal(client,
%{
amount: 100_000,
currency: "GBP",
links: %{
payment_account: "PA123",
creditor_bank_account: "BA456"
}
},
signer: signer,
idempotency_key: GoCardlessClient.new_idempotency_key()
)Summary
Functions
Approves an outbound payment that is pending approval.
Cancels an outbound payment before it is executed.
Eagerly collects all outbound payments into a list.
Creates an outbound payment to a recipient.
Retrieves a single outbound payment by ID.
Returns a page of outbound payments. Filter by :status, :currency, :payment_account.
Returns aggregate statistics for outbound payments.
Returns a lazy Stream over all pages of outbound payments.
Updates an outbound payment's metadata. Only possible before execution.
Creates a withdrawal — sends funds from the Payment Account to your own creditor bank account. Useful for sweeping collected funds.
Functions
@spec approve(GoCardlessClient.Client.t(), String.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Approves an outbound payment that is pending approval.
SCA (Strong Customer Authentication) must be completed before calling this.
The :signer option is required.
@spec cancel(GoCardlessClient.Client.t(), String.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Cancels an outbound payment before it is executed.
@spec collect_all(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, [map()]} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Eagerly collects all outbound payments into a list.
@spec create(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Creates an outbound payment to a recipient.
Always pass an idempotency key and a :signer for safe retries and security.
@spec get(GoCardlessClient.Client.t(), String.t(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Retrieves a single outbound payment by ID.
@spec list(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, %{items: [map()], meta: map()}} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Returns a page of outbound payments. Filter by :status, :currency, :payment_account.
@spec statistics(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Returns aggregate statistics for outbound payments.
Returns counts and total amounts grouped by status and currency.
@spec stream(GoCardlessClient.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy Stream over all pages of outbound payments.
@spec update(GoCardlessClient.Client.t(), String.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Updates an outbound payment's metadata. Only possible before execution.
@spec withdrawal(GoCardlessClient.Client.t(), map(), keyword()) :: {:ok, map()} | {:error, GoCardlessClient.APIError.t() | GoCardlessClient.Error.t()}
Creates a withdrawal — sends funds from the Payment Account to your own creditor bank account. Useful for sweeping collected funds.