To access endpoints, use an HTTPS POST request with a valid JSON payload:
nTest endpoint: https://apitest.cybersource.com/accountupdater/v1/batches
nLive endpoint: https://api.cybersource.com/accountupdater/v1/batches
Submitting Visa and Mastercard One-Off Updates
Tokens can be submitted for a one-off update to Visa and Mastercard. Your update report is generated in 24 to 48 hours. A successful response to the batch creation returns a batch ID. You can check the status of the batch, which returns the URI of the batch update report when available.
Set the type field to oneOff in order to perform this type of update.
Registering Tokens for American Express Daily Updates
You register tokens containing American Express cards for daily updates. CyberSource receives updates from American Express daily, applies them to your tokens, and produces a daily report that is available to you through the REST API.
To indicate that the batch contains tokens to be enrolled with American Express Cardrefresher, set the type to amexRegistration.
Batch Creation Request Examples
TMS supports different types of tokens:
nCustomer
nPayment instrument
nInstrument identifier
Customer tokens and payment instrument tokens store the expiration date in addition to the PAN. Instrument identifier tokens store only the PAN.
|
|
Each batch request should contain only one token type: customer, payment instrument, or instrument identifier. |
For more information about TMS tokens, see Token Management Service Using the Simple Order API (PDF | HTML), Token Management Service Using the SCMP API
(PDF | HTML), or Token Management Service on the Developer Center.
Account Updater requires the existing PAN and expiration date. If you are using instrument identifier tokens, you must also to specify the expiration date.
Example 1Creating a Batch of Two Customer or Payment Instrument Tokens
{
"type": "oneOff",
"included": {
"tokens": [
{
"id": "3FA02EB4E49B65FDA194B38994B1F3F3"
},
{
"id": "D1944BD9A7F9052BE431A276EB492C39"
}
]
},
"merchantReference": "Merchant reference",
"notificationEmail": "email@example.com"
}
Example 2Creating a Batch of Two Instrument Identifier Tokens
{
"type": "amexRegistration",
"included": {
"tokens": [
{
"id": "7B1F41664F08F6DD3BB1C63892907524",
"expirationMonth": "12",
"expirationYear": "2018"
},
{
"id": "E8F44CFA7EBEADDB06A5A9625E7F8696",
"expirationMonth": "12",
"expirationYear": "2018"
}
]
},
"merchantReference": "Merchant reference",
"notificationEmail": "email@example.com"
}
Batch Creation Response Examples
Example 3HTTP 202 – Successful Batch Creation
{
"_links": {
"self": {
"href": "https://api.cybersource.com/accountupdater/v1/batches"
},
"status": {
"href": "https://api.cybersource.com/accountupdater/v1/batches/15269996945240002139594385/status"
}
},
"batchId": "15269996945240002139594385",
"batchItemCount": 2
}
Example 4HTTP 401 – Not authorized to access resource.
{
"_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"
}
Action: Verify that the credentials that you are using are correct for the environment you are accessing. Ensure that your credentials have not expired and that your authentication process is correct.
Example 5422 – Failure to process request
{
"_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"
}
Action: Examine the message to learn what failed validation. Verify that the structure of your JSON format is correct.
The update reports contain details of updates that have been applied to the token and include a masked version of new card numbers and/or expiration dates.
To retrieve the batch, obtain the batch ID. The process for retrieving the batch depends on how the batch was created.
Visa and Mastercard One-Off Reports
One-off updates are retrieved by checking the batch status URL that was returned in the one-off batch creation process. See Submitting Visa and Mastercard One-Off Updates. An authenticated GET on the following resources returns the status of the batch:
nTest endpoint:
https://apitest.cybersource.com/accountupdater/v1/batches/{batchId}/status
nLive endpoint:
https://api.cybersource.com/accountupdater/v1/batches/{batchId}/status
The processing of a batch by Visa and Mastercard can take up to 48 hours; therefore, reports are not available immediately. A successful response returns the status of the batch and additional information relating to the batch as it becomes available.
The following batch statuses are possible:
|
Status |
Description |
|
Received |
The batch was received and is being checked for errors. |
|
Processing |
The batch was sent to the card association(s) to be updated. |
|
Updating |
CyberSource received a response from the card association(s) and is updating the tokens. |
|
Complete |
Updates have been applied to the tokens. |
|
Failed |
Review specific error message. |
|
|
Not all data is available immediately. As the batch status progresses from Received through Processing and Updating to Complete, additional data becomes available in the batch status. Check the status after submitting the batch to catch early errors that might result in a Failed status or incorrect acceptedRecords or rejectedRecords counts. The URL of the batch report appears when the status is Complete. |
Example 6HTTP 200 – Successful Response
{
"_links": {
"self": {
"href": "https://api.cybersource.com/accountupdater/v1/batches/15269996945240002139594385/status"
},
"report": [
{
"href": "https://api.cybersource.com/accountupdater/v1/batches/15269996945240002139594385/report"
}
]
},
"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
}
}
Daily American Express and Harvest Update Reports
American Express update reports are generated daily, so the batch ID is not known in advance.
Similarly, harvest updates are scheduled by the Account Updater service on a date you agree upon with your CyberSource account representative.
For both integration options, the first step is to retrieve the batch ID itself by sending an authenticated GET request on the following resources:
nTest endpoint: https://apitest.cybersource.com/accountupdater/v1/batches
nLive endpoint: https://api.cybersource.com/accountupdater/v1/batches
This step returns an array of batches. Paging is supported with offset and limit query parameters. For example, to return the second page of results with 50 per page you need to send GET /v1/batches?offset=1&limit=50.
Example 7HTTP 200 – Successful Response
{
"_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"
},
{
"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/15416031479410002099212314/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
}
},
{
"_links": {
"reports": [
{
"href": "https://apitest.cybersource.com/accountupdater/v1/batches/15416025010730001655343827/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/15416025010730001655343827/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
}
}
]
}
}
Batches are identified by the batch creation date (batchCreatedDate) and the batch method (batchSource) field values. The following table provides the batchSource possible values:
|
batchSource Value |
Description |
|
AMEX_REGISTRY_API |
Batch for American Express token registration. American Express generates a report only when the registration batch contains errors. |
|
AMEX_MAINTENANCE |
Daily updates for tokens enrolled in the American Express Cardrefresher service. |
|
TOKEN_API |
Updates relating to a one-off request to Visa or Mastercard. |
|
SCHEDULER |
Updates relating to a monthly harvest of all tokens. |
After you submit a batch for American Express token registration, you can access the batch status through the authenticated GET request using the URL returned in the submission. A successful response of the authenticated GET returns the status of the batch. See Registering Tokens for American Express Daily Updates.
Example 8American Express Registry Status Response
{
"_links": {
"self": {
"href": "https://apitest.cybersource.com/accountupdater/v1/batches/15816023535620001646854894/status"
},
"report": [
{
"href": "https://apitest.cybersource.com/accountupdater/v1/batches/15816023535620001646854894/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
}
}
Retrieving a Batch with a Batch ID
You can access an individual batch report through an authenticated GET request using the URL returned in the batch status or batches resource described in the previous sections.
HTTP 200 – Successful Response
Example 9AMEX_REGISTRY_API Batch Method
{
"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": "2001"
},
"responseRecord": {
"response": "DEC",
"reason": "852"
}
},
{
"sourceRecord": {
"token": "456",
"cardExpiryMonth": "01",
"cardExpiryYear": "2001"
},
"responseRecord": {
"response": "DEC",
"reason": "851"
}
},
{
"sourceRecord": {
"token": "789",
"cardExpiryMonth": "01",
"cardExpiryYear": "2001"
},
"responseRecord": {
"response": "DEC",
"reason": "851"
}
}
]
}
American Express Daily Updates
Card numbers in TMS are represented by instrument identifier tokens. A card number and its associated instrument identifier token will be set to a CLOSED status when:
nThe card network sends a direct account closed notification (response code ACL).
nA new card number is issued to replace a cancelled card (response code NAN).
Account Updater updates customer and payment instrument tokens only when you specify them in the request. When you specify a customer token for update or harvest, only the customer's default payment instrument token is updated. When you do not specify the customer and payment instrument tokens, they can become associated with a closed instrument identifier token in the update batch or harvest. These results are detailed in the additionalUpdates section of the update report. To update customer tokens and payment instrument tokens, include them in a subsequent Account Updater batch API request, or send a direct call to the TMS REST API. See Token Management Service on the Developer Center.
Example 10AMEX_MAINTENANCE Batch Method
{
"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,
"caResponses": 3,
"caResponsesOmitted": 0
},
"billing": {
"nan": 1,
"ned": 1,
"acl": 1,
"cch": 0
},
"records": [
{
"id": "562239661",
"sourceRecord": {
"token": "9CCD3AE24DD9E254E0533F36CF0A356E",
"cardNumber": "371449XXXXX2009",
"cardExpiryMonth": "02",
"cardExpiryYear": "2020",
"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": "2020",
"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."
}
]
}
},
{
"id": "562239711",
"sourceRecord": {
"token": "9CCD3AE24DF7E254E0533F36CF0A356E",
"cardNumber": "371449XXXXX1100",
"cardExpiryMonth": "02",
"cardExpiryYear": "2020",
"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": "2020",
"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."
}
]
}
}
]
}
Example 11TOKEN_API Batch Method & Scheduler
{
"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": "21",
"cardType": "002"
},
"responseRecord": {
"response": "ACL",
"reason": "800"
}
},
{
"id": "784311",
"sourceRecord": {
"token": "7020000000014008934",
"cardNumber": "371000XXXXXX8115",
"cardExpiryMonth": "01",
"cardExpiryYear": "2016",
"cardType": "003",
"instrumentIdentifierId": "7020000000014008115"
},
"responseRecord": {
"response": "NAN",
"reason": "800",
"token": "7020000000012513358",
"cardNumber": "401000XXXXXX2753",
"cardType": "001",
"instrumentIdentifierId": "7020000000012512753",
"instrumentIdentifierCreated": "true",
"cardExpiryMonth": "08",
"cardExpiryYear": "2021"
}
}
]
}
Example 12Batch Retrieval Error
{
"_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"