Physical Cards Guide#
This guide covers the complete flow for physical (plastic) card assignment and activation with PIN.Prerequisites#
✅ Complete Getting Started guide
✅ Received USER_CREATE_RESULT webhook with status APPROVED
✅ Have user_id and template_id from previous steps
✅ Have a physical card number ready for assignmentStep 3b: Assign a Physical Card#
After receiving the USER_CREATE_RESULT webhook with status APPROVED, you can assign a physical card to the user using the user ID from Step 2 and template ID from Step 1.Endpoint#
Request Fields#
user_id - User ID (from Getting Started guide)
template_id - Card template ID (from Getting Started guide)
card_number - Physical card number (16-19 digits)
Request Example#
{
"user_id": 12345,
"template_id": 1,
"card_number": "1234567890123456"
}
Response#
The response contains the card ID (card_id) which represents the card assignment operation.Card Assignment Process#
Important: The physical card assignment process is asynchronous and requires webhook confirmation.After successful API call:1.
The card is NOT immediately created in the system
2.
An operation record is created with status PENDING
3.
You must wait for webhook confirmation before proceeding
Webhook Event: CARD_ASSIGN_RESULT#
You will receive a webhook notification with the assignment result:{
"card_id": 12345,
"status": "SUCCESS",
"occur_time": 1691249025085
}
{
"status": "FAILED",
"error_reason": "101:0 - card number not exist",
"user_id": 67890,
"occur_time": 1691249025085
}
card_id - Internal card unique ID (only for successful assignments)
status - Assignment status (SUCCESS or FAILED)
error_reason - Error description (only for failed assignments)
user_id - User identifier (only for failed assignments)
occur_time - Trigger time (milliseconds)
Card Status After Assignment#
After receiving CARD_ASSIGN_RESULT webhook:For Successful Assignment (status: "SUCCESS")#
Card is created in the system with status TBA (To Be Activated)
Card ID becomes available for subsequent operations
Proceed to Step 4b (Activate with PIN)
For Failed Assignment (status: "FAILED")#
Card is NOT created in the system
Check the error reason and correct the issue
Retry the assignment with a valid card number
Important Notes#
The card number must be a valid 16-19 digit number
Always wait for CARD_ASSIGN_RESULT webhook before proceeding
The assignment process is asynchronous and requires webhook confirmation
Physical cards require PIN activation after successful assignment
Failed assignments will provide detailed error information
Step 4b: Activate Physical Card with PIN#
Prerequisites: This step is only available after receiving CARD_ASSIGN_RESULT webhook with status SUCCESS.After successful card assignment confirmation, you must activate the physical card with a 6-digit PIN code before it can be used.Endpoint#
Request Fields#
card_id - Card ID (from assign response)
alter - Set to "ACTIVATE"
pin - PIN code (exactly 6 digits, required for physical card activation)
Request Example#
{
"user_id": 12345,
"card_id": 67890,
"alter": "ACTIVATE",
"pin": "123456"
}
Response#
{
"message": "Operation requested"
}
PIN Requirements#
PIN must be exactly 6 digits long
PIN must contain only numeric characters
No repeated sequences or simple patterns recommended
Card Activation Confirmation#
After the activation with PIN is processed by the banking provider, you will receive a webhook notification - the same as for virtual cards.Webhook Event: CARD_ACTIVATE_RESULT#
{
"card_id": 12345,
"card_number": "1234567890123456",
"status": "SUCCESS",
"occur_time": 1691249025085
}
card_number - Card number
status - Activation status (SUCCESS or FAILED)
occur_time - Trigger time (milliseconds)
Card Status After Activation#
Event Type: CARD_ACTIVATE_RESULT (identical to virtual card activation)
The card status will change to "ACTIVE"
Card becomes ready for transactions and recharge
Important Notes#
PIN setting and activation happen in a single request for physical cards
After PIN is set and card is activated, the card becomes ready for recharge and use
PIN can be changed later using the set_pin endpoint if needed
Always wait for CARD_ACTIVATE_RESULT webhook before proceeding to recharge
Next Steps#
Card is Ready! 🎉#
Your physical card is now active and ready to use. Continue to:ATM Usage - Use the card at any compatible ATM with your PIN
In-Store Payments - Use the card for point-of-sale transactions
Monitor Transactions - Track card usage via webhooks
Common Operations#
1.
Recharge Card - Add funds to the card balance
2.
Get Balance - Check current card balance
3.
Get Card Info - Retrieve card details and status
4.
Get Transactions - View transaction history
5.
Change PIN - Update card PIN if needed
Error Handling#
Common Assignment Errors#
Invalid Card Number Format: Ensure 16-19 digit number
Card Number Not Found: Verify the card exists in the provider system
Card Already Assigned: Card is already assigned to another user
Provider System Errors: Temporary issues with banking provider
Common Activation Errors#
Invalid PIN Format: Must be exactly 6 digits
Card Not in TBA Status: Ensure card was successfully assigned first
Provider Errors: Banking provider rejected the activation
Troubleshooting#
1.
Always wait for CARD_ASSIGN_RESULT webhook before attempting activation
2.
Verify card status is TBA before activation
3.
Ensure PIN meets format requirements (exactly 6 digits)
4.
Check provider connectivity if activation fails
5.
Contact support with card_id for specific issues
Security Considerations#
PIN Protection: Never store or log PIN values in plaintext
Secure Transmission: All requests use encrypted communication
Card Number Validation: Verify card numbers are legitimate before assignment
User Authentication: Ensure proper user verification before card assignment
Modified at 2025-08-04 15:19:55
