# Monato's Giftcards API

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.


Version: 1.0.0

## Servers

```
https://dev-api.finco.lat
```

## Security

### BearerAuth

Type: http
Scheme: bearer
Bearer Format: Access Token

## Download OpenAPI description

[Monato's Giftcards API](https://docs.monato.com/_bundle/products/giftcards/giftcards-openapi.yaml)

## Other

### List gift card payees

 - [GET /api/v1/payees](https://docs.monato.com/products/giftcards/giftcards-openapi/other/listgiftcardpayees.md): 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); 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.

### Purchase a gift card (generate an eGift)

 - [POST /api/v1/gift_cards](https://docs.monato.com/products/giftcards/giftcards-openapi/other/purchasegiftcard.md): 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 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.