openapi: 3.1.0
info:
  title: Monato's Giftcards API
  version: 1.0.0
  description: >
    Monato Giftcards API provides endpoints for selling digital gift cards
    (eGift) through Monato's

    payment platform.


    This API is designed to be Developer/AI-first, providing comprehensive
    documentation for easy

    integration in any programming language. All endpoints require Bearer token
    authentication.


    **Key Features:**

    - Purchase gift cards (generate an eGift) with an idempotency key to prevent
    duplicates


    **Discovering available gift cards:**

    - The list of available gift cards is exposed through the Billpay API. Query
    the
      [List Payees endpoint](/products/billpay/billpay-v1/other/listpayees) and filter those whose
      category is `Giftcard`.
    - Each such payee's id is the `payee_id` you use to purchase a gift card
    here.


    **Important Notes:**

    - Discover available gift cards from the Billpay payees with category
    `Giftcard` before purchasing.

    - Gift card products are not updated very often, so cache the payees list
    (category `Giftcard`)
      on your application server for at least 7 days.
    - The `payee_id` is the id of the service (gift card product) being
    purchased.

    - All amounts are processed in MXN (Mexican Pesos) and must fall within the
    product's allowed range.

    - An `idempotency_key` is required on every purchase to prevent duplicate
    transactions.
  contact:
    name: Monato Support
    email: engineering@monato.com
servers:
  - url: https://dev-api.finco.lat
security:
  - BearerAuth: []
