Authenticate using client_credentials grant against TrueLayer's OAuth2 token endpoint (https://auth.truelayer.com/connect/token) with your client_id and client_secret; request the payments scope
POST /payments to the TrueLayer Payments API (https://api.truelayer.com/payments) with a body containing amount_in_minor (pence/cents), currency, payment_method (type: bank_transfer, beneficiary details with account number and sort code), and user object
Receive a payment id and resource_token in the response; use the resource_token (not your main access token) to create a TrueLayer hosted payment page URL or to embed TrueLayer's drop-in SDK
Redirect the user to the payment page URL or render the embedded SDK; the user selects their bank provider, authenticates, and approves the payment without leaving your flow if using the embedded SDK
After the user completes or abandons the flow, they are sent to your return_uri; verify the payment status by calling GET /payments/{paymentId} using your main access token
Handle terminal statuses: settled (funds received), failed, and authorized_for_settlement (payment authorized but not yet settled — typically intraday); set up TrueLayer webhooks (event_type: payment_settled, payment_failed) for async status updates
Known gotchas
The resource_token is payment-scoped and single-use for the hosted page; never expose it in client-side URLs or logs — treat it with the same sensitivity as a payment authorization code
TrueLayer Payments v3 requires end-user information (name, date of birth, address) for some institutions and use cases for fraud compliance; omitting these fields causes a 422 on payment creation at those institutions
payment_authorized_for_settlement is not equivalent to settled; if your system credits funds on authorization rather than settlement, you bear the risk of a payment that authorizes but fails to settle — always wait for the settled webhook before crediting
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp