Account Updater

Developer Guide



















































Version: 24.01

Account Updater | 2





 

 





 

 

 





 







 

 



























 





Account Updater | Contents | 3

Contents | 4

 



 







 









 

 









Account Updater | Contents | 4

Account Updater



















































Account Updater | Account Updater | 5

Recent Revisions to This Document

























Account Updater | Account Updater | 6

VISA Platform Connect: Specifications and Conditions for

Resellers/Partners









 







 



 





 



















Account Updater | Account Updater | 7

Introduction to Account Updater



















• 

• 

Tokenization



























Account Updater | Introduction to Account Updater | 8

Token Harvest Updates







Token Selective Batch Updates













Storing PANs









Enabling Account Updater























Account Updater | Introduction to Account Updater | 9

Business Center Permissions







• 

• 

• 

• 









• 

◦ 

◦ 

• 



• 

• 



• 

Account Updater | Introduction to Account Updater | 10



• 





• 



Account Updater | Introduction to Account Updater | 11

Token Updates























Token Harvest















Account Updater | Token Updates | 12

Token Batch Updates



• https://apitest.cybersource.com/accountupdater/v1/batches

• https://api.cybersource.com/accountupdater/v1/batches

Submitting Visa and Mastercard One-Time Updates









oneOff

Registering Tokens for American Express Daily Updates









amexRegistration

Account Updater | Token Updates | 13

Batch Creation Request Examples



• 

• 

• 













Account Updater | Token Updates | 14



