openapi: 3.0.3
info:
  title: EBANX Payout API
  version: '1.0'
  description: >-
    Send money from a merchant balance to a local bank account or e-wallet in
    EBANX's Latin American and emerging markets. Supports both local payouts
    (merchant pre-funds in local currency) and cross-border payouts (merchant
    deposits USD and EBANX converts to the payee's local currency), with bank
    transfers settled in up to two business days and e-wallets in roughly two
    minutes.
  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: []
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:
  securitySchemes:
    integrationKey:
      type: apiKey
      in: header
      name: x-ebanx-integration-key
  schemas:
    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'
    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 }
    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 }