# Welcome to Monato Giftcards's API Documentation

## Description

The Monato Giftcards API enables businesses and developers to sell **digital gift cards (eGift)** directly from their applications. A gift card is a payee of type `Giftcard` that is "paid" by generating an eGift. Every successful purchase is persisted as a payment record.

When you integrate this API, your application can:

- **Discover Available Gift Cards**: The list of available gift cards is exposed through the Billpay API — query its payees and filter those whose category is `Giftcard`
- **Purchase Gift Cards**: Generate an eGift for a given gift card and amount, receiving the redeem link


The API is designed to be Developer first, providing comprehensive documentation that makes integration straightforward in any programming language. All operations are secured with Bearer token authentication, ensuring safe and reliable transactions.

## Key Features

### Reliable Purchase Flow

The purchase operation is railway-oriented and short-circuits on the first failure, validating input, product availability, amount range, and (for Prepay clients) balance before generating the eGift. This ensures you only ever receive a completed gift card when every precondition is met.

### Idempotent Purchases

Every purchase **requires** an `idempotency_key` to prevent duplicate purchases. If a duplicate purchase is attempted, the request is rejected with a `DUPLICATED_PAYMENT_ERROR`.

### Automatic Reversal on Timeout

If the provider times out during a purchase, the API returns a `PAYEE_TIMEOUT` error and enqueues an automatic reversal job so the transaction is not left in an inconsistent state.

### Developer-Friendly Design

- Clear, comprehensive documentation
- Language-agnostic API design
- Standard HTTP/REST protocols
- JSON request/response format
- Consistent, machine-readable error envelope


## Operation Types

### Discovering Available Gift Cards

Available gift cards are exposed through the Billpay API. Query the payees and filter those whose category is `Giftcard`; each such payee's id is the `payee_id` you use to purchase a gift card.

Gift card products are not updated very often, so you should cache the payees list (category `Giftcard`) on your application server for **at least 7 days** to avoid unnecessary requests.

### Gift Card Purchase

Generates an eGift for the chosen gift card and amount, and persists the resulting payment. The flow:

1. **Validation**: The input is validated against the request schema
2. **Product Resolution**: The product is resolved from the payee; if it is not available the request fails with `PAYEE_SERVICE_UNAVAILABLE`
3. **Amount Validation**: The amount is checked against the product's allowed range
4. **Duplicate Check**: The `idempotency_key` is checked to reject repeated purchases
5. **Payee Validation**: The payee/company must exist and be available
6. **Balance Check**: Performed only for Prepay clients
7. **eGift Generation**: The payment is created and the eGift is generated
8. **Finalization**: The payment is finalized and, for Prepay clients, the client balance is deducted


## Getting Started

### Prerequisites

Before you begin integrating the Giftcards API, ensure you have:

1. **Access Credentials**: Obtain your Bearer token from the Monato support team
2. **API Endpoint**: Know the correct API base URL for your environment (staging or production)
3. **Integration Environment**: Set up your development environment with HTTP client capabilities


### Integration Workflow

The typical integration follows this pattern:

1. **Authenticate**: Include your Bearer token in all API requests using the Authorization header
2. **Discover Gift Cards**: Query the Billpay payees and filter those with category `Giftcard` to get valid `payee_id` values and their amount ranges
3. **Purchase**: Send a purchase request with the chosen payee, amount, and a unique idempotency key
4. **Handle Response**: Store the returned gift card details (id, redeem link) and handle any errors


### What You'll Need to Provide

- **Payee ID**: The id of the service (gift card) to purchase, obtained from the Billpay payees with category `Giftcard`
- **Amount**: A value within the gift card's allowed range, in MXN
- **Currency**: Must be MXN
- **Country and State**: The purchaser's location
- **Idempotency Key** (required): A unique key to prevent duplicate purchases


### What You'll Receive

- **Gift Card ID**: Unique identifier for the purchased gift card
- **Amount**: The purchased amount
- **Redeem Link**: The eGift redemption URL
- **Status**: The current payment status (`completed`, `failed`, or `pending`)
- **Created At**: The timestamp of the purchase


## Business Rules

### Discovery Requirements

- **Discover via Billpay**: Obtain available gift cards from the Billpay payees with category `Giftcard` before purchasing
- **Cache the Catalog**: Gift card products change infrequently — cache the payees list (category `Giftcard`) on your application server for at least 7 days
- **Respect Amount Ranges**: Purchases must fall within each gift card's allowed range


### Purchase Rules

- **Positive Amount**: The amount must be greater than 0 and within the gift card's allowed range
- **Currency**: All amounts are processed in MXN (Mexican Pesos)
- **Payee Identifies the Product**: The `payee_id` is the id of the service being purchased
- **Prepay Balance**: Prepay clients must have sufficient prepaid balance for the purchase


### Idempotency Rules

- **Required Key**: Every purchase must include an `idempotency_key`
- **Unique Keys**: Use a unique `idempotency_key` per purchase to prevent duplicates
- **Duplicate Rejection**: Duplicate purchases are rejected with `DUPLICATED_PAYMENT_ERROR`


### Error Handling

Except where noted, every error is returned with HTTP `422 Unprocessable Entity` and a consistent envelope:

```json
{ "error_type": "PAYEE_SERVICE_UNAVAILABLE", "error_message": "..." }
```

Common `error_type` values:

- **PAYEE_ID_INVALID**: The `payee_id` does not exist or has no payment provider
- **AMOUNT_INVALID**: Amount outside the gift card'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)


## Support and Resources

For additional help and resources:

- **API Reference**: Review the complete [API Reference](/products/giftcards/giftcards-openapi) for detailed endpoint documentation
- **Support Contact**: Email [engineering@monato.com](mailto:engineering@monato.com) for assistance with credentials, integration questions, or technical support
- **Office Hours**: Schedule a call with our technical team, we are Whatsapp and Slack Friendly


*Monato: Powering the future of payments in Mexico*