openapi: 3.0.3
info:
  title: EBANX FX Payouts API
  version: '1.0'
  description: Retrieve current foreign exchange rates between local market currencies (BRL, MXN, COP, ARS, CLP, PEN, etc.) and pricing currencies (USD, EUR), and lock a rate via an FX token so a quoted price is honored at capture.
  contact:
    name: EBANX Sales Engineering
    email: sales.engineering@ebanx.com
    url: https://docs.ebanx.com
servers:
- url: https://api.ebanxpay.com
  description: Production environment
- url: https://sandbox.ebanxpay.com
  description: Sandbox environment for testing
security:
- integrationKey: []
tags:
- name: Payouts
paths:
  /ws/payout/create:
    post:
      summary: Create Payout
      operationId: createPayout
      description: Create a payout to a payee bank account or e-wallet. The payout starts in a draft state and must be committed.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutRequest'
      responses:
        '200':
          description: Payout created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
  /ws/payout/commit:
    post:
      summary: Commit Payout
      operationId: commitPayout
      description: Confirm and release a previously created payout for settlement.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
                external_uid:
                  type: string
                payout_uid:
                  type: string
      responses:
        '200':
          description: Payout committed
  /ws/payout/cancel:
    post:
      summary: Cancel Payout
      operationId: cancelPayout
      description: Cancel a payout that has not yet been committed or settled.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
                external_uid:
                  type: string
                payout_uid:
                  type: string
      responses:
        '200':
          description: Payout cancelled
  /ws/payout/retrieve:
    post:
      summary: Retrieve Payout
      operationId: retrievePayout
      description: Retrieve the current status and settlement details of a payout.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
                external_uid:
                  type: string
                payout_uid:
                  type: string
      responses:
        '200':
          description: Payout details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
  /ws/payout/search:
    post:
      summary: Search Payouts
      operationId: searchPayouts
      description: Search payouts by date range, status, or payee.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
                start_date:
                  type: string
                  format: date
                end_date:
                  type: string
                  format: date
                status:
                  type: string
      responses:
        '200':
          description: Payout list
  /ws/payout/simulate:
    post:
      summary: Simulate Payout
      operationId: simulatePayout
      description: Calculate the fees, FX rate, and final payee amount that would apply to a hypothetical payout.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutRequest'
      responses:
        '200':
          description: Simulation result
  /ws/payout/attach:
    post:
      summary: Attach Invoice To Payout
      operationId: attachPayoutInvoice
      description: Attach a tax invoice or supporting document to a payout.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
                external_uid:
                  type: string
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Invoice attached
  /ws/payout/balance:
    post:
      summary: Get Payout Balance
      operationId: getPayoutBalance
      description: Return the current funded balance available for payouts in each supported currency.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
      responses:
        '200':
          description: Balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  balance:
                    type: array
                    items:
                      type: object
                      properties:
                        currency_code:
                          type: string
                        country:
                          type: string
                        amount:
                          type: number
                          format: float
  /ws/payout/banks:
    post:
      summary: List Payout Banks
      operationId: listPayoutBanks
      description: List banks supported as payout destinations for a given country.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
                country:
                  type: string
      responses:
        '200':
          description: Bank list
  /ws/payout/bankDetails:
    post:
      summary: Get Payout Bank Details
      operationId: getPayoutBankDetails
      description: Return the field requirements for a destination bank in a given country.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
                country:
                  type: string
                bank_code:
                  type: string
      responses:
        '200':
          description: Bank requirements
  /ws/payout/verify_account:
    post:
      summary: Verify Payee Bank Account
      operationId: verifyPayeeBankAccount
      description: Verify that a payee bank account exists and that the account holder name matches before sending funds.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key:
                  type: string
                country:
                  type: string
                bank_code:
                  type: string
                agency:
                  type: string
                account:
                  type: string
                account_digit:
                  type: string
                document:
                  type: string
      responses:
        '200':
          description: Verification result
  /ws/payee/create:
    post:
      summary: Create Payee
      operationId: createPayee
      description: Register a reusable payee (beneficiary) record for repeat payouts.
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayeeRequest'
      responses:
        '200':
          description: Payee created
components:
  schemas:
    PayeeRequest:
      type: object
      required:
      - integration_key
      - payee
      properties:
        integration_key:
          type: string
        payee:
          $ref: '#/components/schemas/Payee'
    PayoutResponse:
      type: object
      properties:
        status:
          type: string
        payout:
          type: object
          properties:
            payout_uid:
              type: string
            external_uid:
              type: string
            status:
              type: string
            amount_target:
              type: number
            currency_target:
              type: string
            amount_source:
              type: number
            currency_source:
              type: string
            fx_rate:
              type: number
            fee:
              type: number
            created_at:
              type: string
              format: date-time
            estimated_settlement:
              type: string
              format: date-time
    Payee:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        document:
          type: string
        document_type:
          type: string
          description: Local tax id type (CPF, CNPJ, RFC, NIT, etc.).
        country:
          type: string
        bank:
          type: object
          properties:
            code:
              type: string
            agency:
              type: string
            account:
              type: string
            account_digit:
              type: string
            account_type:
              type: string
    PayoutRequest:
      type: object
      required:
      - integration_key
      - external_uid
      - payee
      properties:
        integration_key:
          type: string
        external_uid:
          type: string
          description: Merchant-provided unique identifier for the payout.
        target:
          type: string
          enum:
          - bank_account
          - e_wallet
        target_account:
          type: string
        currency_target:
          type: string
        amount_target:
          type: number
          format: float
        currency_source:
          type: string
        amount_source:
          type: number
          format: float
        payee:
          $ref: '#/components/schemas/Payee'
  securitySchemes:
    integrationKey:
      type: apiKey
      in: header
      name: x-ebanx-integration-key