Set Payment Card Nickname

The Set Payment Card Nickname endpoint allows users to assign or update a custom display name for any of their payment cards. This enables better organization and identification when a cardholder holds multiple cards across different accounts or purposes. Upon successful update, the endpoint returns the full updated card record reflecting the new nickname.

Endpoint

POST /api/paymentCards/nickName

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 cardholder wants to label a card with a personalized name such as "Travel Card", "Business Expenses", or "Online Shopping". This is especially useful for users who hold multiple Physical, Virtual, or Burner cards and need to distinguish between them in a mobile or web interface. Nicknames appear in the card record and can be updated at any time.

Request Body

{
  "paymentCardId": "card_8f3a21bc4d7e9012",
  "nickName": "Travel Expenses"
}

Response

200 OK

{
  "paymentCardId": "card_8f3a21bc4d7e9012",
  "userProfileId": 10042,
  "paymentCardName": "Travel Expenses",
  "maxTotalSpending": null,
  "maxTransactionsCount": null,
  "totalSpending": 245000,
  "totalTransactionsCount": 17,
  "type": 2,
  "expirationDate": "2027-06-30T23:59:59Z",
  "active": true,
  "last4": "4321",
  "bin": "411111",
  "network": "Visa",
  "formFactor": "VIRTUAL",
  "status": 1,
  "partnerId": 5,
  "authorizationControls": [],
  "cardProfileSetId": "cps_b2d4f6a8c0e2",
  "financialAccountId": "fa_1a2b3c4d5e6f",
  "cardProfileSet": null,
  "syncSubDate": "2026-06-01T12:00:00Z",
  "reissuedCardId": null
}

Error Codes

Common Mistakes

• Submitting a nickName longer than 18 characters — the API will reject the request with a 400 error; truncate the value on the client side before sending.
• Omitting paymentCardId from the request body — this field is required and has a minimum length of 1; requests without it will fail validation.
• Assuming the response only returns the nickname field — the full card object is returned; parse paymentCardName to confirm the updated value.
• Attempting to set a nickname on a closed or reissued card — check the status field (value 3 = Closed) before calling this endpoint to avoid unnecessary requests.

Related Endpoints

• POST /api/paymentCards — Issue a new payment card (Physical, Virtual, or Burner)
• GET /api/paymentCards — Retrieve all payment cards for the authenticated user
• POST /api/paymentCards/status — Activate, suspend, or close a payment card
• POST /api/paymentCards/authorizationControls — Set spending limits and merchant restrictions on a card

Example

curl -X POST https://api.banking.netevia.dev/api/paymentCards/nickName \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentCardId": "card_8f3a21bc4d7e9012",
    "nickName": "Travel Expenses"
  }'