{

"type": "oneOff",

"included": {

"tokens": [

{

"id": "3FA02EB4E49B65FDA194B38994B1F3F3"

{

"id": "D1944BD9A7F9052BE431A276EB492C39"

}

]

"merchantReference": "Merchant reference",

"notificationEmail": "[email protected]"

}



{

"type": "amexRegistration",

"included": {

"tokens": [

{

"id": "7B1F41664F08F6DD3BB1C63892907524",

"expirationMonth": "12",

"expirationYear": "2021"

{

"id": "E8F44CFA7EBEADDB06A5A9625E7F8696",

"expirationMonth": "12",

"expirationYear": "2021"

}

]

"merchantReference": "Merchant reference",

"notificationEmail": "[email protected]"

}

Account Updater | Token Updates | 15

Batch Creation Response Examples



{

"_links": {

"self": {

"href": "https://api.cybersource.com/accountupdater/v1/batches"

"status": {

"href":

"https://api.cybersource.com/accountupdater/v1/batches/152699969452400021395943

85/status"

}

batchId": "15269996945240002139594385",

batchItemCount": 2

}



{

"_links": {

"self": {

"href": "https://api.cybersource.com/accountupdater/v1/batches"

}

"code": "FORBIDDEN_RESPONSE",

"correlationId": "c7b74452a7314f9ca28197d1084447a5",

"detail": "You are not authorized to access this resource",

"fields": null,

"localizationKey": "cybsapi.forbidden.response",

"message": "Unauthorized Access"

}







Account Updater | Token Updates | 16



{

"_links": {

"self": {

"href": "https://api.cybersource.com/accountupdater/v1/batches"

}

"code": "VALIDATION_ERROR",

"correlationId": "c7b74452a7314f9ca28197d1084447a5",

"detail": "One or more fields failed validation",

"fields": [

{

"path": "notificationEmail",

"message": "Email address provided should not be 'null'",

"localizationKey": "cybsapi.ondemand.batch.email.null"

}

"localizationKey": "cybsapi.validation.error",

"message": "Field validation error"

}





Retrieving Update Reports









Account Updater | Token Updates | 17

Visa and Mastercard One-Time Updates









ACCEPT=application/json

• https://apitest.cybersource.com/accountupdater/v1/batches/{batchId}/status

• https://api.cybersource.com/accountupdater/v1/batches/{batchId}/status

One-Time Batch Update Response









Status Responses

 

Received 

Processing 

Updating 



Completed 



Failed 

Received 

Processing Updating Completed

Failed 

acceptedRecords rejectedRecords 

Completed

Account Updater | Token Updates | 18



{

"_links": {

"self": {

"href":

"https://api.cybersource.com/accountupdater/v1/batches/152699969452400021395943

85/status"

"report": [

{

"href":

"https://api.cybersource.com/accountupdater/v1/batches/152699969452400021395943

85/status"

}

]

"batchCaEndpoints": "VISA,MASTERCARD",

"batchCreatedDate": "2018-05-22T14.38.57Z",

"batchId": "15269996945240002139594385",

"batchSource": "TOKEN_API",

"billing": {

"nan": "0,",

"ned": "9,",

"acl": "5,",

"cch": 0

"description": "Batch processing complete. Report URL now available.",

"merchantReference": "Merchant reference",

"status": "COMPLETED",

"totals": {

"acceptedRecords": "8,",

"rejectedRecords": "7,",

"updatedRecords": "8,",

"caResponses": "14,",

"caResponsesOmitted": 6

}

Account Updater | Token Updates | 19

American ExpressDailyand Token Harvest Update Reports









ACCEPT=application/json



• https://apitest.cybersource.com/accountupdater/v1/batches

• https://api.cybersource.com/accountupdater/v1/batches



/v1/batches?offset=1&limit=50



v1/batches?fromDate=20200315T000000Z&toDate=20200415T000000Z



{

"_links": [

{

"rel": "self",

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches?offset=0&limit=1"

{

"rel": "first",

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches?offset=0&limit=1"

{

"rel": "next",

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches?offset=1&limit=1"

{

Account Updater | Token Updates | 20



"rel": "last",

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches?offset=114&limit=1"

}

"object": "collection",

"offset": 0,

"limit": 3,

"count": 1,

"total": 3,

"_embedded": {

"batches": [

{

"_links": {

"reports": [

{

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches/1541603147941000209921

2314/report"

}

]

"batchId": "15416031479410002099212314",

"batchCreatedDate": "2018-11-07T07:05:48Z",

"batchModifiedDate": "2018-11-07T07:05:50Z",

"batchSource": "SCHEDULER",

"tokenSource": "TMS",

"merchantReference": "Merchant Name",

"batchCaEndpoints": [

"VISA",

"MASTERCARD"

"status": "COMPLETE",

"totals": {

"acceptedRecords": 1,

"rejectedRecords": 0,

"updatedRecords": 1,

"caResponses": 1,

"caResponsesOmitted": 0

}

Account Updater | Token Updates | 21



{

"_links": {

"reports": [

{

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches/1541602501073000165534

3827/report"

}

]

"batchId": "15416025010730001655343827",

"batchCreatedDate": "2018-11-07T06:55:01Z",

"batchModifiedDate": "2018-11-07T06:56:52Z",

"batchSource": "AMEX_REGISTRY_API",

"tokenSource": "TMS",

"batchCaEndpoints": [

"AMEX"

"status": "COMPLETE"

{

"_links": {

"reports": [

{

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches/1541602501073000165534

3827/report"

}

]

"batchId": "15402221273070001683984545",

"batchCreatedDate": "2018-10-22T08:28:47Z",

"batchModifiedDate": "2018-10-22T08:29:19Z",

"batchSource": "AMEX_MAINTENANCE",

"tokenSource": "TMS",

"batchCaEndpoints": [

"AMEX"

"status": "COMPLETE",

"totals": {

"acceptedRecords": 0

}

]

}

Account Updater | Token Updates | 22



Batch Source Values

 

AMEX_REGISTRY_API 





AMEX_MAINTENANCE 



TOKEN_API 



SCHEDULER 









Account Updater | Token Updates | 23



{

"_links": {

"self": {

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches/1581602353562000164685

4894/status"

"report": [

{

"href":

"https://apitest.cybersource.com/accountupdater/v1/batches/1581602353562000164685

4894/report"

}

]

"batchCaEndpoints": "AMEX",

"batchCreatedDate": "2020-02-13T13.59.13Z",

"batchId": "15816023535620001646854894",

"batchSource": "AMEX_REGISTRY_API",

"description": "Updates have been applied to your tokens. A batch report is

available.",

"merchantReference": "Merchant Name",

"status": "COMPLETE",

"totals":

{

"acceptedRecords": 999,

"rejectedRecords": 123,

"updatedRecords": 0,

"caResponses": 0,

"caResponsesOmitted": 0

}

Account Updater | Token Updates | 24

Retrieving a Batch with a Batch ID



ACCEPT=application/json





{

"version": "1.0",

"reportCreatedDate": "2018-11-07T15:33:11Z",

"batchId": "15416047164330001593314231",

"batchSource": "AMEX_REGISTRY_API",

"batchCaEndpoints": "AMEX",

"batchCreatedDate": "2018-11-07T15:31:56Z",

"merchantReference": "Merchant Name",

"totals": {

"acceptedRecords": 0,

"rejectedRecords": 3

"records": [

{

"sourceRecord": {

"token": "12345678901234567890",

"cardExpiryMonth": "01",

"cardExpiryYear": "2021"

"responseRecord": {

"response": "DEC",

"reason": "852"

}

{

"sourceRecord": {

"token": "456",

"cardExpiryMonth": "01",

"cardExpiryYear": "2021"

"responseRecord": {

"response": "DEC",

"reason": "851"

}

Account Updater | Token Updates | 25



{

"sourceRecord": {

"token": "789",

"cardExpiryMonth": "01",

"cardExpiryYear": "2021"

"responseRecord": {

"response": "DEC",

"reason": "851"

}

]

}

American Express Daily Updates





• 

• 









additionalUpdates 











{

"version": "1.0",

"reportCreatedDate": "2020-01-23T11:16:13Z",

"batchId": "15797780137010000506182090",

"batchSource": "AMEX_MAINTENANCE",

"batchCaEndpoints": "AMEX",

"batchCreatedDate": "2020-01-23T11:13:33Z",

"totals": {

"updatedRecords": 3,

"rejectedRecords": 0,

Account Updater | Token Updates | 26



"caResponses": 3,

"caResponsesOmitted": 0

"billing": {

"nan": 1,

"ned": 1,

"acl": 1,

"cch": 0

"records": [

{

"id": "562239661",

"sourceRecord": {

"token": "9CCD3AE24DD9E254E0533F36CF0A356E",

"cardNumber": "371449XXXXX2009",

"cardExpiryMonth": "02",

"cardExpiryYear": "2021",

"cardType": "003",

"customerId": "9CCD3AE24DD9E254E0533F36CF0A356E",

"paymentInstrumentId": "9CCD3AE24DD8E254E0533F36CF0A356E",

"instrumentIdentifierId": "9CCD3AE24DD7E254E0533F36CF0A356E"

"responseRecord": {

"response": "NAN",

"reason": "800",

"token": "9CCD3AE24DD9E254E0533F36CF0A356E",

"cardNumber": "371449XXXXX0102",

"cardType": "003",

"instrumentIdentifierId": "9CCDC4D08BE0C16BE0533F36CF0A9916",

"instrumentIdentifierCreated": "true",

"cardExpiryMonth": "07",

"cardExpiryYear": "2021",

"additionalUpdates": [

{

"customerId": "8CCD3AE24DD8E254E0533F36CF0A355E",

"paymentInstrumentId": "9CCD3AE24DD8E254E0533F36CF0A356D",

"creator": "aura_regress_tms_report",

"state": "CLOSED",

"message": "This Payment Instrument contains the source card number,

which is now closed. If required, you can update manually or through the AU REST

API."

}

]

}

Account Updater | Token Updates | 27



{

"id": "562239711",

"sourceRecord": {

"token": "9CCD3AE24DF7E254E0533F36CF0A356E",

"cardNumber": "371449XXXXX1100",

"cardExpiryMonth": "02",

"cardExpiryYear": "2021",

"cardType": "003",

"customerId": "9CCD3AE24DF7E254E0533F36CF0A356E",

"paymentInstrumentId": "9CCD3AE24DF6E254E0533F36CF0A356E",

"instrumentIdentifierId": "9CCD3AE24DF5E254E0533F36CF0A356E"

"responseRecord": {

"response": "NED",

"reason": "800",

"cardExpiryMonth": "12",

"cardExpiryYear": "2021"

}

{

"id": "562239751",

"sourceRecord": {

"token": "9CCD3AE24E0FE254E0533F36CF0A356E",

"cardNumber": "371449XXXXX1226",

"cardExpiryMonth": "02",

"cardExpiryYear": "2021",

"cardType": "003",

"customerId": "9CCD3AE24E0FE254E0533F36CF0A356E",

"paymentInstrumentId": "9CCD3AE24E0EE254E0533F36CF0A356E",

"instrumentIdentifierId": "9CCD3AE24E0DE254E0533F36CF0A356E"

"responseRecord": {

"response": "ACL",

"reason": "800",

"additionalUpdates": [

{

"customerId": "7CCD3AE24DD8E254E0533F36CF0A356A",

"paymentInstrumentId": "9CCD3AE24E0EE254E0533F36CF0A356D",

"creator": "aura_regress_tms_report",

"state": "CLOSED",

"message": "This Payment Instrument contains the source card number,

which is now closed. If required, you can update manually or through the AU REST

API."

}

]

}

]

}

Account Updater | Token Updates | 28



{

version": "1.0

"reportCreatedDate": "2018-11-01T14:43:36Z",

"batchId": "15410833473400000123332450",

"batchSource": "SCHEDULER",

"batchCaEndpoints": "VISA,MASTERCARD",

"batchCreatedDate": "2018-11-01T14:42:27Z",

"merchantReference": "Merchant Name",

"totals": {

"acceptedRecords": 2,

"caResponses": 3,

"rejectedRecords": 0,

"updatedRecords": 2,

"caResponsesOmitted": 1

"billing": {

"nan": 1,

"ned": 0,

"acl": 1,

"cch": 0

"records": [

{

"id": "4451434614",

"sourceRecord": {

"token": "4682345889876532701018",

"cardNumber": "511111XXXXXX3604",

"cardExpiryMonth": "09",

"cardExpiryYear": "2021",

"cardType": "002"

"responseRecord": {

"response": "ACL",

"reason": "800"

}

{

"id": "784311",

"sourceRecord": {

"token": "7020000000014008934",

"cardNumber": "371000XXXXXX8115",

"cardExpiryMonth": "01",

"cardExpiryYear": "2021",

"cardType": "003",

"instrumentIdentifierId": "7020000000014008115"

Account Updater | Token Updates | 29



"responseRecord": {

"response": "NAN",

"reason": "800",

"token": "7020000000012513358",

"cardNumber": "401000XXXXXX2753",

"cardType": "001",

"instrumentIdentifierId": "7020000000012512753",

"instrumentIdentifierCreated": "true",

"cardExpiryMonth": "08",

"cardExpiryYear": "2021"

}

]

}



{

"_links": {

"self": {

"href": "https://api.cybersource.com/accountupdater/v1/batches/

154108334734003332450/report"

}

"code": "FORBIDDEN_RESPONSE",

"correlationId": "0386623ab0eb47dfae61d273032f8202",

"detail": "You are not authorized to access this resource",

"localizationKey": "cybsapi.forbidden.response",

"message": "Unauthorized Access"

Account Updater | Token Updates | 30

PAN Updates



















Creating Security Keys





Transaction Security Key















PGP Public/Private Key







Account Updater | PAN Updates | 31







Formatting a Request File





• 

• 

• 

Request Header Record





Header Record Fields

  















 











 

 



 



Account Updater | PAN Updates | 32

Header Record Fields 

  







 









 

Account Updater | PAN Updates | 33

Header Record Fields 

  







 



 

 





 



 









 

 





 



Request Detail Record



Detail Record Fields

  







 





 

Account Updater | PAN Updates | 34

Detail Record Fields 

  







   









 









 

















 













 



Account Updater | PAN Updates | 35

Request Footer Record



Footer Record Field

  



















 

Request File Examples



H,cybs.au.request.pan,merchant1,001,2,[email protected],2019-03-23,My January

Batch

D,1111222233334444,11,09,0001

D,2222333344445555,11,09,0002



H,cybs.au.request.pan,merchant1,001,2,[email protected],2019-03-23,My January

Batch

D,1111222233334444,11,09,0001,subId01

D,2222333344445555,11,09,0002,subId02

Account Updater | PAN Updates | 36

Uploading a Request File























•  https://accountupdatertest.cybersource.com/upload/encrypted-pans

•  https://accountupdater.cybersource.com/upload/encrypted-pans







Authorization: Basic

base64Encode(<merchant-id>:<hex-formatted-merchant-public-key-fingerprint>)



HTTP Error Codes

  

  



  

Account Updater | PAN Updates | 37

HTTP Error Codes 

  



  

  

  





Account Updater | PAN Updates | 38

Email Notification















Email Notifications

  





























  













 





 







Related information

Viewing the Batch File Status (on page 40)

Account Updater | PAN Updates | 39

Viewing the Status of a Batch File

 

◦ 

◦ 

 

 

 





◦ 

◦ 



 







Downloading a Response File









◦ 

◦ 

 

 

 

 



 

Account Updater | PAN Updates | 40

Response File Records









• 

• 

Response Header Record



Header Record Fields

 































 





 





Account Updater | PAN Updates | 41

Response Detail Record



Response Detail Record Fields

  



 







  

  





















  





















Account Updater | PAN Updates | 42

Response Detail Record Fields 

  















 







  

  

Related information

PAN Upload Response Codes and Reason Codes (on page 51)

Response Footer Record



Footer Record Fields

  



 





  

  

Account Updater | PAN Updates | 43

Footer Record Fields 

  



  

Related information

PAN Upload Response Codes and Reason Codes (on page 51)

Response File Examples



H,cybs.au.response.pan,merchant1,001

D,1000000000000000001,1111222233334444,11,09,,,,0001,,NUP,800

D,1000000000000000002,2222333344445555,11,09,6666777788889999,11,11,0002,,NAN,800

F,2,COM,800



H,cybs.au.response.pan,merchant1,001

D,1000000000000000001,1111222233334444,11,09,,,,0001,subId01,NUP,800

D,1000000000000000002,2222333344445555,11,09,6666777788889999,11,11,0002,subId02,N

AN,800

F,2,COM,800

Account Updater | PAN Updates | 44

Testing













American Express Test Card Numbers





371449 



American Express Test Numbers

 

0 0002 0115 

1 0211 2216 

2 0121 2206 

1 0021 1119 

1 0101 0023 

0 0100 2112 

1 2101 2009 

0 2201 2009 

2 1000 0113 

0 2100 0229 

2 2210 0224 

0 0112 0203 

0 2102 1100 

2 0121 2107 

Account Updater | Testing | 45

American Express Test Numbers 

 

0 1121 0119 

0 1022 1109 

1 0112 1226 

2 0201 0005 

1 2121 0207 

0 1012 2109 

1 2120 0224 

2 1010 0020 

1 1202 1118 

1 0122 0218 

0 0010 2004 

1 1111 2108 

1 4254 6639 

6 7595 0950 

Related information

PAN Upload Response Codes and Reason Codes (on page 51)

Mastercard Test Card Numbers



511111 



Mastercard Card Test Numbers

 

10 4714 3086 

10 2999 7178 

Account Updater | Testing | 46

Mastercard Card Test Numbers 

 

10 1548 6814 

10 5459 2548 

10 4871 8571 

10 5798 7356 

10 7450 2964 

10 6971 3154 

10 2030 4416 

10 4733 5823 

10 3135 3600 

10 4816 3604 

10 1867 3020 

10 3056 0627 

10 0270 8865 

10 6646 9396 

Account Updater | Testing | 47

Mastercard Card Test Numbers 

 

10 5787 1816 

10 7350 8855 

Related information

PAN Upload Response Codes and Reason Codes (on page 51)

Visa Test Card Numbers





400000 

Visa Card Test Numbers

 

71 0951 9220 

15 3919 2096 

18 6481 0239 

91 9582 8465 

27 5765 7455 

71 1311 2087 

21 1752 4874 

Account Updater | Testing | 48

Visa Card Test Numbers 

 

71 1629 4650 

20 5548 7183 

52 8063 4792 

24 0631 2635 

89 2339 9344 

55 7908 8940 

57 9875 5634 

80 9110 0706 

26 9567 5155 

35 8627 6236 

Related information

PAN Upload Response Codes and Reason Codes (on page 51)

Account Updater | Testing | 49

API Fields



Account Updater | API Fields | 50

PAN Upload Response Codes and Reason Codes

Record Level





D,1000000000000000002,2222333344445555,11,09,6666777788889999,11,11,0002,,NAN,800

Record Response Codes and Reason Codes

 



 







 

















  

 



  

    

   





    

Account Updater | PAN Upload Response Codes and Reason Codes | 51

Record Response Codes and Reason Codes

 



 







   





   





   





    

   





   





    

   













    

Account Updater | PAN Upload Response Codes and Reason Codes | 52

Record Response Codes and Reason Codes

 



 

















   











   







   





    

   





   







   







   





Account Updater | PAN Upload Response Codes and Reason Codes | 53

Record Response Codes and Reason Codes

 



 







   







   







 







  

 



  

 



  

 





 







Request File Level







F,2,COM,800

Account Updater | PAN Upload Response Codes and Reason Codes | 54

Request File Response Codes and Reason Codes

  





 





 

 





 





Account Updater | PAN Upload Response Codes and Reason Codes | 55

Sample Java Code for Uploading PANs



Requirements

• 

• 





•





Using the Sample Code



 



 



 

 



 

 



Security.provider.2=org.bouncycastle.jce.provider.BouncyCastleProvider

Account Updater | Sample Java Code for Uploading PANs | 56

 



security.provider.1=sun.security.provider.Sun

security.provider.2=org.bouncycastle.jce.provider.BouncyCastleProvider

security.provider.3=com.sun.net.ssl.internal.ssl.Provider

security.provider.4=com.sun.rsajca.Provider

security.provider.5=com.sun.crypto.provider.SunJCE

security.provider.6=sun.security.jgss.SunProvider





 

 

 

 

 

 

giraffe 

 

 

 





 

https://accountupdatertest.cybersource.com/upload/UploadAccountUpdaterFile

https://accountupdater.cybersource.com/upload/UploadAccountUpdaterFile

 

 

 

 

 

 

Account Updater | Sample Java Code for Uploading PANs | 57

 

 

 

 

 

















$JAVA_HOME/bin/keytool -import -file /home/bluu/MyCert.cer-keystore

MyKeystore.jks -storepass myMerchantID





Owner: CN=accountupdatertest.cybersource.com, OU=Operations,

O=Cybersource Corporation, L=Foster City, ST=California, C=US Issuer:

Entrust.net Limited, OU=www.entrust.net/CPS incorp. by ref. (limits

liab.), O=Entrust.net, C=US Serial number: 374e1b7b Valid from: Thu Nov

18 17:15:34 PST 2018 until: Tue Jan 31 17:51:24 PST 2020 Certificate

fingerprints: MD5: BE:BF:B0:91:69:C4:7B:10:45:EC:D6:0F:16:AA:3D:77

SHA1: 07:F8:41:DC:B2:FC:F5:DA:FC:EE:09:7A:33:B8:29:15:31:18 Trust this

certificate? [no]: yes Certificate was added to keystore

 





># Upload host host=accountupdatertest.cybersource.com # Upload

port port=<upload port> # Username to log into the Business Center

bcUserName=<Business Center login name> # Password to log into the Business

Center bcPassword=<Business Center login password> # File to upload

uploadFile=<path to your file>/<file name> # Path where to upload the file

Account Updater | Sample Java Code for Uploading PANs | 58

(provided by Cybersource) path=/upload/UploadAccountUpdaterFile # Your

Cybersource security key key=<key location path>/<key file name> # New

key store you just created that contains the certificate keyStore=<key

store location>/<new key store name> # pass phrase is the string you

used in -storepass option when you # created the key store file earlier

passPhrase=<pass phrase>

 



JAVA_HOME=/home/j2se

 

 

 













HTTP/1.1 200 OK

Date: Wed, 26 Jan 2005 17:26:31 GMT

Server: Apache Coyote/1.0

Content-Type: text/plain

Content-Length: 0

X-Cache: MISS from <your host>

Connection: close

UPLOAD FILE SUCCESSFUL

Account Updater | Sample Java Code for Uploading PANs | 59