paths:
  /api/v1/payees:
    get:
      summary: List gift card payees
      operationId: listGiftcardPayees
      description: >
        Returns the payees available to the authenticated client. Gift cards are
        the payees whose

        `category` is `Giftcard` (their `type` is `EGift`), so to obtain the
        available gift cards call

        this endpoint with `category=Giftcard`.


        Each returned payee's `payee_id` is the id you use to purchase a gift
        card via

        `POST /api/v1/gift_cards`.


        This is the same payees endpoint exposed by the Billpay API (see the

        [List Payees endpoint](/products/billpay/billpay-v1/other/listpayees));
        it is documented here

        for convenience since it is the way to discover gift cards.


        **Caching:** Gift card products are not updated very often, so the
        catalog returned by this

        endpoint when filtered by `category=Giftcard` should be cached by your
        application server for

        **at least 7 days** to avoid unnecessary requests.
      security:
        - BearerAuth: []
      parameters:
        - name: category
          in: query
          required: false
          description: >
            Exact match on the payee category. Use `Giftcard` to list the
            available gift cards.
          schema:
            type: string
          example: Giftcard
        - name: page
          in: query
          required: false
          description: Page number (starts at 1).
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
        - name: name
          in: query
          required: false
          description: Case-insensitive partial match on the payee display name.
          schema:
            type: string
            minLength: 1
          example: Amazon
      responses:
        '200':
          description: Gift card payees retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayeesIndexResponse'
              examples:
                giftcard_example:
                  summary: Giftcard payees list
                  value:
                    meta:
                      current_page: 1
                      next_page: null
                      prev_page: null
                      total_pages: 1
                      total_count: 1
                    payees:
                      - payee_id: 1a079e9a-2bee-46e0-a993-32b714cf0c09
                        name: Amazon eGift - MEX
                        category: Giftcard
                        type: EGift
                        currency: MXN
                        reference_config:
                          regex: null
                        images:
                          small:
                            id: MEDIUM
                            url: >-
                              https://content.monato.com/giftcards/medium/amazon.png
                          large:
                            id: EXTRA_LARGE
                            url: >-
                              https://content.monato.com/giftcards/xlarge/amazon.png
                        redemption_info: ''
                        price: '5.0'
                empty_results:
                  summary: Empty result set
                  value:
                    meta:
                      current_page: 1
                      next_page: null
                      prev_page: null
                      total_pages: 0
                      total_count: 0
                    payees: []
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/gift_cards:
    post:
      summary: Purchase a gift card (generate an eGift)
      operationId: purchaseGiftCard
      description: >
        Generates an eGift for the chosen product and amount, and persists the
        resulting payment.


        The `payee_id` is obtained from the Billpay

        [List Payees endpoint](/products/billpay/billpay-v1/other/listpayees)
        with category `Giftcard`.


        **Purchase flow** (short-circuits on the first failure):

        1. The input is validated against the request schema.

        2. The product is resolved from the payee; if it is not available the
        request fails with
           `PAYEE_SERVICE_UNAVAILABLE`.
        3. The amount is validated against the product's allowed range.

        4. The `idempotency_key` is checked to reject repeated purchases.

        5. The payee/company must exist and be available.

        6. Balance is checked (only for Prepay clients).

        7. The eGift is generated and the account details are returned.

        8. The payment is finalized and, for Prepay clients, the client balance
        is deducted.


        **Implementation Notes:**

        - The `payee_id` is the id of the service (gift card product) being
        purchased.

        - `currency` must be MXN, and the amount must fall within the product's
        allowed range.

        - The `idempotency_key` is required to prevent duplicate purchases.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GiftCardPurchaseRequest'
            examples:
              example-1:
                summary: Gift card purchase
                value:
                  payee_id: 7ceee612-c1c1-4758-b5d5-095544113c18
                  country: MEX
                  state: Baja California
                  amount: 40
                  currency: MXN
                  idempotency_key: '2026071502'
      responses:
        '201':
          description: Gift card purchased successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GiftCard'
              example:
                gift_card_id: 702d2533-19c9-4105-abe3-e7542ee47e4e
                amount: '40.0'
                payee_id: 7ceee612-c1c1-4758-b5d5-095544113c18
                status: completed
                created_at: '2026-07-15T21:33:56.653Z'
                redeem_link: >-
                  https://egift.monato.com/egift?eid=Z8X05NA1WR2JRBDG8F3NW9385H&tid=CD6RPC2K8JH2MMW5PHN6SY07GM
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: >
            The purchase could not be completed. The `error_type` identifies the
            cause:

            - `PAYEE_ID_INVALID` — the `payee_id` does not exist or has no
            payment provider.

            - `AMOUNT_INVALID` — amount outside the product's allowed range.

            - `AMOUNT_INSUFFICIENT` — insufficient prepaid balance (Prepay
            clients).

            - `DUPLICATED_PAYMENT_ERROR` — repeated `idempotency_key`.

            - `PAYEE_TIMEOUT` — the provider timed out (an automatic reversal is
            enqueued).

            - `PAYEE_SERVICE_UNAVAILABLE` — provider error (fallback).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_amount:
                  value:
                    error_type: AMOUNT_INVALID
                    error_message: Amount is invalid
                duplicated:
                  value:
                    error_type: DUPLICATED_PAYMENT_ERROR
                    error_message: This payment is already paid, retry in 24 hours
                insufficient_balance:
                  value:
                    error_type: AMOUNT_INSUFFICIENT
                    error_message: The Payee minimum amount was not met
                invalid_payee:
                  value:
                    error_type: PAYEE_ID_INVALID
                    error_message: Payee ID Invalid
                service_unavailable:
                  value:
                    error_type: PAYEE_SERVICE_UNAVAILABLE
                    error_message: >-
                      Payee service is not available at this time, retry in 5
                      minutes
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Access Token
  responses:
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PayeesIndexResponse:
      type: object
      required:
        - meta
        - payees
      properties:
        meta:
          $ref: '#/components/schemas/PayeesMeta'
        payees:
          type: array
          items:
            $ref: '#/components/schemas/GiftcardPayee'
    PayeesMeta:
      type: object
      description: Pagination metadata.
      properties:
        current_page:
          type: integer
          example: 1
        next_page:
          type:
            - integer
            - 'null'
          example: null
        prev_page:
          type:
            - integer
            - 'null'
          example: null
        total_pages:
          type: integer
          example: 1
        total_count:
          type: integer
          example: 1
    GiftcardPayee:
      type: object
      description: A gift card payee (category `Giftcard`, type `EGift`).
      properties:
        payee_id:
          type: string
          format: uuid
          description: The id you use to purchase a gift card.
          example: 1a079e9a-2bee-46e0-a993-32b714cf0c09
        name:
          type: string
          example: Amazon eGift - MEX
        category:
          type: string
          example: Giftcard
        type:
          type: string
          example: EGift
        currency:
          type: string
          example: MXN
        reference_config:
          type: object
          properties:
            regex:
              type:
                - string
                - 'null'
              example: null
        images:
          type: object
          description: Product images by size.
          properties:
            small:
              $ref: '#/components/schemas/PayeeImage'
            large:
              $ref: '#/components/schemas/PayeeImage'
        redemption_info:
          type: string
          example: ''
        price:
          type: string
          description: Gift card value amount.
          example: '5.0'
    PayeeImage:
      type: object
      properties:
        id:
          type: string
          example: MEDIUM
        url:
          type: string
          format: uri
          example: https://content.monato.com/giftcards/medium/amazon.png
    GiftCardPurchaseRequest:
      type: object
      required:
        - payee_id
        - amount
        - currency
        - idempotency_key
      properties:
        payee_id:
          type: string
          description: >
            Id of the service (gift card product) to purchase. Obtained from the
            Billpay

            [List Payees
            endpoint](/products/billpay/billpay-v1/other/listpayees) with
            category `Giftcard`.
          example: 7ceee612-c1c1-4758-b5d5-095544113c18
        country:
          type: string
          description: Purchaser country code.
          example: MEX
        state:
          type: string
          description: Purchaser state.
          example: Baja California
        amount:
          type: number
          format: float
          exclusiveMinimum: 0
          description: >-
            Purchase amount. Must be greater than 0 and within the product's
            allowed range.
          example: 40
        currency:
          type: string
          description: Purchase currency. Must be MXN.
          example: MXN
        idempotency_key:
          type: string
          description: >
            Required. Prevents duplicate purchases. If a duplicate purchase is
            attempted, the request

            is rejected with `DUPLICATED_PAYMENT_ERROR`.
          example: '2026071502'
    GiftCard:
      type: object
      description: Serialized gift card payment.
      properties:
        gift_card_id:
          type: string
          format: uuid
          description: The payment id.
          example: 702d2533-19c9-4105-abe3-e7542ee47e4e
        amount:
          type: string
          description: Purchased amount.
          example: '40.0'
        payee_id:
          type: string
          example: 7ceee612-c1c1-4758-b5d5-095544113c18
        status:
          type: string
          description: Payment status.
          enum:
            - completed
            - failed
            - pending
          example: completed
        created_at:
          type: string
          format: date-time
          example: '2026-07-15T21:33:56.653Z'
        redeem_link:
          type: string
          format: uri
          description: eGift redemption URL.
          example: >-
            https://egift.monato.com/egift?eid=Z8X05NA1WR2JRBDG8F3NW9385H&tid=CD6RPC2K8JH2MMW5PHN6SY07GM
      required:
        - gift_card_id
        - amount
        - payee_id
        - status
        - created_at
        - redeem_link
    Error:
      type: object
      description: Standard error envelope.
      properties:
        error_type:
          type: string
          description: Machine-readable error code.
          example: PAYEE_SERVICE_UNAVAILABLE
        error_message:
          type: string
          description: Human-readable message (localized).
          example: Payee service is not available at this time, retry in 5 minutes
      required:
        - error_type
        - error_message
