Assign Card

Flow Summary

The current physical-card flow is:

Step 1. Finish the physical card request
Start from Card Request with card_type=PHYSICAL

Step 2. Assign the real card number
POST /api/v1/cards/assign

Step 3. Activate the card
Continue in Card Activation

1. Assign Physical Card

POST /api/v1/cards/assign

Assigns a physical card number to the current user after a physical card request reaches the assignment stage.

Request

{
  "card_number": "4111111111111111"
}

Request rules

• card_number is required
• It must be exactly 16 digits
• It must be numeric only

Important backend behavior

• This route is protected and passes through DecryptField()
• The user must already have a successful card_holder record
• The service checks the latest physical card request still in processing
• On success, the backend either:
  • updates the existing physical request, or
  • creates a new internal physical request record already marked as approved and paid
• In both paths, the stored activation_code is initially set to -
• Upstream errors such as card number not exist or card has been assigned are mapped back into client-facing validation failures

2. Reset Card PIN

POST /api/v1/cards/reset-pin

Resets the PIN for an already issued physical card.

Request

{
  "card_id": 508,
  "new_pin": "123456",
  "new_pin_confirm": "123456"
}

Request rules

• card_id is required
• new_pin is required and must be exactly 6 digits
• new_pin_confirm is required and must exactly match new_pin

Important backend behavior

• This route is protected and passes through DecryptField()
• card_id is the local numeric card record ID
• The card must belong to the current user
• Only PHYSICAL cards are allowed
• The reset is processed synchronously through UQPay
• After success, the service also attempts to send a confirmation email; email-send failure is non-fatal and does not roll back the PIN reset