TrueLayer Payments API v3.
All mutating calls (POST) are:
- Request-signed via ES512 JWS (
Tl-Signatureheader) - Idempotent — stable
Idempotency-Keyper:operation_id - Retried on
Tl-Should-Retry: trueresponses
Example
{:ok, payment} = TruelayerClient.Payments.create_payment(client,
%{
amount_in_minor: 1000,
currency: "GBP",
payment_method: %{
type: "bank_transfer",
provider_selection: %{type: "user_selected"},
beneficiary: %{type: "merchant_account", merchant_account_id: ma_id}
},
user: %{name: "Jane Doe", email: "jane@example.com"}
},
operation_id: "order-001"
)Summary
Functions
Cancel a payment (POST /v3/payments/{id}/cancel).
Create a payment intent (POST /v3/payments).
Create a payment link (POST /v3/payment-links).
Create a refund (POST /v3/payments/{id}/refunds).
Get a payment by ID (GET /v3/payments/{id}).
Get a payment link by ID (GET /v3/payment-links/{id}).
Get a payment provider by ID (GET /v3/payments-providers/{id}).
Get a refund by ID (GET /v3/payments/{id}/refunds/{refund_id}).
List payments for a payment link (GET /v3/payment-links/{id}/payments).
List all refunds for a payment (GET /v3/payments/{id}/refunds).
Search payment providers (POST /v3/payments-providers/search).
Start the authorization flow (POST /v3/payments/{id}/authorization-flow).
Submit PSU consent.
Submit form inputs.
Submit provider selection.
Submit bank-redirect return parameters (POST /v3/payments-providers/return).
Submit scheme selection.
Poll get_payment/2 until a terminal status is reached or the timeout expires.
Functions
@spec cancel_payment(TruelayerClient.t(), String.t(), keyword()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Cancel a payment (POST /v3/payments/{id}/cancel).
@spec create_payment(TruelayerClient.t(), map(), keyword()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Create a payment intent (POST /v3/payments).
Required option
:operation_id— stable caller-supplied ID used to derive theIdempotency-Key. Safe to retry with the same ID.
@spec create_payment_link(TruelayerClient.t(), map(), keyword()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Create a payment link (POST /v3/payment-links).
Required option
:operation_id— stable ID for idempotency
@spec create_refund(TruelayerClient.t(), String.t(), map(), keyword()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Create a refund (POST /v3/payments/{id}/refunds).
Pass amount_in_minor: 0 or omit for a full refund.
Required option
:operation_id— stable ID for idempotency
@spec get_payment(TruelayerClient.t(), String.t()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Get a payment by ID (GET /v3/payments/{id}).
@spec get_payment_link(TruelayerClient.t(), String.t()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Get a payment link by ID (GET /v3/payment-links/{id}).
@spec get_provider(TruelayerClient.t(), String.t()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Get a payment provider by ID (GET /v3/payments-providers/{id}).
@spec get_refund(TruelayerClient.t(), String.t(), String.t()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Get a refund by ID (GET /v3/payments/{id}/refunds/{refund_id}).
@spec list_payment_link_payments(TruelayerClient.t(), String.t(), keyword()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
List payments for a payment link (GET /v3/payment-links/{id}/payments).
@spec list_refunds(TruelayerClient.t(), String.t()) :: {:ok, [map()]} | {:error, TruelayerClient.Error.t()}
List all refunds for a payment (GET /v3/payments/{id}/refunds).
@spec search_providers(TruelayerClient.t(), map()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Search payment providers (POST /v3/payments-providers/search).
@spec start_authorization_flow(TruelayerClient.t(), String.t(), map()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Start the authorization flow (POST /v3/payments/{id}/authorization-flow).
@spec submit_consent(TruelayerClient.t(), String.t()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Submit PSU consent.
@spec submit_form(TruelayerClient.t(), String.t(), map()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Submit form inputs.
@spec submit_provider_selection(TruelayerClient.t(), String.t(), String.t()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Submit provider selection.
@spec submit_return_parameters(TruelayerClient.t(), map()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Submit bank-redirect return parameters (POST /v3/payments-providers/return).
@spec submit_scheme_selection(TruelayerClient.t(), String.t(), String.t()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Submit scheme selection.
@spec wait_for_final_status(TruelayerClient.t(), String.t(), keyword()) :: {:ok, map()} | {:error, TruelayerClient.Error.t()}
Poll get_payment/2 until a terminal status is reached or the timeout expires.
Terminal statuses: executed, settled, failed, cancelled.
Prefer webhook-driven status updates in production systems.
Options
:timeout_ms- maximum wait time in milliseconds (default: 60_000):interval_ms- polling interval in milliseconds (default: 2_000)