openapi: 3.0.3
info:
  title: EBANX Pay-in Direct API
  version: '1.0'
  description: >-
    Direct integration with EBANX to accept payments from customers in Latin America
    and other rising markets using local payment methods (Pix, Boleto, OXXO, SPEI,
    PSE, credit and debit cards, e-wallets, vouchers). The Direct API gives
    merchants full control over the checkout experience and is intended for
    high-conversion flows, subscriptions, and advanced payment scenarios.
  contact:
    name: EBANX Sales Engineering
    email: sales.engineering@ebanx.com
    url: https://docs.ebanx.com
  termsOfService: https://www.ebanx.com/en/legal/merchants/terms-and-conditions-for-payment-processing-services/
  license:
    name: EBANX Merchant Terms
    url: https://www.ebanx.com/en/legal/merchants/terms-and-conditions-for-payment-processing-services/
servers:
  - url: https://api.ebanxpay.com
    description: Production environment
  - url: https://sandbox.ebanxpay.com
    description: Sandbox environment for testing
security:
  - integrationKey: []
paths:
  /ws/direct:
    post:
      summary: Create Direct Payment
      operationId: createDirectPayment
      description: >-
        Create a payment for a local payment method. Supports cards (with optional
        3DS and installments), Pix, Boleto, OXXO, SPEI, PSE, Efecty, PagoEfectivo,
        and many local e-wallets across EBANX markets.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectPaymentRequest'
      responses:
        '200':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
  /ws/capture:
    post:
      summary: Capture Payment
      operationId: capturePayment
      description: Capture a previously authorized card payment.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key: { type: string }
                hash: { type: string }
                amount: { type: number, format: float }
      responses:
        '200':
          description: Captured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
  /ws/query:
    post:
      summary: Query Payment
      operationId: queryPayment
      description: Retrieve the current status and details of a payment by EBANX hash or merchant payment code.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key: { type: string }
                hash: { type: string }
                merchant_payment_code: { type: string }
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
  /ws/cancel:
    post:
      summary: Cancel Payment
      operationId: cancelPayment
      description: Cancel an unpaid or pre-authorized payment.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key: { type: string }
                hash: { type: string }
      responses:
        '200':
          description: Cancellation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
  /ws/refund:
    post:
      summary: Refund Payment
      operationId: refundPayment
      description: Request a full or partial refund for a paid transaction.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        '200':
          description: Refund created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
  /ws/refundOrCancel:
    post:
      summary: Refund Or Cancel Payment
      operationId: refundOrCancelPayment
      description: Cancel the payment if not yet captured, otherwise issue a refund.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
  /ws/instalmentsPlan:
    post:
      summary: List Installments Plan
      operationId: listInstallmentsPlan
      description: Retrieve the available installment plans for a given country, amount, and BIN.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key: { type: string }
                amount: { type: number, format: float }
                currency_code: { type: string }
                country: { type: string }
                payment_type_code: { type: string }
      responses:
        '200':
          description: Installment plan
  /ws/cardbin:
    post:
      summary: Lookup Card BIN
      operationId: lookupCardBin
      description: Identify the issuer, brand, and country for a card BIN.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key: { type: string }
                bin: { type: string }
      responses:
        '200':
          description: BIN information
  /ws/getBankList:
    post:
      summary: List Available Banks
      operationId: listAvailableBanks
      description: List banks available for a given country and payment method.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key: { type: string }
                country: { type: string }
                operation: { type: string }
      responses:
        '200':
          description: Bank list
  /ws/ewallet-availableEWallets:
    post:
      summary: List Available E-Wallets
      operationId: listAvailableEWallets
      description: List e-wallets supported for a given country, currency, and amount.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key: { type: string }
                country: { type: string }
                currency_code: { type: string }
                amount: { type: number, format: float }
      responses:
        '200':
          description: E-wallet list
  /ws/updatecustomerbankinfo:
    post:
      summary: Resend Bank Info
      operationId: updateCustomerBankInfo
      description: Resend the bank slip or transfer information to the customer for a Boleto or bank transfer payment.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_key: { type: string }
                hash: { type: string }
                email: { type: string }
      responses:
        '200':
          description: Result
  /print:
    post:
      summary: Print Voucher Or Slip
      operationId: printVoucherOrSlip
      description: Return a printable HTML or PDF voucher for cash/voucher payment methods such as Boleto, OXXO, Efecty, and PagoEfectivo.
      tags: [Payments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hash: { type: string }
      responses:
        '200':
          description: Printable slip
components:
  securitySchemes:
    integrationKey:
      type: apiKey
      in: header
      name: x-ebanx-integration-key
      description: >-
        EBANX integration key. Historically passed in the JSON body as
        `integration_key`, also accepted via the `x-ebanx-integration-key`
        header. Sandbox and production credentials are distinct.
  schemas:
    DirectPaymentRequest:
      type: object
      required: [integration_key, operation, payment]
      properties:
        integration_key: { type: string }
        operation:
          type: string
          enum: [request]
        payment:
          $ref: '#/components/schemas/Payment'
    Payment:
      type: object
      properties:
        name: { type: string }
        email: { type: string, format: email }
        document: { type: string, description: 'Local tax id (CPF, RFC, NIT, etc.).' }
        country: { type: string, description: 'ISO 3166-1 alpha-2 country code.' }
        payment_type_code:
          type: string
          description: 'Payment method code (e.g., visa, mastercard, _all, pix, boleto, oxxo, spei, pse, efecty).'
        merchant_payment_code: { type: string }
        currency_code: { type: string }
        amount_total: { type: number, format: float }
        instalments: { type: integer, minimum: 1 }
        creditcard:
          type: object
          properties:
            card_number: { type: string }
            card_name: { type: string }
            card_due_date: { type: string }
            card_cvv: { type: string }
            token: { type: string }
    PaymentResponse:
      type: object
      properties:
        status:
          type: string
          enum: [SUCCESS, ERROR]
        payment:
          type: object
          properties:
            hash: { type: string }
            merchant_payment_code: { type: string }
            status: { type: string, enum: [PE, CA, OP, CO, PN] }
            country: { type: string }
            payment_type_code: { type: string }
            amount_br: { type: number }
            amount_iof: { type: number }
            amount_ext: { type: number }
            currency_rate: { type: number }
            currency_ext: { type: string }
            due_date: { type: string, format: date }
            instalments: { type: string }
            transfer_status: { type: string }
        status_code: { type: string }
        status_message: { type: string }
    RefundRequest:
      type: object
      required: [integration_key, operation]
      properties:
        integration_key: { type: string }
        operation:
          type: string
          enum: [request, confirm, cancel]
        hash: { type: string }
        amount: { type: number, format: float }
        description: { type: string }
        refund_id: { type: string }
    RefundResponse:
      type: object
      properties:
        status: { type: string }
        refund:
          type: object
          properties:
            id: { type: string }
            merchant_refund_code: { type: string }
            status: { type: string }
            amount_ext: { type: number }
            description: { type: string }