openapi: 3.0.3
info:
  title: TrueLayer Mandates Payments API
  description: The TrueLayer Payments API v3 enables applications to create and manage open banking payments, payouts, refunds, and variable recurring payment mandates across the UK and EU. TrueLayer connects to 69+ banks and provides a unified interface for instant bank payments using open banking rails. Authentication requires signed requests with private keys and OAuth2 access tokens.
  version: 3.0.0
  contact:
    name: TrueLayer Support
    url: https://docs.truelayer.com
  termsOfService: https://truelayer.com/legal/
servers:
- url: https://api.truelayer.com
  description: TrueLayer Production API
- url: https://api.truelayer-sandbox.com
  description: TrueLayer Sandbox (testing)
security:
- BearerAuth: []
tags:
- name: Payments
  description: Create and manage individual bank payments
paths:
  /v3/payments:
    post:
      summary: Create Payment
      description: Initiate a new payment via open banking. Supports closed-loop pay-ins to merchant accounts, single payments to external accounts, and mandate-based VRP payments. All POST requests must include a Tl-Signature header and Idempotency-Key.
      operationId: createPayment
      tags:
      - Payments
      parameters:
      - name: Tl-Signature
        in: header
        required: true
        description: Request signing signature (detached JWS)
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        description: UUID for idempotent request deduplication
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '200':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /v3/payments/{id}:
    get:
      summary: Get Payment
      description: Retrieve the current status and details of a payment.
      operationId: getPayment
      tags:
      - Payments
      parameters:
      - name: id
        in: path
        required: true
        description: Payment UUID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/payments/{id}/authorization-flow:
    post:
      summary: Start Authorization Flow
      description: Start or continue the payment authorization flow. Used when implementing a custom authorization journey.
      operationId: startAuthorizationFlow
      tags:
      - Payments
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Tl-Signature
        in: header
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider_selection:
                  type: object
                  description: Selected provider for authorization
                  properties:
                    provider_id:
                      type: string
                scheme_selection:
                  type: object
                  description: Payment scheme selection
                redirect:
                  type: object
                  properties:
                    return_uri:
                      type: string
                      format: uri
      responses:
        '200':
          description: Authorization flow started
          content:
            application/json:
              schema:
                type: object
                properties:
                  authorization_flow:
                    type: object
                    properties:
                      actions:
                        type: object
                      configuration:
                        type: object
                  status:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Unauthorized - invalid token or missing signature
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
              title:
                type: string
    UnprocessableEntity:
      description: Unprocessable entity - business logic error
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
              title:
                type: string
              errors:
                type: object
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
              title:
                type: string
              trace_id:
                type: string
              errors:
                type: object
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
              title:
                type: string
  schemas:
    CreatePaymentResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Payment ID
        user:
          type: object
          properties:
            id:
              type: string
              format: uuid
        resource_token:
          type: string
          description: JWT token for client-side payment authorization (15 min expiry)
        status:
          type: string
          enum:
          - authorization_required
          description: Initial status after creation
    Payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount_in_minor:
          type: integer
        currency:
          type: string
        payment_method:
          type: object
        user:
          type: object
        status:
          type: string
          enum:
          - authorization_required
          - authorizing
          - authorized
          - executed
          - settled
          - failed
          - pending
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        executed_at:
          type: string
          format: date-time
        settled_at:
          type: string
          format: date-time
        failure_reason:
          type: string
    CreatePaymentRequest:
      type: object
      required:
      - amount_in_minor
      - currency
      - payment_method
      - user
      properties:
        amount_in_minor:
          type: integer
          description: Amount in minor currency units (e.g., pence for GBP)
          minimum: 1
        currency:
          type: string
          enum:
          - GBP
          - EUR
          description: ISO 4217 currency code
        payment_method:
          type: object
          required:
          - type
          - beneficiary
          properties:
            type:
              type: string
              enum:
              - bank_transfer
              - mandate
            provider_selection:
              type: object
              description: How to select the payment provider
              properties:
                type:
                  type: string
                  enum:
                  - user_selected
                  - preselected
                provider_id:
                  type: string
                  description: Required when type=preselected
                filter:
                  type: object
                  description: Constraints for provider selection
            scheme_selection:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - instant_only
                  - instant_preferred
                  - user_selected
                  - preselected
            beneficiary:
              type: object
              required:
              - type
              properties:
                type:
                  type: string
                  enum:
                  - merchant_account
                  - external_account
                merchant_account_id:
                  type: string
                  format: uuid
                  description: Required when type=merchant_account
                account_holder_name:
                  type: string
                account_identifier:
                  type: object
                  description: Required when type=external_account
                  properties:
                    type:
                      type: string
                      enum:
                      - sort_code_account_number
                      - iban
                      - bban
                      - nrb
                    sort_code:
                      type: string
                    account_number:
                      type: string
                    iban:
                      type: string
        user:
          type: object
          required:
          - name
          properties:
            id:
              type: string
              description: Your internal user ID (optional)
            name:
              type: string
            email:
              type: string
              format: email
            phone:
              type: string
            date_of_birth:
              type: string
              format: date
            address:
              type: object
        metadata:
          type: object
          description: Up to 10 custom key-value string pairs
          maxProperties: 10
          additionalProperties:
            type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 access token with payments scope