Set PIN for Payment Card

Set PIN for Payment Card

The Set PIN endpoint allows users to securely set a new PIN or update the existing PIN for a payment card. The request requires both the new PIN and a confirmation value to prevent errors during the update. All PIN changes are subject to security validation to ensure compliance with PIN complexity and length requirements.

Endpoint

POST /api/paymentCards/setPinForPaymentCard

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 needs to set a PIN on a newly issued card before first use, or when they want to change an existing PIN for security purposes. This applies to physical, virtual, and burner payment cards that support PIN-based transactions. Integrating this endpoint into your card management flow ensures cardholders can independently manage their card security at any time.

Request Body

{
  "paymentCardId": "card_a1b2c3d4e5f6",
  "newPin": "7492",
  "pinConfirm": "7492"
}

Response

200 OK

A 200 response indicates the PIN was successfully set or updated. The response body on success is empty.

{}

Error Codes

Common Mistakes

• Sending a newPin and pinConfirm that do not match — both fields must be identical or the request will be rejected with a 400 error.
• Providing a PIN longer than 4 characters — the newPin and pinConfirm fields each enforce a maximum length of 4 characters.
• Using an expired or missing Bearer token — ensure the token is refreshed before making requests, as the token lifetime is only 10 minutes.
• Passing an incorrect or non-existent paymentCardId — verify the card ID belongs to the authenticated user's account before submitting.

Related Endpoints

• POST /api/paymentCards/createPaymentCard — create a new physical, virtual, or burner payment card
• GET /api/paymentCards/getPaymentCards — retrieve a list of payment cards associated with a customer
• POST /api/paymentCards/lockPaymentCard — lock a payment card to temporarily prevent transactions
• POST /api/paymentCards/unlockPaymentCard — unlock a previously locked payment card

Example

curl -X POST https://api.banking.netevia.dev/api/paymentCards/setPinForPaymentCard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentCardId": "card_a1b2c3d4e5f6",
    "newPin": "7492",
    "pinConfirm": "7492"
  }'