Moves the cardholder onto a new card from your inventory, named by its proxy in destination_proxy. Use it when a card is lost, damaged or otherwise needs replacing.
- The source card's available balance is unloaded to your funding account.
- The destination card is assigned to the person on the source card, with the same profile and external reference, and the
external_tagyou send or, if you omit it, the source's. - The balance is loaded onto the destination card, and the program's replacement fee, if it has one, is charged to it.
- The source account is closed.
Whether the destination card is activated, and when, depends on the program's settings.
A source that holds a balance is refused with 422 when that balance cannot be unloaded: when its account_status (from Get a cardholder by ID), or the cards[].status of its only card, reads suspended or fraud, or when an active card has expired. A source with a negative balance is refused with 422. A source whose account is closed is refused with 409.
After a replacement the person's card is the destination cardholder; use its id for later calls. To find it, call Search cardholders with prn set to the destination_proxy you sent. That filter is a prefix match, so take the result whose primary_processor_reference equals it exactly.
If a step up to and including the assignment fails, the request fails and the unloaded balance is reloaded onto the source card. That reload is best-effort, and its failure is not reported in the response. It always fails for a source marked lost or stolen, or whose every card is closed; its balance then stays in your funding account. After any error, check both cardholders and the source balance before retrying.
| Status | type | When |
|---|---|---|
| 404 | cardholder_not_found | No cardholder with this id, or no card with this proxy, in your company |
| 404 | card_order_item_not_found | The destination card is not in inventory, for example not yet received or damaged |
| 409 | cardholder_already_assigned | The destination card is already assigned, or is the source card |
| 409 | cardholder_already_closed | The source account is closed |
| 409 | bulk_update_count_mismatch | Another request changed the source or destination card at the same time; check both before retrying |
| 422 | cardholder_not_assigned | The source card is in inventory, or was already replaced |
| 422 | cardholder_no_cards | The source account has no card |
| 422 | cardholder_cards_closed | Every card on the destination cardholder is closed at the processor, for example invalidated by a failed card order |
| 422 | cardholder_suspended, cardholder_fraud_blocked, cardholder_expired | The source holds a balance that cannot be unloaded in this state, or (for cardholder_expired) the destination card has expired |
| 422 | card_expires_soon | The destination card expires within the program's minimum validity window |
| 422 | cardholder_replacement_currency_mismatch | The destination card's program uses a different currency |
| 422 | instant_issuance_replacement_fee_insufficient_funds | The source balance cannot cover the replacement fee |
| 422 | cardholder_replacement_source_overdrawn | The source card has a negative balance; settle it before replacing the card |
| 422 | cardholder_replacement_ship_to_name_required | The source card's shipping address has no recipient name, and the profile has none to fall back on |
| 422 | cardholder_not_assignable, cardholder_program_not_supported | The destination card cannot be assigned, for example it is not ready yet, or the processor refused the copied profile (errors may name the profile field). The destination program may also require an email or phone the source lacks, which returns a 422 without type naming body.email or body.phone |
| 422 | value_load_* | The processor refused the balance unload, for example a velocity or limit check |
| 502, 504 | value_load_processor_failure, value_load_processor_timeout, cardholder_processor_balance_failed, cardholder_processor_profile_failed | A processor call failed before the assignment; check the source balance before retrying |
| 500 | internal_server_error | Reading a card's status, or a processor call during the assignment, failed unexpectedly; check both cardholders and the source balance before retrying |
200 with warnings
Once the destination card is assigned, the replacement cannot be undone, so a later step that fails does not fail the request. The response is still 200, message is Card replaced with warnings, and warnings lists each failed step by type.
Do not retry the replacement: the source card is no longer assigned, so a retry returns 422 cardholder_not_assigned. Contact Berkeley Payments support with both cardholder ids and the warning types.
Warning type | What it means |
|---|---|
cardholder_replacement_balance_transfer_failed | The balance was unloaded from the source card but not loaded onto the new card. The funds are in your funding account, not lost. The fee warning below usually appears with it. |
instant_issuance_replacement_fee_charge_failed | The replacement fee may not have been charged. The new card is usable. |
cardholder_replacement_activation_failed | The new card is assigned but not activated, so it may not transact yet. |
cardholder_replacement_source_close_failed | The old account is still open at the processor, with a zero balance. It cannot be closed through this API. |
cardholder_replacement_contact_move_failed | Contact details held by Berkeley Payments, which are used for notifications, were not carried over to the new cardholder. |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||