Overview
After a cardholder is created you can upload a passport photo and a selfie-with-passport via a dedicated endpoint. These photos live in PayCA and are used by admins during cardholder approval. They are not forwarded to the card provider.
Uploading photos is optional — a cardholder can be approved without them. Photos still tend to speed up admin review.
Photo requirements
| Parameter | Value |
|---|---|
| Format | JPEG or PNG |
| Max size | 5 MB per file |
| Request type | multipart/form-data |
Endpoint
POST /v1/cardholders/{id}/photos
Content-Type: multipart/form-data
Upload one or both photos as files in a multipart request. At least one photo must be attached.
Form fields
| Field | Type | Required | Description |
|---|---|---|---|
passportPhoto |
file (binary) | No* | Passport photo (JPEG or PNG, max 5 MB). |
selfiePhoto |
file (binary) | No* | Selfie holding the passport (JPEG or PNG, max 5 MB). |
* At least one of the two fields must be present.
Request example
# Upload both photos
curl -s -X POST "$PAYCA_BASE_URL/v1/cardholders/{cardholderId}/photos" \
-H "x-client-id: $PAYCA_CLIENT_ID" \
-H "x-client-secret: $PAYCA_CLIENT_SECRET" \
-F "passportPhoto=@passport.jpg" \
-F "selfiePhoto=@selfie.jpg"
# Upload only the passport photo
curl -s -X POST "$PAYCA_BASE_URL/v1/cardholders/{cardholderId}/photos" \
-H "x-client-id: $PAYCA_CLIENT_ID" \
-H "x-client-secret: $PAYCA_CLIENT_SECRET" \
-F "passportPhoto=@passport.jpg"
Response example
{
"ok": true
}
Workflow
- Create the cardholder:
POST /v1/users/{userId}/cardholder - Upload photos:
POST /v1/cardholders/{cardholderId}/photos - Wait for approval (poll
GET /v1/cardholders/{id}or subscribe to the webhook) - Issue a card:
POST /v1/cards
Photos can be uploaded at any point after cardholder creation, including after approval.
Validation errors
| Error | Cause |
|---|---|
passportPhoto exceeds 5MB limit |
File is larger than 5 MB. |
passportPhoto must be JPEG or PNG |
File is not JPEG or PNG. |
selfiePhoto exceeds 5MB limit |
File is larger than 5 MB. |
selfiePhoto must be JPEG or PNG |
File is not JPEG or PNG. |
at least one photo ... must be provided |
Neither photo was attached to the request. |
cardholder not found |
Cardholder does not exist or belongs to another client. |
Viewing photos
Uploaded photos are visible to PayCA admins in the Admin UI. When inspecting a cardholder under Cardholders, the admin can expand the cardholder row to see the passport photo and the selfie.
The client-facing API does not expose a way to retrieve uploaded photos — they are intended for internal verification only.
Notes
- Both fields are fully optional. Send either
passportPhoto,selfiePhoto, or both. - Re-uploading replaces the previous file. If a follow-up request includes only one photo, the other one stays unchanged.
- For B2C cardholders, if photos were not uploaded through this endpoint, the system will automatically use the documents already collected through the KYC flow (when available) for display in the Admin UI.