Exchange Reward Points
This endpoint allows business customers to convert their accumulated reward points into cash. The specified number of points is redeemed and the equivalent dollar amount is credited directly to the designated financial account. Points must meet a minimum threshold of 100 before an exchange can be initiated.
Endpoint
POST /api/UsersReward/exchange
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 earned reward points for cash. The redeemed value is transferred as a credit to one of the customer's financial accounts. This is typically triggered from a rewards management interface where the customer selects a points amount and a destination account.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| toFinancialAccountId | string | Yes | The ID of the financial account to receive the converted cash amount |
| points | integer (int32) | Yes | Number of reward points to exchange. Minimum: 100, Maximum: 2147483647 |
{
"toFinancialAccountId": "fa_9b3e21c4d7f8a056e1234567",
"points": 500
}Response
200 OK
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier of the transfer transaction |
| createdAt | string (date-time) | Timestamp when the transfer was created |
| updatedAt | string (date-time) | Timestamp when the transfer was last updated |
| amount | object | The cash amount credited to the financial account |
| amount.value | integer (int64) | Monetary value in the smallest currency unit (e.g., cents) |
| amount.currencyCode | string | ISO 4217 currency code (e.g., "USD") |
| status | string | Current status of the transfer (e.g., "PENDING", "COMPLETED", "FAILED") |
| statusReason | string | Reason for the current status, especially useful when status is FAILED |
| memo | string | Descriptive memo attached to the transfer |
| errors | array | List of user-facing errors, if any occurred during processing |
| errors[].path | array of strings | Field path(s) related to the error |
| errors[].code | string | Machine-readable error code |
| errors[].description | string | Human-readable error description |
{
"id": "txn_7f4a1bc902e3d85f6c7890ab",
"createdAt": "2026-06-09T14:22:31Z",
"updatedAt": "2026-06-09T14:22:31Z",
"amount": {
"value": 500,
"currencyCode": "USD"
},
"status": "COMPLETED",
"statusReason": null,
"memo": "Reward points exchange",
"errors": []
}Error Codes
| Code | When it happens |
|---|---|
| 400 | Missing required fields, points below minimum (100), or invalid financial account ID format |
| 401 | Token missing, expired, or invalid |
| 403 | Insufficient permissions or customer does not have enough reward points for the requested exchange |
| 404 | The specified toFinancialAccountId does not exist or does not belong to the authenticated customer |
| 500 | Internal server error |
Common Mistakes
- Submitting a
pointsvalue below the minimum of 100 — the API requires at least 100 points per exchange request - Using a
toFinancialAccountIdthat belongs to a different customer or does not exist — the destination account must be owned by the authenticated business customer - Attempting to exchange more points than the customer currently holds — ensure the points balance is checked before calling this endpoint
- This endpoint is only available to business customers; personal customers do not have access to the rewards program
Related Endpoints
GET /api/UsersReward— Retrieve the current reward points balance for the authenticated customerPOST /api/UsersReward/send— Send reward points to another Netevia business customerGET /api/FinancialAccounts— List all financial accounts available to the customer for use as a transfer destination
Example
curl -X POST https://api.banking.netevia.dev/api/UsersReward/exchange \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"toFinancialAccountId": "fa_9b3e21c4d7f8a056e1234567",
"points": 500
}'