---
title: "Purchase a gift card (generate an eGift)"
method: POST
path: "/api/v1/gift_cards"
---

# Purchase a gift card (generate an eGift)

`POST /api/v1/gift_cards`

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.

## Request body

- GiftCardPurchaseRequest
  - `payee_id` string, required — 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`.
  - `country` string — Purchaser country code.
  - `state` string — Purchaser state.
  - `amount` number, float, required — Purchase amount. Must be greater than 0 and within the product's allowed range.
  - `currency` string, required — Purchase currency. Must be MXN.
  - `idempotency_key` string, required — Required. Prevents duplicate purchases. If a duplicate purchase is attempted, the request is rejected with `DUPLICATED_PAYMENT_ERROR`.

## Response `201`

Gift card purchased successfully

- GiftCard — Serialized gift card payment.
  - `gift_card_id` string, uuid, required — The payment id.
  - `amount` string, required — Purchased amount.
  - `payee_id` string, required
  - `status` 'completed' | 'failed' | 'pending', required — Payment status.
  - `created_at` string, date-time, required
  - `redeem_link` string, uri, required — eGift redemption URL.

## Other responses

- `401` — Missing or invalid Bearer token.
- `422` — 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).

---

[API](https://skmtc.dev/monato/apis/monato-s-giftcards-api.md) · [All operations](https://skmtc.dev/monato/apis/monato-s-giftcards-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/monato/monato-s-giftcards-api/revisions/2ad543a96907/schema)