Xendit Invoices API

openapi: 3.0.3
info:
  title: Xendit API
  description: >-
    Xendit is a payments infrastructure provider for Southeast Asia. This
    OpenAPI document describes a representative, high-fidelity subset of the
    public Xendit REST API grounded in the developer documentation at
    https://docs.xendit.co - the unified Payments API (Payment Requests and
    Payment Tokens), hosted Invoices, Payouts / disbursements, Balance,
    Transactions, Customers, and Refunds. All requests are authenticated with a
    secret API key passed over HTTP Basic (the API key is the username, the
    password is left empty) against the base host https://api.xendit.co.

    Scope note: The newer Payments API resources (payment_requests,
    payment_tokens, payouts v3, refunds) require an `api-version` header. Some
    read/update operations here (get transaction by ID, get/update customer,
    get refund by ID, cancel payout, expire invoice) follow Xendit's documented
    resource conventions but were not each individually confirmed against a
    published reference page at authoring time; they are modeled as
    representative and flagged in review.yml. Xendit does not publish a machine
    -readable OpenAPI file at a single canonical public URL; this document was
    authored by API Evangelist from the human documentation.
  version: '1.0'
  contact:
    name: Xendit
    url: https://www.xendit.co
servers:
  - url: https://api.xendit.co
    description: Xendit production API (test and live keys select the environment)
security:
  - basicAuth: []
tags:
  - name: Payment Requests
    description: Unified Payments API - charge end users across all channels.
  - name: Payment Tokens
    description: Save reusable payment methods for future and recurring charges.
  - name: Invoices
    description: Xendit-hosted invoices / payment links.
  - name: Payouts
    description: Disburse funds to bank accounts and e-wallets.
  - name: Balance
    description: Retrieve account balances by type and currency.
  - name: Transactions
    description: List and retrieve money-movement transactions.
  - name: Customers
    description: Create and manage customer records.
  - name: Refunds
    description: Refund successful payment requests.
