Sign in

v1

latestOpenAPI 3.1.02026-08-062715.0 KB

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.
post/api/v1/gift_cards

Request body

payee_idstring required

Id of the service (gift card product) to purchase. Obtained from the Billpay List Payees endpoint with category Giftcard.

countrystring

Purchaser country code.

statestring

Purchaser state.

amountnumber float required

Purchase amount. Must be greater than 0 and within the product's allowed range.

currencystring required

Purchase currency. Must be MXN.

idempotency_keystring required

Required. Prevents duplicate purchases. If a duplicate purchase is attempted, the request is rejected with DUPLICATED_PAYMENT_ERROR.

Example request

{
  "payee_id": "7ceee612-c1c1-4758-b5d5-095544113c18",
  "country": "MEX",
  "state": "Baja California",
  "amount": 40,
  "currency": "MXN",
  "idempotency_key": "2026071502"
}

Response

Gift card purchased successfully

gift_card_idstring uuid required

The payment id.

amountstring required

Purchased amount.

payee_idstring required
status'completed' | 'failed' | 'pending' required

Payment status.

created_atstring date-time required
redeem_linkstring uri required

eGift redemption URL.

Example response

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