Exchange Points for Gift Card
This endpoint allows business customers to redeem their accumulated reward points by purchasing gift cards from supported brands. The transaction requires multi-factor authentication via a one-time code to ensure security. Upon success, the response includes the full gift card order details including the redemption URL and order status.
Endpoint
POST /api/UsersReward/exchange/giftcard
Authentication
Bearer token required. Obtain via:
POST https://api.banking.netevia.dev/api/auth/v2Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.
When to use
Use this endpoint when a business customer wants to redeem their reward points balance in exchange for a digital gift card. This is typically triggered from a rewards redemption UI where the customer selects a gift card brand and denomination. The endpoint supports two request variants: a base issue request (points-only redemption) and a buy request that additionally specifies a financial account and explicit points amount.
Request Body
This endpoint accepts one of two request shapes:
Option 1 — Issue Gift Card Request (issuegiftcardrequest)
| Field | Type | Required | Description |
|---|---|---|---|
| brandId | string | No | The ID of the gift card brand to purchase |
| faceAmount | integer (int64) | No | The denomination (face value) of the gift card |
| oneTimeCode | string | Yes | A 6-digit one-time code for MFA verification (pattern: ^\d{6}$) |
| secureOperationType | string (enum) | Yes | The MFA mechanism used: ShortMessageCode, TimeBasedCode, or LegacyTimeBasedCode |
Option 2 — Buy Gift Card Request (buygiftcardrequest, extends Option 1)
Includes all fields from Option 1, plus:
| Field | Type | Required | Description |
|---|---|---|---|
| fromFinancialAccountId | string | No | The financial account ID from which to debit if supplementing points |
| rewardsPoints | integer (int32) | No | The explicit number of reward points to apply toward the purchase |
{
"brandId": "brand_abc123",
"faceAmount": 25,
"oneTimeCode": "847392",
"secureOperationType": "ShortMessageCode",
"fromFinancialAccountId": "fa_98765xyz",
"rewardsPoints": 2500
}Response
200 OK
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier for the gift card order |
| brandId | string | The brand ID of the purchased gift card |
| brandName | string | Human-readable name of the gift card brand |
| logoUrl | string | URL to the brand's logo image |
| url | string | Redemption URL for the issued gift card |
| currency | string | Currency of the gift card (e.g., USD) |
| faceAmount | integer (int64) | The face value/denomination of the gift card |
| amount | integer (int64) | The actual points or monetary amount charged |
| discount | number (double) | Any discount applied to the transaction |
| expirationDate | string (date-time) | Expiration date of the gift card, if applicable |
| createdDate | string (date-time) | Timestamp when the order was created |
| cancelDate | string (date-time) | Timestamp when the order was canceled, if applicable |
| issueTransactionId | string | Transaction ID associated with the issuance |
| cancelTransactionId | string | Transaction ID associated with cancellation, if applicable |
| status | string (enum) | Order status: Issued or Canceled |
| userName | string | Username of the customer who placed the order |
| userId | integer (int32) | Internal user ID of the customer |
{
"id": "gco_7f3a91bc2e",
"brandId": "brand_abc123",
"brandName": "Amazon",
"logoUrl": "https://cdn.example.com/brands/amazon_logo.png",
"url": "https://giftcards.example.com/redeem/abc123xyz",
"currency": "USD",
"faceAmount": 25,
"amount": 2500,
"discount": 0.0,
"expirationDate": "2027-06-30T00:00:00Z",
"createdDate": "2026-06-09T14:22:00Z",
"cancelDate": null,
"issueTransactionId": "txn_issue_44d9a1",
"cancelTransactionId": null,
"status": "Issued",
"userName": "[email protected]",
"userId": 10482
}Error Codes
| Code | When it happens |
|---|---|
| 400 | Missing required fields (oneTimeCode or secureOperationType), invalid one-time code format (must be exactly 6 digits), or insufficient reward points balance |
| 401 | Token missing, expired, or invalid |
| 403 | Insufficient permissions or customer is not eligible for rewards redemption |
| 404 | Specified brandId not found or fromFinancialAccountId does not exist |
| 500 | Internal server error |
Common Mistakes
- Sending a
oneTimeCodethat is not exactly 6 digits — the field enforces the pattern^\d{6}$and will fail validation if the code has any non-numeric characters or wrong length. - Omitting
secureOperationType— this field is required even when the code is provided; the server needs to know which MFA method was used to validate it. - Using a financial account ID that belongs to a different customer —
fromFinancialAccountIdmust be owned by the authenticated user. - Attempting to redeem more points than the customer's current rewards balance without providing a
fromFinancialAccountIdto cover the shortfall. - Reusing an expired or already-consumed one-time code — each code is valid for a single use only.
Related Endpoints
GET /api/UsersReward/balance— Retrieve the current reward points balance for the authenticated customerGET /api/UsersReward/giftcard/brands— List available gift card brands and their supported denominationsGET /api/UsersReward/exchange/history— View past reward redemption and exchange transactionsPOST /api/UsersReward/exchange— Redeem reward points directly to a financial account
Example
curl -X POST https://api.banking.netevia.dev/api/UsersReward/exchange/giftcard \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"brandId": "brand_abc123",
"faceAmount": 25,
"oneTimeCode": "847392",
"secureOperationType": "ShortMessageCode",
"fromFinancialAccountId": "fa_98765xyz",
"rewardsPoints": 2500
}'