API DOCUMENTATION Last Update: Apr 2022

Customer Card Replace

Updates a customer's card_number and/or unique code with new ones, based on partial customer data matching.


The data to be submitted to the API is composed of the following fields:


  field   Example   Note
user_id john1970 Required
user_password 1959caadac9b13dcb3 Required
type card_replace Required
account_id greatwidgets Required
previous_code 0123456789012345 See notes
previous_card 121212 See notes
new_code 1234567890123456 See notes
new_card_number 131313 See notes
card_number_generate (# of digits) See notes
profile_uid 395 See notes
check_override Y See notes
keep_which matched or duplicate See notes
first_name Jane Optional
last_name Doe Optional
phone 555-5555 Optional
email jdoe@email.com Optional
street1 123 Main St.
street2 Suite 3G
city Anytown Optional
state ONT Optional
postal_code 55555 Optional
country Canada
custom_date 1970-07-14 Optional
custom_field baltimore Optional
customer_password pa$$w0rd Optional
customer_PIN 1234 Optional
customer_username janedoe123 Optional
Output Format:
output JSON or XML Optional. If not provided, defaults to XML
callback someFunctionName Optional: JSONP format
condensed yes Optional (No white space)
Applies only to JSON(P) output



  • For this call to work, you must provide a "new_code", a "new_card_number" or the field "card_number_generate". It can also be a combination of new_code and either new_card_number or card_number generate.
  • The card_number_generate field is should be included only if you want the program to generate a random unique card number. It takes as an argument the number of digits to be generated.
  • If both "previous_code" and "previous_card" are given, "previous_code" is given priority and used to identify the old card.
  • If neither "previous_code" and "previous_card" are given, the "new_code" and/or "new_card_number" will be applied only if there is a single resulting customer that matches ALL of whichever information fields were given (phone, email, etc.).
  • If multiple matches result, then a list of those matching customers will be returned, with each customer's information, including a "profile_uid" field to be used when one of the customers is selected as the one to update:
  • With a "profile_uid" field provided, only the new_code and/or new_card_number fields need to be given back through the API call: All other optional fields, if given, will be ignored.
  • The program will check before replacing any card if the given new_code or new_card_number already exist in the system -- if they do, an error code will be generated. In case this is not what you want,set the check_override parameter to "Y"and it will not perform this check.
  • Setting the check_override really only makes sense if you expect duplicate records to result from the card_replace API call. However, although card_numbers can be duplicates for esoteric reasons, card codes must be unique. If there is an existing (duplicate) card code that matches the new_code provided, for example, if joining two customer accounts together or if replacing a lost card with a "new" card when all cards are already pre-loaded into the system, you need to set the check_override parameter to "Y" AND select which of the two record to keep with the keep_which parameter:
    • Selecting "matched" will keep the customer information in the "matched" (or "old" or "lost") card, replace its code and/or card number with the new one(s), delete the "duplicate" existing account that matches the new_code provided, and move any existing transactions associated with the now deleted "duplicate" account to the newly updated "matched" one.
    • Selecting "duplicate" will keep the customer information in the existing account whose code matches the given new_code, replace the existing card_number of that account if a new_card_number is given (or card_number_generate), delete the "old" (or "lost") account, and move any transaction associated with the "old" (or "lost") account to the new one.
  • The custom_date field must be given in YYYY-MM-DD format
  • Text-based matches on the optional fields are not case-sensitive.


Example PHP Requests:

To replace the card number and/or code of a known card, by previous_code or by previous_card:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'card_replace';
  4. $data['account_id'] = 'greatwidgets';
  5. $data['previous_code'] = '012345678912345';
  6. $data['new_card_number'] = '1231313';


To replace the card number and/or code knowing only certain data:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'card_replace';
  4. $data['account_id'] = 'greatwidgets';
  5. $data['last_name'] = 'Doe';
  6. $data['phone'] = '555-55555';
  7. $data['customer_password'] = '1234';


To replace the card number and/or code after selecting a customer from multiple matches:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'card_replace';
  4. $data['account_id'] = 'greatwidgets';
  5. $data['profile_uid'] = '365';
  6. $data['new_code'] = '1234567890123456';
  7. $data['new_card_number'] = '131313';


Success XML Response for a successful card number/code replacement:

  1. <response status="success">
  2. <customer>
  3. <code>1234567890123456</code>
  4. </customer>
  5. </response>


Success XML Response for multiple matches:

  1. <response status="multiple_matches">
  2. <customers>
  3. <customer>
  4. <profile_uid>365</profile_uid>
  5. <code>0123456789012345</code>
  6. <card_number>121212</card_number>
  7. <first_name>John</first_name>
  8. <last_name>Doe</last_name>
  9. <phone>555-5555</phone>
  10. <email>jdoe@email.com</email>
  11. <street1>123 Main St</street1>
  12. <street2>Apt 3G</street2>
  13. <city>Anytown</city>
  14. <state>ONT</state>
  15. <postal_code>55555</postal_code>
  16. <country>Australia</country>
  17. <custom_date>1970-07-14</custom_date>
  18. <custom_field>Baltimore</custom_field>
  19. </customer>
  20. <customer>
  21. <profile_uid>1267</profile_uid>
  22. <code>2345678901234567</code>
  23. <card_number>343435</card_number>
  24. <first_name>John</first_name>
  25. <last_name>Doe</last_name>
  26. <phone>555-7777</phone>
  27. <email>john.doe@workemail.com</email>
  28. <street1>78 Side St</street1><street2>Apt 3G
  29. <street2></street2>
  30. <city>Bigtown</city>
  31. <state>CA</state>
  32. <postal_code>MX5-4F6</postal_code>
  33. <country>Oceania</country>
  34. <custom_date>1985-06-18</custom_date>
  35. <custom_field></custom_field>
  36. </customer>
  37. ...
  38. </campaign>
  39. </response>


XML Response if no customers matched:

  1. <response status="no_match">
  2. <message>Language-specific "No Customers Match Criteria"</message>
  3. </response>


Error XML Response:

  1. <response status="error">
  2. <error>Error message</error>
  3. </response>