Physical cards

Create and manage physical cardsPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. for your customers using our API. You can print physical cardsPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. or embed them in wearables and send them directly to your customers.

Set up your card program

You can customise physical cardsPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. to match your branding. Before you can issue physical cardsPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use., you need to set up your card program. This includes preparing your artwork, choosing the right card material, finishing, and selecting a card carrier. Read more on the different options offered by Weavr in the card stock setup guide. Additional fees apply.

Multiple card programs supported

In your app, you can set up multiple card programs with different artworks.

Create a physical card

To create a physical cardPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use., you need to:

1. Create a virtual card.
2. Request a physical cardPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. for that virtual cardVirtual CardA payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. with POST/managed_cards/{id}/physical.

After you set up your card program, you can request a physical cardPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. for any of your virtual cardsVirtual CardA payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode..

To request a physical cardPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use., specify the productReference and carrierType properties. These fields identify the card stock and card carrier to use.

Card sensitive information

The card PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. is considered PCI-sensitive data and needs to be tokenizedTokenizeReplace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. if you are not PCI compliant. Learn how to securely capture your user's preferred PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. using the capture card PIN UI component.

Choose a delivery mode

You can either:

1. Send each card directly to its cardholder with Individual delivery
2. Group several card orders into one parcel which you can then process and send on with bulk delivery.

Both modes use POST/managed_cards/{id}/physical. The bulkDelivery field selects how the card is dispatched.

Individual delivery

Set bulkDelivery to false, or omit it. Each request creates one card, seals it in its own envelope with a card carrier, and sends it to the supplied deliveryAddress.

The address name and surname are printed on the card carrier. If the card is linked to a user, the linked user's name takes precedence. Individual delivery supports STANDARD_DELIVERY, REGISTERED_MAIL, COURIER, and FIRST_CLASS_MAIL. If you omit deliveryMethod, Weavr uses STANDARD_DELIVERY. A contactNumber is required for courier delivery and ignored for the other methods.

POST/managed_cards/{id}/physicalOpen API reference →

/managed_cards/123456789/physical

{  "deliveryMethod": "FIRST_CLASS_MAIL",  "bulkDelivery": false,  "deliveryAddress": {    "name": "Jane",    "surname": "Doe",    "addressLine1": "221B Baker Street",    "city": "London",    "postCode": "NW1 6XE",    "country": "GB"  },  "pin": {    "value": "<tokenised-pin>"  }}

Bulk delivery

Set bulkDelivery to true. Each request still creates one card and seals it in its own envelope, but the fulfillment center groups qualifying orders into a parcel sent to a shared address. Bulk delivery is only available for cards linked to a user.

The address name and surname identify the parcel recipient, such as an office manager. They aren't printed on the individual card carriers, which use the linked users' names instead. The remaining address fields are printed on each carrier.

Bulk delivery supports REGISTERED_MAIL and COURIER. A contactNumber is required for courier delivery. Orders are grouped when they are placed on the same day and have identical recipient names, address fields, and contact numbers. Even formatting differences split orders into separate parcels.

A registered-mail parcel can contain up to 90 cards, while a courier parcel can contain up to 200. The fulfillment center splits larger groups across multiple parcels.

POST/managed_cards/{id}/physicalOpen API reference →

/managed_cards/123456789/physical

{  "deliveryMethod": "COURIER",  "bulkDelivery": true,  "deliveryAddress": {    "name": "Alex",    "surname": "Ops-Manager",    "addressLine1": "5 Canary Wharf",    "city": "London",    "postCode": "E14 5AB",    "country": "GB",    "contactNumber": "+447700900123"  },  "pin": {    "value": "<tokenised-pin>"  }}

The physical cardPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. details are returned in the response. The card is shipped in an inactive state and must be activated before it can be used.

Activate the physical card

Physical cardsPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. are shipped inactive. Until the card is activated, it can't be used for purchases and its API state is reported as BLOCKED. To activate it, call POST/managed_cards/{id}/physical/activate.

Only activate a card the customer holds

The API lets you activate a physical cardPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. at any time after it's created, including while it's still in transit. Don't do this. Only allow the card assigneeCard AssigneeThe person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users. to activate the card once it has been delivered and is in their possession. Requiring an explicit activation step prevents a card intercepted in transit from being used by a fraudster before it reaches your customer, so make sure your user experience clearly instructs customers to activate the card only after they have received it.

If you want stronger assurance that the customer holds the card, set an activationCode when you upgrade the card. The assignee must then enter the same code to activate it, and we can configure the code to be printed on the card carrier so it travels with the card. See choosing an activation approach for the trade-offs.

POST/managed_cards/{id}/physical/activateOpen API reference →

/managed_cards/123456789/physical/activate

{  "activationCode": {}}

After activation, the card transitions to the ACTIVE state. See activate a physical card for the full lifecycle.

Retrieve the physical card PIN

Physical cardsPhysical CardA payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. issued by Weavr are chip-and-PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. cards. When the card assigneeCard AssigneeThe person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users. makes a purchase at a physical point-of-sale, they must input the PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. associated with the card as an additional security layer.

You can allow your customers to specify a personalized PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. when creating a physical card.

Unspecified PINs are randomly generated

If a PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. is not specified when the card is created, Weavr assigns a randomly generated PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. to the card.

You can retrieve the card PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. with GET/managed_cards/{id}/physical/pin.

GET/managed_cards/{id}/physical/pinOpen API reference →

/managed_cards/123456789/physical/pin

The card PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. is returned in the response, tokenizedTokenizeReplace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants.. You can display the plain text card PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. to your customers using the show card PIN UI component.