Issue Gift Card

The /api/giftCards/card endpoint allows customers to purchase digital gift cards from brands available in the Netevia system. Upon a successful purchase, the gift card is immediately accessible via the GET /api/giftCards/orders endpoint and the corresponding amount is deducted from the customer's designated financial account. An optional rewards points redemption is supported to offset the purchase cost.

Endpoint

POST /api/giftCards/card

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when a customer selects a brand and denomination from the gift card catalog and initiates a purchase. This is the primary action endpoint for the gift card flow — call it after retrieving available brands and confirming the customer has sufficient funds. The purchased gift card order is immediately trackable and the deducted amount is reflected on the funding account in real time.

Request Body

{
  "brandId": "brand_abc123",
  "faceAmount": 5000,
  "oneTimeCode": "482917",
  "secureOperationType": "ShortMessageCode",
  "fromFinancialAccountId": "fa_9d8e7f6a5b4c",
  "rewardsPoints": 200
}

Response

200 OK

{
  "id": "gco_7f3a2b1c9d8e",
  "brandId": "brand_abc123",
  "brandName": "Amazon",
  "logoUrl": "https://cdn.example.com/brands/amazon-logo.png",
  "url": "https://redeem.example.com/gift/7f3a2b1c9d8e",
  "currency": "USD",
  "faceAmount": 5000,
  "amount": 4750,
  "discount": 0.05,
  "expirationDate": "2027-06-30T23:59:59Z",
  "createdDate": "2026-06-08T14:32:00Z",
  "cancelDate": null,
  "issueTransactionId": "txn_1a2b3c4d5e6f",
  "cancelTransactionId": null,
  "status": "Issued",
  "userName": "Jane Smith",
  "userId": 10042
}

Error Codes

Common Mistakes

• Omitting oneTimeCode or secureOperationType — both are required fields; the request will be rejected with a 400 error if either is missing
• Supplying a oneTimeCode that does not match the exact 6-digit pattern (^\d{6}$) — codes with letters, spaces, or fewer/more digits will fail validation
• Using an expired or already-consumed one-time code — generate a fresh code immediately before submitting the purchase request
• Specifying a fromFinancialAccountId that belongs to a different customer — ensure the account ID matches the authenticated user's account
• Passing faceAmount in dollars instead of cents — the field expects the smallest currency unit (e.g., 5000 for $50.00)

Related Endpoints

• GET /api/giftCards/orders — Retrieve the list of gift card orders placed by the customer
• GET /api/giftCards/brands — List available gift card brands and their supported denominations
• DELETE /api/giftCards/card/{orderId} — Cancel a previously issued gift card order

Example

curl -X POST https://api.banking.netevia.dev/api/giftCards/card \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "brand_abc123",
    "faceAmount": 5000,
    "oneTimeCode": "482917",
    "secureOperationType": "ShortMessageCode",
    "fromFinancialAccountId": "fa_9d8e7f6a5b4c",
    "rewardsPoints": 200
  }'