openapi: 3.1.0
info:
  title: Belvo Direct Debit API
  version: 1.0.0
  description: >-
    Our Payment infrastructure aims to make moving money between businesses and
    people easy, fast, and modular.
  contact:
    name: Need help?
    url: https://developers.belvo.com
    email: support@belvo.com
servers:
  - url: https://api.sandbox.directdebit.belvo.com
security:
  - sec0: []
    sec1: []
tags:
  - name: Balances (Direct Debit Mexico)
    description: Balances
  - name: Institutions (Direct Debit Mexico)
    description: Direct Debit Institutions
  - name: Customers (Direct Debit Mexico)
    description: >
      A Customer is the end user, either an individual or a business, who owns
      the bank account involved in a debit or payout operation. Belvo Direct
      Debit stores the essential information of this Customer to simplify and
      reuse it across multiple payment methods and payout targets
  - name: Payment Methods (Direct Debit Mexico)
    description: Payment Methods
  - name: Payment Requests (Direct Debit Mexico)
    description: Payment Requests
paths:
  /balance/payments:
    get:
      summary: Get payments balance
      description: Get the details for the current balance of all your payments
      operationId: DetailDirectDebitPaymentBalance
      tags:
        - Balances (Direct Debit Mexico)
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payments_balance'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /customers:
    post:
      summary: Create a customer
      description: Create a new Direct Debit customer
      operationId: CreateDirectDebitCustomer
      tags:
        - Customers (Direct Debit Mexico)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/create_customer_individual'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerId'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /customers/:
    get:
      summary: List all customers
      description: List all Direct Debit customers associated with your account
      operationId: ListDirectDebitCustomers
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/search_customer'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customers_paginated'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /customers/{customerId}:
    post:
      summary: Update a customer
      description: Update an existing direct debit customer
      operationId: UpdateDirectDebitCustomer
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/create_customer_individual'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerId'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Get a customer's details
      description: Get te details regarding a specific direct debit customer
      operationId: DetailDirectDebitCustomer
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/customer_individual'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /institutions:
    get:
      summary: List all institutions
      description: List all institutions available
      operationId: ListDirectDebitInstitutions
      tags:
        - Institutions (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/institutions'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_methods/bank_accounts:
    post:
      summary: Create a payment method
      description: Create a new payment method for a customer
      operationId: CreateDirectDebitPaymentMethod
      tags:
        - Payment Methods (Direct Debit Mexico)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_payment_method'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentMethodId'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_methods:
    get:
      summary: List all payment methods
      description: List all payment methods associated with your account
      operationId: ListDirectDebitPaymentMethods
      tags:
        - Payment Methods (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/search__general'
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/type'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method_paginated'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_methods/{paymentMethodId}:
    get:
      summary: Get a payment method's details
      description: Get the details regarding a specific payment method
      operationId: DetailDirectDebitPaymentMethod
      tags:
        - Payment Methods (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentMethodId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_methods/{paymentMethodId}/deactivate:
    post:
      summary: Deactivate a payment method
      description: >
        Deactivate a specific payment method.


        > 📘 Info

        >

        > You can only deactivate a payment method when the `status` is in the
        `active` state and there are no pending payment requests
        (`paymentRequest.status` = `processing`)
      operationId: DeactivateDirectDebitPaymentMethod
      tags:
        - Payment Methods (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentMethodId'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_requests:
    post:
      summary: Create a payment request
      description: |
        Create a new payment request for an existing payment method.

        > 📘 Idempotency Keys
        >
        > This method supports idempotency keys.
      operationId: CreateDirectDebitPaymentRequest
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/idempotency_key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_payment_request_existing'
      responses:
        '201':
          description: Payment Request Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentRequestId'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: List all payment requests
      description: List all payment requests associated with your account
      operationId: ListDirectDebitPaymentRequests
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/search__general'
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request_paginated'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_requests/{paymentRequestId}:
    get:
      summary: Get a payment request's details
      description: Get the details regarding a specific payment request
      operationId: DetailDirectDebitPaymentRequest
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentRequestId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_requests/{paymentRequestId}/cancel:
    post:
      summary: Cancel a payment request
      description: >
        Cancel a payment request.


        > 📘 Info

        >

        > You can only cancel a payment request when the `status` is in the
        `initial` state.
      operationId: CancelDirectDebitPaymentRequest
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentRequestId'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: api-key-id
    sec1:
      type: apiKey
      in: header
      name: api-key-secret
  schemas:
    payments_available_balance:
      type: object
      description: >
        Amount collected via Direct Debit payment requests and that are
        available for

        withdrawal.
      properties:
        currency:
          type: string
          enum:
            - mxn
          description: >
            The three-letter ISO 4217 currency code of the balance. At the
            moment, we only support `mxn`.
          example: mxn
        amount:
          type: integer
          format: float
          description: The amount available for withdrawal.
    payments_balance:
      type: object
      properties:
        availableBalance:
          $ref: '#/components/schemas/payments_available_balance'
    400_bad_request_error:
      type: object
      title: Bad Request
      description: >
        This error occurs when the parameters provided did not match the
        expected fields or the item you are trying to create is already in our
        database.
      properties:
        statusCode:
          type: integer
          description: The HTTP status code for this error.
          example: 400
        error:
          type: string
          description: The HTTP status code description for this error.
          example: Bad Request
        message:
          oneOf:
            - type: string
              title: Single String
            - type: array
              title: Array of Strings
              items:
                type: string
          description: >-
            A short description of the error, indicating what is wrong with the
            request.

            > **Note**: We return either a string or an array of strings,
            depending on the validation error(s). 


            The description can be (among others):

              - `id must be a UUID`
              - `Not enough balance`
              - `amount is not a valid decimal number.`
              - `currency must be one of the following values: cop, mxn, usd`
              - `reference must be a string`
              - `Customer not found for merchant`
              - `documentType is a required field`
          example: id must be a UUID
    401_unauthorized_error:
      type: object
      title: Unauthorized
      description: >-
        This error occurs when you try to make an API call using incorrect Belvo
        API credentials (either your secret key or secret password, or both, are
        incorrect).
      properties:
        statusCode:
          type: integer
          description: The HTTP status code for this error.
          example: 401
        error:
          type: string
          description: The HTTP status code description for this error.
          example: Unauthorized
        message:
          type: string
          description: >-
            A short description of the error, indicating what is wrong with the
            request.

            In the case of a 401 Unauthorized error, the message is:

              - `Unauthorized credentials`
          example: Unauthorized credentials
    documentType_individual:
      type: string
      title: Individual
      enum:
        - mx_rfc
        - mx_curp
      description: |
        The document type of the individual.

        For 🇲🇽 Mexico, can be one of the following:
          - `mx_rfc`: Tax Identification Number (*Registro Federal de Contribuyentes*)
          - `mx_curp`: Unique Population Registry Code (*Clave Única de Registro de Población*)
      example: mx_rfc
    create_customer_individual:
      type: object
      title: Individual
      description: Request body for creating a direct debit customer.
      required:
        - firstname
        - lastname
        - email
        - documentType
        - documentNumber
      properties:
        firstname:
          type: string
          minLength: 1
          maxLength: 50
          description: The first name of the customer.
          example: Carlos
        lastname:
          type: string
          minLength: 1
          maxLength: 50
          description: The last name of the customer.
          example: Vives
        email:
          type: string
          format: email
          description: The email of the customer.
          example: carlos-vives@musica.mx
        documentType:
          $ref: '#/components/schemas/documentType_individual'
        documentNumber:
          type: string
          description: >
            The document number of the customer.

            For Mexico, this must be 18 characters.


            > **Note**: If the `documentNumber` does not match the expected
            character length and format for a given `documentType`, we return a
            `400 input_validation` error.
          example: '123456789'
        phone:
          type: string
          description: The phone number of the customer (including country code).
          example: '+523001234567'
    customerId:
      type: object
      properties:
        customerId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            The unique identifier created by Belvo used to reference the
            customer.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    404_not_found_error:
      type: object
      title: Not Found
      properties:
        statusCode:
          type: integer
          description: The HTTP status code for this error.
          example: 404
        error:
          type: string
          description: The HTTP status code description for this error.
          example: Not Found
        message:
          type: string
          description: >-
            A short description of the error, indicating what is wrong with the
            request.

            The description can be (among others):

              - `Payout Target not found`
              - `Payment method not found`
              - `Customer not found`
          example: Payout Target not found
    customer_individual:
      type: object
      title: Individual
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            The unique identifier created by Belvo used to reference the
            customer.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >
            The ISO-8601 timestamp when the customer was created in Belvo's
            database.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >
            The ISO-8601 timestamp when information regarding the customer was
            last updated.
          example: '2022-02-09T08:45:50.406032Z'
        firstname:
          type: string
          minLength: 1
          maxLength: 50
          description: The first name of the customer.
          example: Carlos
        lastname:
          type: string
          minLength: 1
          maxLength: 50
          description: The last name of the customer.
          example: Vives
        email:
          type: string
          format: email
          description: The email of the customer.
          example: carlos-vives@musica.mx
        phone:
          type: string
          description: The phone number of the customer (including country code).
          example: '+523001234567'
        country:
          type: string
          pattern: ^[a-z]{3}$
          description: The ISO 3166-1 alpha-3 three-letter country code of the customer.
          example: mex
        documentType:
          $ref: '#/components/schemas/documentType_individual'
        documentNumber:
          type: string
          description: The document number of the customer.
          example: '123456789'
    paginated_meta:
      type: object
      description: Additional metadata regarding the paginated result set.
      properties:
        totalItems:
          type: integer
          format: int32
          description: The total number of items in the paginated result set.
          example: 100
        itemCount:
          type: integer
          format: int32
          description: The number of items in the current page.
          example: 10
        itemsPerPage:
          type: integer
          format: int32
          description: The number of items requested per page.
          example: 10
        totalPages:
          type: integer
          format: int32
          description: The total number of pages in the paginated result set.
          example: 10
        currentPage:
          type: integer
          format: int32
          description: The current page number.
          example: 1
    paginated_links:
      type: object
      description: Links to navigate the paginated result set.
      properties:
        first:
          type: string
          description: The URL to the first page of the paginated result set.
          example: /customers?limit=20
        last:
          type: string
          description: The URL to the last page of the paginated result set.
          example: /customers?page=4&limit=20
        next:
          type: string
          description: The URL to the next page of the paginated result set.
          example: /customers?page=3&limit=20
        previous:
          type: string
          description: The URL to the previous page of the paginated result set.
          example: /customers?page=2&limit=20
    customers_paginated:
      type: object
      properties:
        items:
          type: array
          description: An array of customer objects.
          items:
            oneOf:
              - $ref: '#/components/schemas/customer_individual'
        metadata:
          $ref: '#/components/schemas/paginated_meta'
        links:
          $ref: '#/components/schemas/paginated_links'
    institutions_mexico:
      type: string
      description: >
        Available institutions in Mexico.  For a full list of institutions,
        please see our dedicated <a
        href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
        target="_blank">Payment Institutions</a> page.
      example: mx_citi_banamex
    institutions:
      type: object
      description: Institutions
      properties:
        mx:
          type: array
          description: >
            Available institutions in Mexico. For a full list of institutions,
            please see our dedicated <a
            href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
            target="_blank">Payment Institutions</a> page.
          items:
            $ref: '#/components/schemas/institutions_mexico'
    accountType_mexico:
      type: string
      title: 🇲🇽 Mexico
      enum:
        - savings
        - checking
        - debit_card
      description: |
        The bank account type. Can be either:
          - `savings`
          - `checking`
          - `debit_card`
      example: savings
    bank_mexico:
      type: string
      title: 🇲🇽 Mexico
      description: >
        The name of the Mexican bank where the account is held.



        For a full list of institutions, please see our dedicated <a
        href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
        target="_blank">Payment Institutions</a> page.
      example: mx_citi_banamex
    create_payment_method:
      type: object
      required:
        - accountNumber
        - accountType
        - customerId
        - bank
      properties:
        accountNumber:
          type: string
          description: The bank account or debit card number.
          example: '445566790'
        accountType:
          $ref: '#/components/schemas/accountType_mexico'
        customerId:
          type: string
          format: uuid
          description: >-
            The unique identifier created by Belvo used to reference the
            customer.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        bank:
          $ref: '#/components/schemas/bank_mexico'
        reference:
          type: string
          minLength: 1
          maxLength: 50
          description: An optional reference description for the bank account.
          example: SAVINGS_445566790
    paymentMethodId:
      type: object
      properties:
        paymentMethodId:
          type: string
          format: uuid
          description: >-
            The unique identifier created by Belvo used to reference the payment
            method.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    type_integration_mexico:
      type: string
      title: 🇲🇽 Mexico
      enum:
        - bank_account
      description: |
        The type of account. For Mexico, this value is set to `bank_account`.
      example: bank_account
    customer_payment_method:
      type: object
      description: Details regarding the customer associated with the payment method.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            The unique identifier created by Belvo used to reference the current
            customer.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        firstname:
          type: string
          description: The first name of the customer.
          example: Carlos
        lastname:
          type: string
          description: The last name of the customer.
          example: Vives
        email:
          type: string
          format: email
          description: The email of the customer.
          example: carlos-vives@musica.mx
        phone:
          type: string
          description: The phone number of the customer (including country code).
          example: '+523001234567'
    payment_method_details:
      type: object
      description: Details regarding the bank account associated with the payment method.
      properties:
        accountNumber:
          type: string
          description: The bank account number.
          example: '445566790'
        accountType:
          $ref: '#/components/schemas/accountType_mexico'
        bank:
          $ref: '#/components/schemas/bank_mexico'
    payment_method:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            The unique identifier created by Belvo used to reference the payment
            method.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            The ISO-8601 timestamp when the customer was created in Belvo's
            database.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            The ISO-8601 timestamp when information regarding the customer was
            last updated.
          example: '2022-02-09T08:45:50.406032Z'
        status:
          type: string
          enum:
            - pending_agreement_acceptance
            - waiting_for_activation_response
            - active
            - error
            - inactive
          description: |
            The status of the payment method. Can be either: 
              - `pending_agreement_acceptance`<br>
                The method needs to be accepted by the bank account owner. This can be done either by sending a Setup Link to the owner or by using our Agreements API resource.
              - `waiting_for_activation_response`<br>
                The owner has accepted the payment method. The registration and charge files have been generated.<br>
                The financial institution now needs to send a response regarding bank account information (OK or Not OK).
              - `active`<br>
                The financial institution has successfully confirmed the bank account registration. The payment method can now be used for payment requests. <br>
                **Note**: The status can change to `inactive` if the owner cancels or removes the payment method at the financial institution.
              - `error`<br>
                The financial institution was not able to confirm the bank account registration (usually due to the owner providing incorrect bank account information or an error in the financial institution).
              - `inactive`<br>
                The payment method cannot be used. This is usually due to the owner canceling their account and the financial institution informing us that the method is no longer valid
          example: active
        type:
          $ref: '#/components/schemas/type_integration_mexico'
        customer:
          $ref: '#/components/schemas/customer_payment_method'
        details:
          $ref: '#/components/schemas/payment_method_details'
    payment_method_paginated:
      type: object
      properties:
        items:
          type: array
          description: An array of customer payment method objects.
          items:
            $ref: '#/components/schemas/payment_method'
        metadata:
          $ref: '#/components/schemas/paginated_meta'
        links:
          $ref: '#/components/schemas/paginated_links'
    payment_request:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            The unique identifier created by Belvo used to reference the payment
            request.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >
            The ISO-8601 timestamp when the payment request was created in
            Belvo's database.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >
            The ISO-8601 timestamp when information regarding the payment
            request was last updated.
          example: '2022-02-09T08:45:50.406032Z'
        status:
          type: string
          enum:
            - initial
            - processing
            - successful
            - failed
            - canceled
          description: |
            The status of the payment request. Can be either:
              - `initial`<br>
                The payment request has been created.
              - `processing`<br>
                The charge files have been generated for the payment request. Awaiting response from the financial institution.
              - `successful`<br>
                The financial institution has confirmed the payment request and the funds have been transferred.
              - `failed`<br>
                The financial institution has reported an error for the payment request and no funds have been transferred.
              - `canceled`<br>
                The request was canceled. This is only possible if the payment request has not transitioned to the `processing` status.
          example: processing
        failedReason:
          type:
            - string
            - 'null'
          description: |
            The financial institution's failure code.
          example: null
        failedReasonMessage:
          type:
            - string
            - 'null'
          description: >
            The financial institution's failure message, describing the reason
            for the failure.
          example: null
        amount:
          type: string
          description: The amount to debit from the customer.
          example: '100000.00'
        currency:
          type: string
          enum:
            - mxn
          description: >
            The three-letter ISO 4217 currency code of the transaction. At the
            moment, we only support `mxn`.
          example: mxn
        customer:
          type: string
          format: uuid
          description: >-
            The unique identifier created by Belvo used to reference the
            customer.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        customerName:
          type: string
          description: The name of the customer.
          example: Carlos Vives
        reference:
          type: string
          minLength: 1
          maxLength: 160
          description: A reference for the payment request.
          example: Monthly gym subscription
        paymentMethod:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/type_integration_mexico'
            details:
              $ref: '#/components/schemas/payment_method_details'
    payment_request_paginated:
      type: object
      properties:
        items:
          type: array
          description: An array of payment request objects.
          items:
            $ref: '#/components/schemas/payment_request'
        metadata:
          $ref: '#/components/schemas/paginated_meta'
        links:
          $ref: '#/components/schemas/paginated_links'
    create_payment_request_existing:
      type: object
      title: Existing payment method
      description: >-
        The request body for creating a payment request for an existing payment
        method.
      required:
        - amount
        - currency
        - reference
        - paymentMethodId
      properties:
        amount:
          type: number
          format: float
          description: The amount to debit from the customer.
          example: 1000
        currency:
          type: string
          enum:
            - mxn
          description: >
            The three-letter ISO 4217 currency code of the transaction. At the
            moment, we only support `mxn`.
          example: mxn
        reference:
          type: string
          minLength: 1
          maxLength: 50
          description: |
            Your internal reference for the payment request.
          example: J-789029-PAY-3X
        paymentMethodId:
          type: string
          format: uuid
          description: >-
            The unique identifier created by Belvo used to reference the payment
            method.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    paymentRequestId:
      type: object
      properties:
        paymentRequestId:
          type: string
          format: uuid
          description: >-
            The unique identifier created by Belvo used to reference the payment
            request.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
  parameters:
    page:
      name: page
      required: false
      in: query
      description: A page number within the paginated result set.
      schema:
        example: 1
        format: int32
        type: integer
    limit:
      name: limit
      required: false
      in: query
      description: >
        Indicates how many results to return per page. By default we return 20
        results

        per page.



        ℹ️ The minimum number of results returned per page is 1 and the maximum
        is 100.

        If you enter a value greater than 100, our API will default to the
        maximum

        value (100).
      schema:
        type: integer
        format: int32
        default: 20
        minimum: 1
        maximum: 100
        example: 15
    search_customer:
      name: search
      required: false
      in: query
      description: >
        Return results that match the `email`, `firstname`, `lastname`, or
        `documentNumber` you searched for. 


        **Note:**


        This filter supports both full and partial search queries.


        For example, searching for `car` may match the following values:

          - `carlos.vives@musicamexico.mx` (`email`)
          - `Carlos` (`firstname`)
          - `Cartregena` (`lastname`)
          - `789-CAR-789456789` (`documentNumber`)
      schema:
        type: string
        example: trai
    customerId:
      name: customerId
      required: true
      in: path
      description: |
        The unique identifier created by Belvo used to reference the customer.
      schema:
        type: string
        format: uuid
        example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    search__general:
      name: search
      required: false
      in: query
      description: >
        Return results that match the `reference` you searched for. 



        **Note:**

        This filter supports both full and partial search queries. For example,
        searching for `trai` may match the following values (extacted

        from the `reference` field)):

          - `Awesome training sneakers` 
          - `Training equipment`
      schema:
        type: string
        example: trai
    customer_id:
      name: customer_id
      required: false
      in: query
      description: |
        The unique identifier created by Belvo used to reference the customer.
      schema:
        type: string
        format: uuid
        example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    type:
      name: type
      required: false
      in: query
      description: |
        The type of account. Can be either:

          - `bank_account`
            Used for most bank accounts.
      schema:
        type: string
        enum:
          - bank_account
        example: bank_account
    paymentMethodId:
      name: paymentMethodId
      required: true
      in: path
      description: >
        The unique identifier created by Belvo used to reference the payment
        method.
      schema:
        type: string
        format: uuid
        example: d5f2e1a8-f449-4338-bd6a-df62b3fbf0b3
    order:
      name: order
      required: false
      in: query
      description: >
        Return results in either ascending (oldest to newest) or descending
        (newest to oldest) order, according to the `createdDate`.


        Can be either:
          - `asc` for ascending order
          - `desc` for descending order
      schema:
        enum:
          - asc
          - desc
        example: asc
        type: string
    start_date:
      name: start_date
      required: false
      in: query
      description: >
        Return items with a `createdDate` greater than or equal to the specified
        date. The date must be in the format `YYYY-MM-DD`.
      schema:
        type: string
        format: date
        pattern: ^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$
        example: '2024-01-01'
    end_date:
      name: end_date
      required: false
      in: query
      description: >
        Return items with a `createdDate` less than or equal to the specified
        date. The date must be in the format `YYYY-MM-DD`.
      schema:
        type: string
        format: date
        pattern: ^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$
        example: '2024-01-30'
    idempotency_key:
      name: Idempotency-Key
      required: false
      in: header
      description: >
        (Optional, but highly recommended.) A unique identifier for this request
        to support idempotency. Use a UUID or

        similar identifier. For more information, see our dedicated <a
        href="https://developers.belvo.com/docs/direct-debit-idempotency-and-whitelisting"
        target="_blank">Idempotency</a> article.
      schema:
        type: string
    paymentRequestId:
      name: paymentRequestId
      required: true
      in: path
      description: >
        The unique identifier created by Belvo used to reference the payment
        request.
      schema:
        type: string
        format: uuid
        example: 2e66d035-c78f-435c-a21d-b86d3e7b351d
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true
