> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dolfinai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay a bill by bank (open banking)

> Initiates a Yapily pay-by-bank payment for an approved bill: the response carries the bank authorisation URL the payer must open, plus the mandatory Yapily Connect disclosure to render on the consent screen. Requires the client to have opted in to pay-by-bank and the supplier's bank details to be confirmed. After bank authorisation the user is redirected to returnUrl (host must be allowlisted on the client).



## OpenAPI

````yaml post /bills/{id}/pay/bank
openapi: 3.1.1
info:
  title: Dolfin API
  description: >-
    Dolfin API for AR & AP. Authenticate using the `x-dolfin-api-key` header
    with the API key distributed to your organisation.
  version: v1
servers:
  - url: https://api.dolfinai.co
    description: Production
security:
  - {}
tags:
  - name: Webhooks
  - name: Users
  - name: TaxRates
  - name: Suppliers
  - name: Supplier Credit Notes
  - name: Bills
  - name: SpendCategories
  - name: Payables
  - name: RecurringInvoices
  - name: Receivables
  - name: Purchase Orders
  - name: Products
  - name: Payments
  - name: Invoices
  - name: Organisations
  - name: Members
  - name: MCP
  - name: Matching
  - name: Invoice Reminders
  - name: Industries
  - name: Gmail
  - name: Delivery Notes
  - name: Customers
  - name: Currencies
  - name: Credit Notes
  - name: Clients
  - name: ClientInvites
  - name: BankPayments
  - name: Bank details
  - name: Auth
  - name: ApprovalPolicies
  - name: ApiKeys
  - name: Agent
paths:
  /bills/{id}/pay/bank:
    post:
      tags:
        - BankPayments
      summary: Pay a bill by bank (open banking)
      description: >-
        Initiates a Yapily pay-by-bank payment for an approved bill: the
        response carries the bank authorisation URL the payer must open, plus
        the mandatory Yapily Connect disclosure to render on the consent screen.
        Requires the client to have opted in to pay-by-bank and the supplier's
        bank details to be confirmed. After bank authorisation the user is
        redirected to returnUrl (host must be allowlisted on the client).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateBillBankPaymentRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateBillBankPaymentResponse'
        '400':
          description: >-
            Bill.TransitionFailed — bill is not in a state that allows this
            transition


            ValidationProblem — supplier bank details fail validation; per-field
            errors with machine-readable `codes`
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: >-
            BankPayment.RedirectHostNotAllowed — returnUrl host not on the
            client allowlist


            Organisation.InsufficientRole — caller's organisation role is below
            the level this action requires
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: >-
            Bill.NotFound — bill does not exist or belongs to a different
            organisation
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: >-
            BankPayment.PayByBankNotEnabled — the client has not opted in to
            pay-by-bank


            BankPayment.SupplierBankDetailsNotVerified — supplier bank details
            not confirmed by an admin


            BankPayment.MissingSupplier — bill has no resolved supplier


            BankPayment.MissingBankDetails — supplier has no UK sort
            code/account number


            BankPayment.NothingToPay — the bill has no outstanding balance to
            pay


            BankPayment.UnsupportedCurrency — bill is not GBP
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '502':
          description: >-
            BankPayment.ProviderError — Yapily rejected the authorisation
            request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '503':
          description: >-
            Service Unavailable


            BankPayment.NotConfigured — pay-by-bank is not enabled for this
            environment
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    InitiateBillBankPaymentRequest:
      required:
        - institutionId
        - returnUrl
      type: object
      properties:
        institutionId:
          type: string
        returnUrl:
          type: string
    InitiateBillBankPaymentResponse:
      required:
        - billPaymentId
        - authorisationUrl
        - expiresAt
        - disclosure
      type: object
      properties:
        billPaymentId:
          type: string
          format: uuid
        authorisationUrl:
          type: string
        expiresAt:
          type: string
          format: date-time
        disclosure:
          $ref: '#/components/schemas/YapilyDisclosure'
    ProblemDetails:
      type: object
      properties:
        type:
          type:
            - 'null'
            - string
        title:
          type:
            - 'null'
            - string
        status:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
            - 'null'
            - integer
            - string
          format: int32
        detail:
          type:
            - 'null'
            - string
        instance:
          type:
            - 'null'
            - string
    YapilyDisclosure:
      required:
        - text
        - termsUrl
        - privacyUrl
      type: object
      properties:
        text:
          type: string
        termsUrl:
          type: string
        privacyUrl:
          type: string

````