paths:
  /v3/payment_requests:
    post:
      operationId: createPaymentRequest
      tags:
        - Payment Requests
      summary: Create a payment request
      description: >-
        Creates a payment request that charges an end user through a chosen
        channel (virtual account, e-wallet, QR, card, direct debit, or retail
        outlet). Requires the api-version header set to 2024-11-11.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/ForUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequestInput'
      responses:
        '201':
          description: The created payment request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/payment_requests/{payment_request_id}:
    parameters:
      - $ref: '#/components/parameters/PaymentRequestId'
    get:
      operationId: getPaymentRequest
      tags:
        - Payment Requests
      summary: Get a payment request
      description: Retrieves the status of a payment request by its ID.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: The requested payment request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/payment_requests/{payment_request_id}/cancel:
    parameters:
      - $ref: '#/components/parameters/PaymentRequestId'
    post:
      operationId: cancelPaymentRequest
      tags:
        - Payment Requests
      summary: Cancel a payment request
      description: >-
        Cancels a payment request, preventing the end user from completing
        payment. The returned object has status CANCELED.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: The cancelled payment request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/payment_tokens:
    post:
      operationId: createPaymentToken
      tags:
        - Payment Tokens
      summary: Create a payment token
      description: >-
        Saves an end user's payment method as a reusable payment token for
        future transactions. Requires the api-version header set to 2024-11-11.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/ForUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentTokenInput'
      responses:
        '201':
          description: The created payment token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/invoices:
    post:
      operationId: createInvoice
      tags:
        - Invoices
      summary: Create an invoice
      description: >-
        Creates a Xendit-hosted invoice / payment link that presents every
        enabled payment channel on a single checkout page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceInput'
      responses:
        '200':
          description: The created invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: getInvoices
      tags:
        - Invoices
      summary: List invoices
      description: Lists invoices, filterable by parameters such as external_id and status.
      parameters:
        - name: external_id
          in: query
          required: false
          description: Filter invoices by the merchant-supplied external ID.
          schema:
            type: string
        - name: statuses
          in: query
          required: false
          description: Filter by invoice status, e.g. ["PENDING","PAID","EXPIRED"].
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: A list of invoices.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/invoices/{invoice_id}:
    parameters:
      - $ref: '#/components/parameters/InvoiceId'
    get:
      operationId: getInvoiceById
      tags:
        - Invoices
      summary: Get an invoice
      description: Retrieves an invoice by its Xendit ID.
      responses:
        '200':
          description: The requested invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{invoice_id}/expire!:
    parameters:
      - $ref: '#/components/parameters/InvoiceId'
    post:
      operationId: expireInvoice
      tags:
        - Invoices
      summary: Expire an invoice
      description: Manually expires an outstanding invoice so it can no longer be paid.
      responses:
        '200':
          description: The expired invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/payouts:
    post:
      operationId: createPayout
      tags:
        - Payouts
      summary: Create a payout
      description: >-
        Disburses funds to a bank account or e-wallet. Requires an
        Idempotency-key header to safely retry without duplicate payouts.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/ForUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutInput'
      responses:
        '200':
          description: The created payout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/payouts/{payout_id}:
    parameters:
      - $ref: '#/components/parameters/PayoutId'
    get:
      operationId: getPayoutById
      tags:
        - Payouts
      summary: Get a payout
      description: Retrieves a payout by its ID.
      responses:
        '200':
          description: The requested payout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/payouts/{payout_id}/cancel:
    parameters:
      - $ref: '#/components/parameters/PayoutId'
    post:
      operationId: cancelPayout
      tags:
        - Payouts
      summary: Cancel a payout
      description: >-
        Cancels a payout that has not yet been disbursed. Modeled from Xendit's
        documented payout resource conventions.
      responses:
        '200':
          description: The cancelled payout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /balance:
    get:
      operationId: getBalance
      tags:
        - Balance
      summary: Get balance
      description: >-
        Retrieves the balance of your Xendit account for a given account type
        and currency, optionally at a point in time.
      parameters:
        - name: account_type
          in: query
          required: false
          description: Account type to query.
          schema:
            type: string
            enum:
              - CASH
              - HOLDING
            default: CASH
        - name: currency
          in: query
          required: false
          description: ISO 4217 currency code.
          schema:
            type: string
            enum:
              - IDR
              - PHP
              - USD
              - VND
              - THB
              - MYR
              - SGD
              - EUR
              - GBP
              - HKD
              - AUD
        - name: at_timestamp
          in: query
          required: false
          description: ISO 8601 timestamp to query a historical balance.
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/ForUserId'
      responses:
        '200':
          description: The account balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transactions:
    get:
      operationId: listTransactions
      tags:
        - Transactions
      summary: List transactions
      description: >-
        Lists money-movement transactions on your account with filters and
        cursor-based pagination.
      parameters:
        - name: types
          in: query
          required: false
          schema:
            type: string
        - name: statuses
          in: query
          required: false
          schema:
            type: string
        - name: channel_categories
          in: query
          required: false
          schema:
            type: string
        - name: reference_id
          in: query
          required: false
          schema:
            type: string
        - name: currency
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
        - name: after_id
          in: query
          required: false
          schema:
            type: string
        - name: before_id
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  has_more:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transactions/{transaction_id}:
    parameters:
      - name: transaction_id
        in: path
        required: true
        description: The ID of the transaction.
        schema:
          type: string
    get:
      operationId: getTransactionById
      tags:
        - Transactions
      summary: Get a transaction
      description: >-
        Retrieves a single transaction by ID. Modeled from Xendit's documented
        transaction resource conventions.
      responses:
        '200':
          description: The requested transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers:
    post:
      operationId: createCustomer
      tags:
        - Customers
      summary: Create a customer
      description: >-
        Creates a customer record (individual or business) for later use with a
        payments endpoint. Uses the api-version header (e.g. 2020-10-31).
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: getCustomers
      tags:
        - Customers
      summary: List customers
      description: Retrieves the customers that match a given reference_id.
      parameters:
        - name: reference_id
          in: query
          required: true
          description: The merchant-supplied reference ID of the customer.
          schema:
            type: string
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: An array of matching customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customer_id}:
    parameters:
      - name: customer_id
        in: path
        required: true
        description: The ID of the customer.
        schema:
          type: string
    get:
      operationId: getCustomerById
      tags:
        - Customers
      summary: Get a customer
      description: >-
        Retrieves a customer by ID. Modeled from Xendit's documented customer
        resource conventions.
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCustomer
      tags:
        - Customers
      summary: Update a customer
      description: >-
        Updates a customer record. Modeled from Xendit's documented customer
        resource conventions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /refunds:
    post:
      operationId: createRefund
      tags:
        - Refunds
      summary: Create a refund
      description: >-
        Initiates a full or partial refund for a successful payment request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundInput'
      responses:
        '200':
          description: The created refund.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /refunds/{refund_id}:
    parameters:
      - name: refund_id
        in: path
        required: true
        description: The ID of the refund.
        schema:
          type: string
    get:
      operationId: getRefundById
      tags:
        - Refunds
      summary: Get a refund
      description: >-
        Retrieves a refund by ID. Modeled from Xendit's documented refund
        resource conventions.
      responses:
        '200':
          description: The requested refund.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. Use your Xendit secret API key as the
        username and leave the password empty. The key is Base64-encoded into
        the Authorization header. Test keys and live keys select the
        environment.
  parameters:
    ApiVersion:
      name: api-version
      in: header
      required: false
      description: >-
        Xendit API version date. The v3 Payments API (payment_requests,
        payment_tokens) expects 2024-11-11; the Customers API accepts dates such
        as 2020-10-31.
      schema:
        type: string
    ForUserId:
      name: for-user-id
      in: header
      required: false
      description: xenPlatform sub-account (Business ID) to act on behalf of.
      schema:
        type: string
    IdempotencyKey:
      name: Idempotency-key
      in: header
      required: false
      description: Unique key to safely retry a request without creating a duplicate.
      schema:
        type: string
    PaymentRequestId:
      name: payment_request_id
      in: path
      required: true
      description: The 39-character payment request ID (e.g. pr-xxxxxxxx-...).
      schema:
        type: string
    PayoutId:
      name: payout_id
      in: path
      required: true
      description: The ID of the payout.
      schema:
        type: string
    InvoiceId:
      name: invoice_id
      in: path
      required: true
      description: The Xendit ID of the invoice.
      schema:
        type: string
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error_code:
          type: string
          description: Machine-readable Xendit error code, e.g. DATA_NOT_FOUND.
        message:
          type: string
    PaymentRequestInput:
      type: object
      required:
        - currency
        - amount
      properties:
        reference_id:
          type: string
          description: Merchant-supplied reference for the payment request.
        currency:
          type: string
          description: ISO 4217 currency code.
        amount:
          type: number
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code (ID, PH, TH, VN, MY, SG).
        payment_method:
          type: object
          description: >-
            The payment method to charge. Selects the channel - VIRTUAL_ACCOUNT,
            EWALLET, QR_CODE, CARD, DIRECT_DEBIT, OVER_THE_COUNTER, etc.
          additionalProperties: true
        customer_id:
          type: string
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
    PaymentRequest:
      type: object
      properties:
        payment_request_id:
          type: string
        reference_id:
          type: string
        business_id:
          type: string
        currency:
          type: string
        amount:
          type: number
        country:
          type: string
        status:
          type: string
          enum:
            - REQUIRES_ACTION
            - PENDING
            - SUCCEEDED
            - FAILED
            - CANCELED
        payment_method:
          type: object
          additionalProperties: true
        actions:
          type: array
          items:
            type: object
            additionalProperties: true
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    PaymentTokenInput:
      type: object
      required:
        - reference_id
        - country
        - currency
        - channel_code
      properties:
        reference_id:
          type: string
        country:
          type: string
        currency:
          type: string
        channel_code:
          type: string
          description: Payment channel provider code, e.g. DANA, OVO, GCASH.
        channel_properties:
          type: object
          additionalProperties: true
        customer_id:
          type: string
    PaymentToken:
      type: object
      properties:
        payment_token_id:
          type: string
        reference_id:
          type: string
        channel_code:
          type: string
        status:
          type: string
          enum:
            - REQUIRES_ACTION
            - PENDING
            - ACTIVE
            - FAILED
            - EXPIRED
            - CANCELED
        created:
          type: string
          format: date-time
    InvoiceInput:
      type: object
      required:
        - external_id
        - amount
      properties:
        external_id:
          type: string
          description: Unique merchant-supplied identifier for the invoice.
        amount:
          type: number
        payer_email:
          type: string
          format: email
        description:
          type: string
        currency:
          type: string
        invoice_duration:
          type: integer
          description: Seconds until the invoice expires.
        success_redirect_url:
          type: string
          format: uri
        failure_redirect_url:
          type: string
          format: uri
    Invoice:
      type: object
      properties:
        id:
          type: string
        external_id:
          type: string
        user_id:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - PAID
            - SETTLED
            - EXPIRED
        merchant_name:
          type: string
        amount:
          type: number
        currency:
          type: string
        invoice_url:
          type: string
          format: uri
        expiry_date:
          type: string
          format: date-time
        created:
          type: string
          format: date-time
    PayoutInput:
      type: object
      required:
        - reference_id
        - channel_code
        - channel_properties
        - amount
        - currency
      properties:
        reference_id:
          type: string
        channel_code:
          type: string
          description: Destination channel, e.g. ID_BCA, PH_GCASH.
        channel_properties:
          type: object
          description: Destination account details (account number, holder name).
          additionalProperties: true
        amount:
          type: number
        currency:
          type: string
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
    Payout:
      type: object
      properties:
        id:
          type: string
        reference_id:
          type: string
        business_id:
          type: string
        channel_code:
          type: string
        amount:
          type: number
        currency:
          type: string
        status:
          type: string
          enum:
            - ACCEPTED
            - PENDING
            - LOCKED
            - CANCELLED
            - SUCCEEDED
            - FAILED
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    Balance:
      type: object
      properties:
        balance:
          type: number
          description: Current balance for the requested account type and currency.
    Transaction:
      type: object
      properties:
        id:
          type: string
        product_id:
          type: string
        type:
          type: string
          description: Transaction type, e.g. PAYMENT, DISBURSEMENT, REFUND, FEE.
        status:
          type: string
          enum:
            - PENDING
            - SUCCESS
            - FAILED
            - VOIDED
            - REVERSED
        channel_category:
          type: string
        reference_id:
          type: string
        amount:
          type: number
        currency:
          type: string
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    CustomerInput:
      type: object
      required:
        - reference_id
        - type
      properties:
        reference_id:
          type: string
        type:
          type: string
          enum:
            - INDIVIDUAL
            - BUSINESS
        individual_detail:
          type: object
          additionalProperties: true
        business_detail:
          type: object
          additionalProperties: true
        email:
          type: string
          format: email
        mobile_number:
          type: string
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
    Customer:
      allOf:
        - $ref: '#/components/schemas/CustomerInput'
        - type: object
          properties:
            id:
              type: string
            created:
              type: string
              format: date-time
            updated:
              type: string
              format: date-time
    RefundInput:
      type: object
      required:
        - payment_request_id
        - reason
      properties:
        payment_request_id:
          type: string
          description: The successful payment request to refund.
        reason:
          type: string
          enum:
            - FRAUDULENT
            - DUPLICATE
            - REQUESTED_BY_CUSTOMER
            - CANCELLATION
            - OTHERS
        amount:
          type: number
          description: Amount to refund; omit for a full refund.
        currency:
          type: string
        reference_id:
          type: string
    Refund:
      type: object
      properties:
        refund_id:
          type: string
        payment_request_id:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - SUCCEEDED
            - FAILED
            - CANCELLED
        amount:
          type: number
        currency:
          type: string
        reason:
          type: string
        created:
          type: string
          format: date-time