{
  "info": {
    "_postman_id": "9725eb6d-0308-5a86-97b9-d11bae5bdffa",
    "name": "Monato · Gift Cards",
    "description": "Monato's Giftcards API 1.0.0. Generated from `products/giftcards/giftcards-openapi.yaml`.\n\nSelect the Monato Sandbox environment and fill in your credentials, then send any request.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "List gift card payees",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{finBaseUrl}}/api/v1/payees",
          "host": [
            "{{finBaseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "payees"
          ],
          "query": [
            {
              "key": "category",
              "value": "Giftcard",
              "description": "Exact match on the payee category. Use `Giftcard` to list the available gift cards.",
              "disabled": true
            },
            {
              "key": "page",
              "value": "1",
              "description": "Page number (starts at 1).",
              "disabled": true
            },
            {
              "key": "name",
              "value": "Amazon",
              "description": "Case-insensitive partial match on the payee display name.",
              "disabled": true
            }
          ]
        },
        "description": "Returns the payees available to the authenticated client. Gift cards are the payees whose\n`category` is `Giftcard` (their `type` is `EGift`), so to obtain the available gift cards call\nthis endpoint with `category=Giftcard`.\n\nEach returned payee's `payee_id` is the id you use to purchase a gift card via\n`POST /api/v1/gift_cards`.\n\nThis is the same payees endpoint exposed by the Billpay API (see the\n[List Payees endpoint](/products/billpay/billpay-v1/other/listpayees)); it is documented here\nfor convenience since it is the way to discover gift cards.\n\n**Caching:** Gift card products are not updated very often, so the catalog returned by this\nendpoint when filtered by `category=Giftcard` should be cached by your application server for\n**at least 7 days** to avoid unnecessary requests.",
        "auth": {
          "type": "bearer",
          "bearer": [
            {
              "key": "token",
              "value": "{{finAccessToken}}",
              "type": "string"
            }
          ]
        }
      },
      "response": [
        {
          "name": "200 Giftcard payees list",
          "originalRequest": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/payees",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "payees"
              ],
              "query": [
                {
                  "key": "category",
                  "value": "Giftcard",
                  "description": "Exact match on the payee category. Use `Giftcard` to list the available gift cards.",
                  "disabled": true
                },
                {
                  "key": "page",
                  "value": "1",
                  "description": "Page number (starts at 1).",
                  "disabled": true
                },
                {
                  "key": "name",
                  "value": "Amazon",
                  "description": "Case-insensitive partial match on the payee display name.",
                  "disabled": true
                }
              ]
            }
          },
          "code": 200,
          "status": "Gift card payees retrieved successfully.",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"meta\": {\n    \"current_page\": 1,\n    \"next_page\": null,\n    \"prev_page\": null,\n    \"total_pages\": 1,\n    \"total_count\": 1\n  },\n  \"payees\": [\n    {\n      \"payee_id\": \"1a079e9a-2bee-46e0-a993-32b714cf0c09\",\n      \"name\": \"Amazon eGift - MEX\",\n      \"category\": \"Giftcard\",\n      \"type\": \"EGift\",\n      \"currency\": \"MXN\",\n      \"reference_config\": {\n        \"regex\": null\n      },\n      \"images\": {\n        \"small\": {\n          \"id\": \"MEDIUM\",\n          \"url\": \"https://content.monato.com/giftcards/medium/amazon.png\"\n        },\n        \"large\": {\n          \"id\": \"EXTRA_LARGE\",\n          \"url\": \"https://content.monato.com/giftcards/xlarge/amazon.png\"\n        }\n      },\n      \"redemption_info\": \"\",\n      \"price\": \"5.0\"\n    }\n  ]\n}"
        },
        {
          "name": "200 Empty result set",
          "originalRequest": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/payees",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "payees"
              ],
              "query": [
                {
                  "key": "category",
                  "value": "Giftcard",
                  "description": "Exact match on the payee category. Use `Giftcard` to list the available gift cards.",
                  "disabled": true
                },
                {
                  "key": "page",
                  "value": "1",
                  "description": "Page number (starts at 1).",
                  "disabled": true
                },
                {
                  "key": "name",
                  "value": "Amazon",
                  "description": "Case-insensitive partial match on the payee display name.",
                  "disabled": true
                }
              ]
            }
          },
          "code": 200,
          "status": "Gift card payees retrieved successfully.",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"meta\": {\n    \"current_page\": 1,\n    \"next_page\": null,\n    \"prev_page\": null,\n    \"total_pages\": 0,\n    \"total_count\": 0\n  },\n  \"payees\": []\n}"
        },
        {
          "name": "401 Missing or invalid Bearer token.",
          "originalRequest": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/payees",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "payees"
              ],
              "query": [
                {
                  "key": "category",
                  "value": "Giftcard",
                  "description": "Exact match on the payee category. Use `Giftcard` to list the available gift cards.",
                  "disabled": true
                },
                {
                  "key": "page",
                  "value": "1",
                  "description": "Page number (starts at 1).",
                  "disabled": true
                },
                {
                  "key": "name",
                  "value": "Amazon",
                  "description": "Case-insensitive partial match on the payee display name.",
                  "disabled": true
                }
              ]
            }
          },
          "code": 401,
          "status": "Missing or invalid Bearer token.",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"error_type\": \"PAYEE_SERVICE_UNAVAILABLE\",\n  \"error_message\": \"Payee service is not available at this time, retry in 5 minutes\"\n}"
        }
      ]
    },
    {
      "name": "Purchase a gift card (generate an eGift)",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{finBaseUrl}}/api/v1/gift_cards",
          "host": [
            "{{finBaseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "gift_cards"
          ]
        },
        "description": "Generates an eGift for the chosen product and amount, and persists the resulting payment.\n\nThe `payee_id` is obtained from the Billpay\n[List Payees endpoint](/products/billpay/billpay-v1/other/listpayees) with category `Giftcard`.\n\n**Purchase flow** (short-circuits on the first failure):\n1. The input is validated against the request schema.\n2. The product is resolved from the payee; if it is not available the request fails with\n   `PAYEE_SERVICE_UNAVAILABLE`.\n3. The amount is validated against the product's allowed range.\n4. The `idempotency_key` is checked to reject repeated purchases.\n5. The payee/company must exist and be available.\n6. Balance is checked (only for Prepay clients).\n7. The eGift is generated and the account details are returned.\n8. The payment is finalized and, for Prepay clients, the client balance is deducted.\n\n**Implementation Notes:**\n- The `payee_id` is the id of the service (gift card product) being purchased.\n- `currency` must be MXN, and the amount must fall within the product's allowed range.\n- The `idempotency_key` is required to prevent duplicate purchases.",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"payee_id\": \"7ceee612-c1c1-4758-b5d5-095544113c18\",\n  \"country\": \"MEX\",\n  \"state\": \"Baja California\",\n  \"amount\": 40,\n  \"currency\": \"MXN\",\n  \"idempotency_key\": \"2026071502\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "auth": {
          "type": "bearer",
          "bearer": [
            {
              "key": "token",
              "value": "{{finAccessToken}}",
              "type": "string"
            }
          ]
        }
      },
      "response": [
        {
          "name": "201 Gift card purchased successfully",
          "originalRequest": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/gift_cards",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "gift_cards"
              ]
            }
          },
          "code": 201,
          "status": "Gift card purchased successfully",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"gift_card_id\": \"702d2533-19c9-4105-abe3-e7542ee47e4e\",\n  \"amount\": \"40.0\",\n  \"payee_id\": \"7ceee612-c1c1-4758-b5d5-095544113c18\",\n  \"status\": \"completed\",\n  \"created_at\": \"2026-07-15T21:33:56.653Z\",\n  \"redeem_link\": \"https://egift.monato.com/egift?eid=Z8X05NA1WR2JRBDG8F3NW9385H&tid=CD6RPC2K8JH2MMW5PHN6SY07GM\"\n}"
        },
        {
          "name": "401 Missing or invalid Bearer token.",
          "originalRequest": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/gift_cards",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "gift_cards"
              ]
            }
          },
          "code": 401,
          "status": "Missing or invalid Bearer token.",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"error_type\": \"PAYEE_SERVICE_UNAVAILABLE\",\n  \"error_message\": \"Payee service is not available at this time, retry in 5 minutes\"\n}"
        },
        {
          "name": "422 invalid_amount",
          "originalRequest": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/gift_cards",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "gift_cards"
              ]
            }
          },
          "code": 422,
          "status": "The purchase could not be completed. The `error_type` identifies the cause:",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"error_type\": \"AMOUNT_INVALID\",\n  \"error_message\": \"Amount is invalid\"\n}"
        },
        {
          "name": "422 duplicated",
          "originalRequest": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/gift_cards",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "gift_cards"
              ]
            }
          },
          "code": 422,
          "status": "The purchase could not be completed. The `error_type` identifies the cause:",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"error_type\": \"DUPLICATED_PAYMENT_ERROR\",\n  \"error_message\": \"This payment is already paid, retry in 24 hours\"\n}"
        },
        {
          "name": "422 insufficient_balance",
          "originalRequest": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/gift_cards",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "gift_cards"
              ]
            }
          },
          "code": 422,
          "status": "The purchase could not be completed. The `error_type` identifies the cause:",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"error_type\": \"AMOUNT_INSUFFICIENT\",\n  \"error_message\": \"The Payee minimum amount was not met\"\n}"
        },
        {
          "name": "422 invalid_payee",
          "originalRequest": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/gift_cards",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "gift_cards"
              ]
            }
          },
          "code": 422,
          "status": "The purchase could not be completed. The `error_type` identifies the cause:",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"error_type\": \"PAYEE_ID_INVALID\",\n  \"error_message\": \"Payee ID Invalid\"\n}"
        },
        {
          "name": "422 service_unavailable",
          "originalRequest": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{finBaseUrl}}/api/v1/gift_cards",
              "host": [
                "{{finBaseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "gift_cards"
              ]
            }
          },
          "code": 422,
          "status": "The purchase could not be completed. The `error_type` identifies the cause:",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "_postman_previewlanguage": "json",
          "body": "{\n  \"error_type\": \"PAYEE_SERVICE_UNAVAILABLE\",\n  \"error_message\": \"Payee service is not available at this time, retry in 5 minutes\"\n}"
        }
      ]
    }
  ]
}