After you create and issue cards to your users, you will need to manage the whole lifecycle of your cards, including:
- Replacing a damaged or expired card.
- Replacing lost or stolen card.
- Cancelling a card.
Update a card
Many fields on a card cannot be updated, since some configurations exist on the card chip itself.
To update a card, make a PATCH /paymentInstruments request.
Here is an example for updating the description on paymentInstruments.id PI6789678967896789.
{
"description":"{hint:Human-readable field for your support agents and other staff}Secondary card - used to be primary card{/hint}"
}The response contains the updated paymentInstrument resource.
{
"id": "PI6789678967896789",
"type":"card",
"description":"{hint:Human-readable field for your support agents and other staff}Secondary card - used to be primary card{/hint}"
...
}Deactivate a card
You can deactive a payment instrument to temporarily prevent payment processing. You can activate the card again at any time. If you want to permanently close a card, you can cancel the card.
To deactivate a card, update the payment instrument providing:
status: Set this to Inactive.
The card can no longer be used for payments. You can update the status back to active if you want to reenable payments.
Replace a card
Replacing a card requires creating a new payment instrument and specifying replacement information. The replacement.reason specifies how the card replacement is processed. Possible card replacement reasons are:
- damaged: The physical card is damaged. Card number is copied from original payment instrument to the new payment instrument. New CVV and expiration date will be used. The original card is left active.
- expiration: The card is nearing expiration or is expired. Card number is copied from original payment instrument to the new payment instrument. New CVV and expiration date will be used. The original card is left active.
- lost: Card is reported as lost. New card number, CVV, and expiration date is used. The original card is cancelled.
- stolen: Card has been stolen. New card number, CVV, and expiration date is used. The original card is cancelled.
You can additional provide areplacement.description, a free-form field to provide additional context for future reference.
Replacing a damaged card or expired card results in creating a new card that has the same card number as their existing card. A new cvv and expiration will be used for the new card. The original card is still left as active.
To replace a card while keeping the same card number, create a new payment instrument providing:
type: specifying card.replacement.originalPaymentInstrument: The id of the original paymentInstrument to replace.replacement.description: Specify damaged or expiration.
For example, to replace paymentInstrument.Id PI6789678967896789, make a POST /paymentInstruments request:
{
"type": "card",
"replacement":{
"originalPaymentInstrument":"PI6789678967896789",
"reason":"damaged",
"description": "Card worn from normal wear and tear"
},
"description":"{hint:Human-readable field for your support agents and other staff}S.Hopper- Primary card{/hint}",
"reference":"{hint:This is your unique identifier for this resource}myPaymentInstrument_12346{/hint}"
}When replacing an original payment instrument, all information and settings will be copied over to the replacement card unless new information is provided.
The response contains the new paymentInstrument and card number.
{
"id": "PI3456345634563456",
"type":"card",
"card": {...},
"status": "inactive",
"replacement":{
"originalPaymentInstrument":"PI6789678967896789",
"reason":"damaged",
"description": "Card worn from normal wear and tear"
}
}The original card is still active and can be used. Once your user has confirmed receipt of the new card, cancel the original payment instrument.
When replacing a lost or stolen card, the replacement card will have a new card number, CVV, and expiration date. The original card is automatically canceled.
To replace a lost or stolen card, create a new payment instrument providing:
type: Specify card.replacement.originalPaymentInstrument: The ID of the original paymentInstrument that you are replacing.replacement.reason: Specify as lost or stolen. If you are unsure if a card is lost or stolen, specify lost.
For example, to replace paymentInstrument.id PI6789678967896789, make a POST /paymentInstruments request:
{
"type": "card",
"replacement":{
"originalPaymentInstrument":"PI6789678967896789",
"reason":"lost",
"description":"Misplaced card, requesting replacement."
},
"description":"{hint:Human-readable field for your support agents and other staff}S.Hopper- Primary card{/hint}",
"reference":"{hint:This is your unique identifier for this resource}myPaymentInstrument_12346{/hint}"
}When replacing an original payment instrument, all information and settings will be copied over to the replacement card unless new information is provided.
The response contains the new paymentInstrument and card number.
{
"id": "PI3456345634563456",
"type":"card",
"card": {...},
"reference": "myPaymentInstrument_12346",
"status": "inactive",
"description":"{hint:Human-readable field for your support agents and other staff}S.Hopper- Primary card{/hint}",
"replacement":{
"originalPaymentInstrument":"PI6789678967896789",
"reason":"lost",
"description":"Misplaced card, requesting replacement."
}
}Replacing a lost card automatically cancels the original payment instrument.
Cancel a card
Cancel a card to permanently close it. If you want to temporarily prevent processing, you can deactivate the card. Canceling a card is a permanent action and cannot be reversed.
To cancel a card, make a POST /paymentInstruments/{id}/cancel request.
For example, the request below cancels paymentInstrument.id PI6789678967896789.
POST /paymentInstruments/PI6789678967896789/cancel