Docs

Gift Cards · Guides

Purchase a gift card

Generate an eGift for a gift card and an amount, and get the redeem link.

A purchase generates an eGift for the chosen gift card and amount, and saves it as a payment.

Before you start

  • Get the payee_id from the gift card catalog.
  • Generate a unique idempotency_key for this purchase.
  • For Prepay clients, make sure your prepaid balance covers the amount.

Request

Purchase a gift card
curl https://dev-api.finco.lat/api/v1/gift_cards \
  -H 'Authorization: Bearer your_api_key' \
  -H 'Content-Type: application/json' \
  --data '{
    "payee_id": "7ceee612-c1c1-4758-b5d5-095544113c18",
    "country": "MEX",
    "state": "Baja California",
    "amount": 40.0,
    "currency": "MXN",
    "idempotency_key": "2026071502"
  }'
Field Required Description
payee_id Yes ID of the gift card to purchase, from the catalog
amount Yes Purchase amount. Must be greater than 0 and within the gift card’s allowed range.
currency Yes Must be MXN
idempotency_key Yes Unique key that prevents duplicate purchases
country No Purchaser country code
state No Purchaser state

See Purchase a gift card.

Response

201 Created
{
  "gift_card_id": "702d2533-19c9-4105-abe3-e7542ee47e4e",
  "amount": "40.0",
  "payee_id": "7ceee612-c1c1-4758-b5d5-095544113c18",
  "status": "completed",
  "created_at": "2026-07-15T21:33:56.653Z",
  "redeem_link": "https://egift.monato.com/egift?eid=Z8X05NA1WR2JRBDG8F3NW9385H&tid=CD6RPC2K8JH2MMW5PHN6SY07GM"
}

Store the gift_card_id and the redeem_link. Give the redeem link to your user.

What the purchase checks

The purchase runs these steps in order and stops at the first failure:

  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 must exist and be available.
  6. Balance check. Only for Prepay clients.
  7. eGift generation. The payment is created and the eGift is generated.
  8. Finalization. The payment is finalized. For Prepay clients, the balance is deducted.

If any step fails, you get a 422 with an error_type. See Error codes.

If the provider times out

You get PAYEE_TIMEOUT and Monato queues an automatic reversal. See Timeouts and reversals.