Purchase a gift card (generate an eGift)

POST /api/v1/gift_cards

Try it ▸

Base URL https://dev-api.finco.lat · operationId purchaseGiftCard

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):

The input is validated against the request schema.
The product is resolved from the payee; if it is not available the request fails with PAYEE_SERVICE_UNAVAILABLE.
The amount is validated against the product's allowed range.
The idempotency_key is checked to reject repeated purchases.
The payee/company must exist and be available.
Balance is checked (only for Prepay clients).
The eGift is generated and the account details are returned.
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.

Authorization

BearerAuth Bearer token

Request body application/json · required

payee_id string required

Id of the service (gift card product) to purchase. Obtained from the Billpay List Payees endpoint 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.

Responses

201 Gift card purchased successfully application/json

gift_card_id string (uuid) required

The payment id.

amount string required

Purchased amount.

payee_id string required

status string required

Payment status.

completed failed pending

created_at string (date-time) required

redeem_link string (uri) required

eGift redemption URL.

401 Missing or invalid Bearer token. application/json

error_type string required

Machine-readable error code.

error_message string required

Human-readable message (localized).

422 The purchase could not be completed. The error_type identifies the cause: application/json

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).

error_type string required

Machine-readable error code.

error_message string required

Human-readable message (localized).

This request is in the Monato · Gift Cards Postman collection.Download collection

Request

curl -X POST "https://dev-api.finco.lat/api/v1/gift_cards" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "payee_id": "7ceee612-c1c1-4758-b5d5-095544113c18",
  "country": "MEX",
  "state": "Baja California",
  "amount": 40,
  "currency": "MXN",
  "idempotency_key": "2026071502"
}'

const body = JSON.stringify({
  "payee_id": "7ceee612-c1c1-4758-b5d5-095544113c18",
  "country": "MEX",
  "state": "Baja California",
  "amount": 40,
  "currency": "MXN",
  "idempotency_key": "2026071502"
});

const res = await fetch("https://dev-api.finco.lat/api/v1/gift_cards", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests

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

res = requests.post(
    "https://dev-api.finco.lat/api/v1/gift_cards",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json=payload,
)
data = res.json()

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

{
  "error_type": "PAYEE_SERVICE_UNAVAILABLE",
  "error_message": "Payee service is not available at this time, retry in 5 minutes"
}

{
  "error_type": "AMOUNT_INVALID",
  "error_message": "Amount is invalid"
}

{
  "error_type": "DUPLICATED_PAYMENT_ERROR",
  "error_message": "This payment is already paid, retry in 24 hours"
}

{
  "error_type": "AMOUNT_INSUFFICIENT",
  "error_message": "The Payee minimum amount was not met"
}

{
  "error_type": "PAYEE_ID_INVALID",
  "error_message": "Payee ID Invalid"
}

{
  "error_type": "PAYEE_SERVICE_UNAVAILABLE",
  "error_message": "Payee service is not available at this time, retry in 5 minutes"
}