Welcome to Monato Giftcards's API Documentation

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.

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.

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.

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.

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

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.

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

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

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

• 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

• 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

• 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

• 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

• 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

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

{ "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)

For additional help and resources:

• API Reference: Review the complete API Reference for detailed endpoint documentation
• Support Contact: Email 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