{
  "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\npayment platform.\n\nThis API is designed to be Developer/AI-first, providing comprehensive documentation for easy\nintegration in any programming language. All endpoints require Bearer token authentication.\n\n**Key Features:**\n- Purchase gift cards (generate an eGift) with an idempotency key to prevent duplicates\n\n**Discovering available gift cards:**\n- The list of available gift cards is exposed through the Billpay API. Query the\n  [List Payees endpoint](/products/billpay/billpay-v1/other/listpayees) and filter those whose\n  category is `Giftcard`.\n- Each such payee's id is the `payee_id` you use to purchase a gift card here.\n\n**Important Notes:**\n- Discover available gift cards from the Billpay payees with category `Giftcard` before purchasing.\n- Gift card products are not updated very often, so cache the payees list (category `Giftcard`)\n  on your application server for at least 7 days.\n- The `payee_id` is the id of the service (gift card product) being purchased.\n- All amounts are processed in MXN (Mexican Pesos) and must fall within the product's allowed range.\n- An `idempotency_key` is required on every purchase to prevent duplicate transactions.\n",
    "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\n`category` is `Giftcard` (their `type` is `EGift`), so to obtain the available gift cards call\nthis endpoint with `category=Giftcard`.\n\nEach returned payee's `payee_id` is the id you use to purchase a gift card via\n`POST /api/v1/gift_cards`.\n\nThis is the same payees endpoint exposed by the Billpay API (see the\n[List Payees endpoint](/products/billpay/billpay-v1/other/listpayees)); it is documented here\nfor convenience since it is the way to discover gift cards.\n\n**Caching:** Gift card products are not updated very often, so the catalog returned by this\nendpoint when filtered by `category=Giftcard` should be cached by your application server for\n**at least 7 days** to avoid unnecessary requests.\n",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Exact match on the payee category. Use `Giftcard` to list the available gift cards.\n",
            "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.\n\nThe `payee_id` is obtained from the Billpay\n[List Payees endpoint](/products/billpay/billpay-v1/other/listpayees) with category `Giftcard`.\n\n**Purchase flow** (short-circuits on the first failure):\n1. The input is validated against the request schema.\n2. The product is resolved from the payee; if it is not available the request fails with\n   `PAYEE_SERVICE_UNAVAILABLE`.\n3. The amount is validated against the product's allowed range.\n4. The `idempotency_key` is checked to reject repeated purchases.\n5. The payee/company must exist and be available.\n6. Balance is checked (only for Prepay clients).\n7. The eGift is generated and the account details are returned.\n8. The payment is finalized and, for Prepay clients, the client balance is deducted.\n\n**Implementation Notes:**\n- The `payee_id` is the id of the service (gift card product) being purchased.\n- `currency` must be MXN, and the amount must fall within the product's allowed range.\n- The `idempotency_key` is required to prevent duplicate purchases.\n",
        "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:\n- `PAYEE_ID_INVALID` — the `payee_id` does not exist or has no payment provider.\n- `AMOUNT_INVALID` — amount outside the product's allowed range.\n- `AMOUNT_INSUFFICIENT` — insufficient prepaid balance (Prepay clients).\n- `DUPLICATED_PAYMENT_ERROR` — repeated `idempotency_key`.\n- `PAYEE_TIMEOUT` — the provider timed out (an automatic reversal is enqueued).\n- `PAYEE_SERVICE_UNAVAILABLE` — provider error (fallback).\n",
            "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\n[List Payees endpoint](/products/billpay/billpay-v1/other/listpayees) with category `Giftcard`.\n",
            "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\nis rejected with `DUPLICATED_PAYMENT_ERROR`.\n",
            "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"
        ]
      }
    }
  }
}