Skip to main content

Card Management

This guide describes how to create a Paytient card for an employee and how to activate a physical card once it has been received.

Overview​

Paytient cards give employees access to their Paytient account for eligible healthcare purchases. When creating a card, you specify whether the employee receives a virtual card only, or both a virtual and physical card.

  • Virtual cards are available immediately after creation and can be used for online and in-app transactions.
  • Physical cards are mailed to the employee's address on file. Once received, the physical card must be activated before purchases can be made.

See the API Reference for full endpoint details and request/response schemas.

Prerequisites​

Before creating a card, the employee must meet all onboarding requirements. See the Onboarding Requirements guide for details.

Step 1: Create a Card​

Use the Create a Card endpoint (see API Reference) to issue a card for an employee. Pass the cardType query parameter to specify which card type(s) the employee should receive.

POST /api/employers/{employerId}/employees/{employeeId}/cards?cardType=virtual
cardTypeResult
virtualIssues a virtual card only — available for use immediately
allIssues both a virtual card and a physical card — physical card is mailed to the employee

A successful request returns 201 Created with a PaytientCard object.

After a card is successfully created, Paytient sends a card.created webhook event to your configured endpoint containing the employeeId and new cardId.

Error Handling​

If the employee has not met all prerequisites, the API returns 400 Bad Request with an error code identifying the missing requirement. Resolve the issue and retry the request.

Check prerequisites first

Use the Onboarding Requirements guide to verify all prerequisites are met before attempting card creation. This avoids unnecessary 400 errors.

Step 2: Activate a Physical Card​

If you created a card with cardType=all, the physical card is mailed to the employee's address on file. The physical card has a status of Inactive until activated.

Once the employee has received their physical card, use the Activate a Card endpoint (see API Reference) to activate it.

POST /api/employers/{employerId}/employees/{employeeId}/cards/{cardId}/activate-physical-card

Provide the cardId returned in the 201 Created response from Step 1. A successful request returns 200 OK and the physical card is immediately active.

note

Physical card activation only applies to cards created with cardType=all. Virtual-only cards are active immediately upon creation and do not require an activation step.