Fence Payments API

openapi: 3.2.0
info:
  title: Fence Partner Integration Payments API
  version: '2.0'
  description: Machine-readable contract for the Fence API operations documented for integration partners. Access requires credentials provisioned by Fence during onboarding. Deal-specific asset fields are agreed separately and remain explicitly extensible in this contract. The current public API uses the /v2 major-version path. Compatible additive changes may be introduced within a major version; a change that breaks a documented integration requires a new major version. No operation in this description is currently announced for deprecation.
  contact:
    name: Fence
    url: https://fence.finance/contact/
    email: hello@fence.finance
servers:
- url: https://dev-api.fence.finance
  description: Sandbox API for integration testing. Requires sandbox credentials provisioned by Fence.
- url: https://api.fence.finance
  description: Production API. Requires production credentials provisioned by Fence.
security:
- OAuth2ClientCredentials: []
tags:
- name: Payments
  description: Validate or submit payment transactions in bulk.
paths:
  /v2/{deal_id}/payments/bulk:
    parameters:
    - $ref: '#/components/parameters/DealId'
    post:
      tags:
      - Payments
      operationId: bulkCreatePayments
      summary: Validate or submit payment transactions
      description: Validate payment transactions synchronously when dry_run is true, or enqueue them for asynchronous creation when dry_run is false.
      parameters:
      - name: dry_run
        in: query
        required: false
        description: When true, validate without creating transactions. Set false explicitly to enqueue live processing.
        schema:
          type: boolean
          default: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPaymentsRequest'
      responses:
        '200':
          description: Synchronous validation result, including per-transaction failures.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResult'
        '202':
          description: Transactions accepted for asynchronous processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncPaymentsAccepted'
        '400':
          description: The request could not be processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '401':
          description: A valid bearer access token is required.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '403':
          description: The client is not authorized for this deal or action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '404':
          description: The requested deal or resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '422':
          description: The request did not satisfy validation rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
components:
  schemas:
    BulkPaymentsRequest:
      type: object
      additionalProperties: false
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentTransaction'
    ValidationIssue:
      type: object
      additionalProperties: true
      properties:
        loc:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
        msg:
          type: string
        type:
          type: string
    AsyncPaymentsAccepted:
      type: object
      additionalProperties: false
      required:
      - declaration_id
      - accepted
      - accepted_count
      - failed_count
      - failed
      - message
      properties:
        declaration_id:
          type: string
          format: uuid
        accepted:
          type: array
          items:
            type: string
        accepted_count:
          type: integer
          minimum: 0
        failed_count:
          type: integer
          minimum: 0
        failed:
          type: array
          items:
            type: object
            additionalProperties: true
        message:
          type: string
    PaymentMetadata:
      type: object
      required:
      - metadata_type
      properties:
        metadata_type:
          type: string
          enum:
          - intake
          - intake_meta
          - expense
          - borrow
          - repayment
          - utilization
          - outgoing_type
        deal_specific_metadata:
          type:
          - object
          - 'null'
          additionalProperties: true
      additionalProperties: true
    PaymentTransactionType:
      type: string
      enum:
      - expense
      - borrow
      - repayment
      - waterfall_payment
      - intake
      - intake_meta
      - outbound
      - outgoing_type
      - disposition
      - utilization
    PaymentTransaction:
      type: object
      additionalProperties: false
      required:
      - external_id
      - amount
      - transaction_date
      properties:
        external_id:
          type: string
          minLength: 1
        from_:
          type:
          - string
          - 'null'
        to_:
          type:
          - string
          - 'null'
        amount:
          type: number
        memo:
          type:
          - string
          - 'null'
        iban:
          type:
          - string
          - 'null'
        routing_number:
          type:
          - string
          - 'null'
        account_number:
          type:
          - string
          - 'null'
        transaction_date:
          type: string
          format: date-time
        bank_account_id:
          type:
          - string
          - 'null'
          format: uuid
        currency:
          type: string
          enum:
          - ALL
          - ARS
          - AUD
          - BGN
          - BOB
          - BRL
          - BZD
          - CAD
          - CHF
          - CLP
          - CNY
          - COP
          - CRC
          - CZK
          - DKK
          - EGP
          - EUR
          - GBP
          - GEL
          - GTQ
          - HKD
          - HUF
          - IDR
          - ILS
          - INR
          - ISK
          - JPY
          - KHR
          - KRW
          - LAK
          - LKR
          - MAD
          - MKD
          - MVR
          - MXN
          - MYR
          - NOK
          - NZD
          - PAB
          - PEN
          - PHP
          - PLN
          - PYG
          - RON
          - RSD
          - SEK
          - SGD
          - THB
          - TRY
          - TZS
          - USD
          - UYU
          - VND
          - ZAR
          default: EUR
        intake_source:
          type:
          - string
          - 'null'
          default: banking
        transaction_type:
          oneOf:
          - $ref: '#/components/schemas/PaymentTransactionType'
          - type: 'null'
        metadata:
          oneOf:
          - $ref: '#/components/schemas/PaymentMetadata'
          - type: 'null'
    BulkOperationResult:
      type: object
      additionalProperties: true
      required:
      - entity_name
      properties:
        declaration_id:
          type:
          - string
          - 'null'
        entity_name:
          type: string
        failed:
          type: array
          items:
            type: object
            additionalProperties: true
        message:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
        successful:
          type: array
          items:
            oneOf:
            - type: string
            - type: object
              additionalProperties: true
        valid:
          type: array
          items:
            oneOf:
            - type: string
            - type: object
              additionalProperties: true
        delta_borrow_base:
          type:
          - number
          - 'null'
    HttpError:
      type: object
      additionalProperties: true
      required:
      - detail
      properties:
        detail:
          oneOf:
          - type: string
          - type: array
            items:
              $ref: '#/components/schemas/ValidationIssue'
          - type: object
            additionalProperties: true
  parameters:
    DealId:
      name: deal_id
      in: path
      required: true
      description: Fence deal identifier provisioned for the target environment.
      schema:
        type: string
        format: uuid
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 Client Credentials grant for server-to-server integrations. Fence provisions credentials separately for each environment.
      flows:
        clientCredentials:
          tokenUrl: /v1/login/access-token
          scopes: {}
externalDocs:
  description: Fence API Client Integration Guide
  url: https://docs.fence.finance/