# Purchase a gift card (generate an eGift)

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.

Endpoint: POST /api/v1/gift_cards
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `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.
    Example: "7ceee612-c1c1-4758-b5d5-095544113c18"

  - `country` (string)
    Purchaser country code.
    Example: "MEX"

  - `state` (string)
    Purchaser state.
    Example: "Baja California"

  - `amount` (number, required)
    Purchase amount. Must be greater than 0 and within the product's allowed range.
    Example: 40

  - `currency` (string, required)
    Purchase currency. Must be MXN.
    Example: "MXN"

  - `idempotency_key` (string, required)
    Required. Prevents duplicate purchases. If a duplicate purchase is attempted, the request
is rejected with DUPLICATED_PAYMENT_ERROR.
    Example: "2026071502"

## Response 201 fields (application/json):

  - `gift_card_id` (string, required)
    The payment id.
    Example: "702d2533-19c9-4105-abe3-e7542ee47e4e"

  - `amount` (string, required)
    Purchased amount.
    Example: "40.0"

  - `payee_id` (string, required)
    Example: "7ceee612-c1c1-4758-b5d5-095544113c18"

  - `status` (string, required)
    Payment status.
    Enum: "completed", "failed", "pending"

  - `created_at` (string, required)
    Example: "2026-07-15T21:33:56.653Z"

  - `redeem_link` (string, required)
    eGift redemption URL.
    Example: "https://egift.monato.com/egift?eid=Z8X05NA1WR2JRBDG8F3NW9385H&tid=CD6RPC2K8JH2MMW5PHN6SY07GM"

## Response 401 fields (application/json):

  - `error_type` (string, required)
    Machine-readable error code.
    Example: "PAYEE_SERVICE_UNAVAILABLE"

  - `error_message` (string, required)
    Human-readable message (localized).
    Example: "Payee service is not available at this time, retry in 5 minutes"