Replace Card

Replace Customer Card

The Replace Card endpoint issues a replacement for an existing card, for example when the card is damaged, lost, stolen, expired, returned, or compromised. The replacement is issued as a new card with its own new cardsId; the previous card's ID is not reused. It is created against the same funding account as the original, so the balance is retained, and the response returns previousCardsId (the ID of the card it replaced) for reconciliation. When the replacement reason is Lost or Stolen, the original card is closed. A replacement fee may apply and is reserved from the customer's card funding account once the replacement has succeeded. Use the Review Replace Card endpoint first to preview the fee and the paying account. Optionally, supply a shippingAddress to have the replacement card delivered to a different address than the original. When it is omitted, the original card's shipping address is used.

• Endpoint: /api/v1/customer/cards/replace

• Method: POST

• Request Format: application/json

• Header Parameter

  • otp : required

Request Body

{
  "cardsId": 1359,               // required, number, ID of the card to replace
  "replaceReason": "Damaged",    // required, string, one of: "Damaged", "Lost", "FraudCompromised", "Returned", "Expired", "Stolen"
  "shippingMethod": "Standard",  // optional, string, one of: "Standard" (default), "Express"
  "shippingAddress": {           // optional. Supply to ship the replacement card to a new address
    "shippingAddressLine1": "1 Roshar Ave",  // required when shippingAddress is supplied, string, max 60 characters
    "shippingAddressLine2": null,            // optional, string, max 60 characters
    "shippingAddressCity": "New York",       // required when shippingAddress is supplied, string, max 60 characters
    "shippingAddressState": "NY",            // required when shippingAddress is supplied, string, letters only, max 30 characters
    "shippingAddressPostcode": "10001",      // required when shippingAddress is supplied, string, digits only, max 10 characters
    "shippingAddressCountry": "US"           // required when shippingAddress is supplied, string, letters only
  }
}

Response Body

{
  "id": 1402,
  "details": {
    "cardsId": 1402,
    "cardsCode": "TUC-1402",
    "nameOnCard": "John Smith",
    "cardLastFour": "4821",
    "expiryDate": "09/29",
    "status": "Active",
    "shippingMethod": "Standard",
    "previousCardsId": 1359
  },
  "status": "1",
  "errors": []
}

Error Responses

Errors are returned using the standard envelope, with status set to "0" and one or more entries in the errors array, each containing a fieldName and a messageCode.

messageCode	Meaning
Required	A required field (cardsId or replaceReason) was not provided.
Invalid	replaceReason or shippingMethod is not one of the accepted values.
Card_Provider_Not_Supported	Card replacement is not supported for this card.
Card_Already_Replaced	The card has already been replaced.
Card_Account_Not_Found	The funding account for the card could not be found.
Card_Replacement_Fee_Not_Configured	No card replacement fee is configured for the customer.
Insufficient_Funds	The funding account does not have enough available balance to cover the replacement fee.
Card_Provider_Error	The card could not be replaced due to an error while processing the replacement (HTTP 500).

{
  "id": 0,
  "details": null,
  "status": "0",
  "errors": [
    {
      "fieldName": "CardsId",
      "messageCode": "Insufficient_Funds"
    }
  ]
}