CyberSource Batches API
Once a batch is created its status can be checked using the status resource. When the batch status is COMPLETED its report can then be retrieved.
OpenAPI Specification
swagger: '2.0'
info:
description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
version: 0.0.1
title: CyberSource Merged Spec bankAccountValidation Batches API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Batches
description: 'Once a batch is created its status can be checked using the status resource.
When the batch status is COMPLETED its report can then be retrieved.
'
paths:
/accountupdater/v1/batches:
post:
summary: Create a Batch
description: '**Create a Batch**<br>This resource accepts TMS tokens ids of a Customer, Payment Instrument or Instrument Identifier. <br> The card numbers for the supplied tokens ids are then sent to the relevant card associations to check for updates.<br>The following type of batches can be submitted:
- **oneOff** batch containing tokens id for Visa or MasterCard card numbers.
- **amexRegistration** batch containing tokens id for Amex card numbers.
A batch id will be returned on a successful response which can be used to get the batch status and the batch report.
The availability of API features for a merchant may depend on the portfolio configuration and may need to be enabled at the portfolio level before they can be added to merchant accounts.
'
parameters:
- name: Body
in: body
required: true
schema:
type: object
required:
- included
- notificationEmail
properties:
type:
type: string
default: oneOff
description: "Valid Values:\n * oneOff\n * amexRegistration\n"
included:
type: object
properties:
tokens:
type: array
items:
type: object
required:
- id
properties:
id:
type: string
minLength: 1
maxLength: 32
example: '7030000000000116236'
expirationMonth:
type: string
minLength: 2
maxLength: 2
example: '12'
expirationYear:
type: string
minLength: 4
maxLength: 4
example: '2020'
merchantReference:
type: string
example: TC50171_3
maxLength: 255
description: Reference used by merchant to identify batch.
notificationEmail:
type: string
format: email
example: test@cybs.com
description: Email used to notify the batch status.
tags:
- Batches
operationId: postBatch
x-devcenter-metaData:
categoryTag: Account_Updater
developerGuides: https://developer.cybersource.com/library/documentation/dev_guides/Account_Updater_UG/html/index.html#t=Topics%2FBatch_Update.htm%23TOC_Batches_Resourcebc-1
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
responses:
'202':
description: A new batch has been created.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches
status:
type: array
items:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches/16188390061150001062041064/status
batchId:
type: string
example: '16188390061150001062041064'
description: Unique identification number assigned to the submitted request.
batchItemCount:
type: integer
example: 1
'400':
description: Bad request.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches
code:
type: string
description: "Valid Values:\n * FORBIDDEN_RESPONSE\n * VALIDATION_ERROR\n * UNSUPPORTED_MEDIA_TYPE\n * MALFORMED_PAYLOAD_ERROR\n * SERVER_ERROR\n"
correlationId:
type: string
example: c7b74452a7314f9ca28197d1084447a5
detail:
type: string
example: One or more fields failed validation
fields:
type: array
items:
type: object
properties:
path:
type: string
example: notificationEmail
message:
type: string
example: Email Address is invalid
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.ondemand.batch.email.null\n"
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.forbidden.response\n * cybsapi.validation.error\n * cybsapi.media.notsupported\n"
message:
type: string
example: Field validation error
'401':
description: Not authorized to access resource.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches
code:
type: string
description: "Valid Values:\n * FORBIDDEN_RESPONSE\n * VALIDATION_ERROR\n * UNSUPPORTED_MEDIA_TYPE\n * MALFORMED_PAYLOAD_ERROR\n * SERVER_ERROR\n"
correlationId:
type: string
example: c7b74452a7314f9ca28197d1084447a5
detail:
type: string
example: One or more fields failed validation
fields:
type: array
items:
type: object
properties:
path:
type: string
example: notificationEmail
message:
type: string
example: Email Address is invalid
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.ondemand.batch.email.null\n"
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.forbidden.response\n * cybsapi.validation.error\n * cybsapi.media.notsupported\n"
message:
type: string
example: Field validation error
'415':
description: Unsupported media type provided.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches
code:
type: string
description: "Valid Values:\n * FORBIDDEN_RESPONSE\n * VALIDATION_ERROR\n * UNSUPPORTED_MEDIA_TYPE\n * MALFORMED_PAYLOAD_ERROR\n * SERVER_ERROR\n"
correlationId:
type: string
example: c7b74452a7314f9ca28197d1084447a5
detail:
type: string
example: One or more fields failed validation
fields:
type: array
items:
type: object
properties:
path:
type: string
example: notificationEmail
message:
type: string
example: Email Address is invalid
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.ondemand.batch.email.null\n"
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.forbidden.response\n * cybsapi.validation.error\n * cybsapi.media.notsupported\n"
message:
type: string
example: Field validation error
'422':
description: Failure to process request.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches
code:
type: string
description: "Valid Values:\n * FORBIDDEN_RESPONSE\n * VALIDATION_ERROR\n * UNSUPPORTED_MEDIA_TYPE\n * MALFORMED_PAYLOAD_ERROR\n * SERVER_ERROR\n"
correlationId:
type: string
example: c7b74452a7314f9ca28197d1084447a5
detail:
type: string
example: One or more fields failed validation
fields:
type: array
items:
type: object
properties:
path:
type: string
example: notificationEmail
message:
type: string
example: Email Address is invalid
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.ondemand.batch.email.null\n"
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.forbidden.response\n * cybsapi.validation.error\n * cybsapi.media.notsupported\n"
message:
type: string
example: Field validation error
x-example:
example0:
summary: One Off Visa MasterCard Customer Token Batch
value:
type: oneOff
included:
tokens:
- id: C064DE56200B0DB0E053AF598E0A52AA
- id: C064DE56213D0DB0E053AF598E0A52AA
merchantReference: TC50171_3
notificationEmail: test@cybs.com
example1:
summary: One Off Visa MasterCard Instrument Identifier Token Batch
value:
type: oneOff
included:
tokens:
- id: '7030000000000116236'
expirationMonth: '12'
expirationYear: '2020'
- id: '7030000000000178855'
expirationMonth: '12'
expirationYear: '2020'
merchantReference: TC50171_3
notificationEmail: test@cybs.com
example2:
summary: Amex Registration Customer Token Batch
value:
type: amexRegistration
included:
tokens:
- id: C06977C0EDC0E985E053AF598E0A3326
- id: C069A534044F6140E053AF598E0AD492
merchantReference: TC50171_3
notificationEmail: test@cybs.com
example3:
summary: Amex Registration Instrument Identifier Token Batch
value:
type: amexRegistration
included:
tokens:
- id: '7030000000000260224'
expirationMonth: '12'
expirationYear: '2020'
- id: '7030000000000231118'
expirationMonth: '12'
expirationYear: '2020'
merchantReference: TC50171_3
notificationEmail: test@cybs.com
get:
summary: List Batches
description: '**List Batches**<br>This resource accepts a optional date range, record offset and limit, returning a paginated response of batches containing:
- The batch id.
- The batch status.
- The batch created / modified dates.
- The total number of accepted, rejected, updated records.
- The total number of card association responses.
'
parameters:
- name: offset
in: query
description: Starting record in zero-based dataset that should be returned as the first object in the array.
required: false
type: integer
format: int64
default: 0
minimum: 0
- name: limit
in: query
description: The maximum number that can be returned in the array starting from the offset record in zero-based dataset.
required: false
type: integer
format: int64
default: 20
minimum: 1
maximum: 500
- name: fromDate
in: query
description: 'ISO-8601 format: yyyyMMddTHHmmssZ'
required: false
type: string
- name: toDate
in: query
description: 'ISO-8601 format: yyyyMMddTHHmmssZ'
required: false
type: string
tags:
- Batches
operationId: getBatchesList
x-devcenter-metaData:
categoryTag: Account_Updater
developerGuides: https://developer.cybersource.com/library/documentation/dev_guides/Account_Updater_UG/html/index.html#t=Topics%2FBatch_Update.htm%23TOC_Daily_American_Expressbc-9
produces:
- application/json
- application/json;charset=utf-8
responses:
'200':
description: A list of batches have been returned.
schema:
type: object
properties:
_links:
type: array
items:
type: object
properties:
rel:
type: string
description: "Valid Values:\n * self\n * first\n * last\n * prev\n * next\n"
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches?offset=0&limit=20
object:
type: string
example: collection
offset:
type: integer
example: 0
limit:
type: integer
example: 20
count:
type: integer
example: 1
total:
type: integer
example: 1
_embedded:
type: object
properties:
batches:
type: array
items:
type: object
properties:
_links:
type: object
properties:
reports:
type: array
items:
type: object
description: Retrieve the generated report of a batch when available.
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches/16188390061150001062041064/report
batchId:
type: string
example: '16188390061150001062041064'
description: Unique identification number assigned to the submitted request.
batchCreatedDate:
type: string
example: 2018-05-22T14.38.57Z
description: 'ISO-8601 format: yyyy-MM-ddTHH:mm:ssZ'
batchModifiedDate:
type: string
example: 2018-05-22T14.38.57Z
description: 'ISO-8601 format: yyyy-MM-ddTHH:mm:ssZ'
batchSource:
type: string
description: "Valid Values:\n * SCHEDULER\n * TOKEN_API\n * CREDIT_CARD_FILE_UPLOAD\n * AMEX_REGSITRY\n * AMEX_REGISTRY_API\n * AMEX_REGISTRY_API_SYNC\n * AMEX_MAINTENANCE\n"
tokenSource:
type: string
description: "Valid Values:\n * SECURE_STORAGE\n * TMS\n * CYBERSOURCE\n"
merchantReference:
type: string
example: TC50171_3
maxLength: 255
description: Reference used by merchant to identify batch.
batchCaEndpoints:
type: array
description: "Valid Values:\n * VISA\n * MASTERCARD\n * AMEX\n"
items:
type: string
example: VISA
status:
type: string
description: "Valid Values:\n * REJECTED\n * RECEIVED\n * VALIDATED\n * DECLINED\n * PROCESSING\n * COMPLETE\n"
totals:
type: object
properties:
acceptedRecords:
type: integer
example: 1
rejectedRecords:
type: integer
example: 1
updatedRecords:
type: integer
example: 1
caResponses:
type: integer
example: 1
caResponsesOmitted:
type: integer
example: 1
'401':
description: Not authorized to access resource.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches
code:
type: string
description: "Valid Values:\n * FORBIDDEN_RESPONSE\n * VALIDATION_ERROR\n * UNSUPPORTED_MEDIA_TYPE\n * MALFORMED_PAYLOAD_ERROR\n * SERVER_ERROR\n"
correlationId:
type: string
example: c7b74452a7314f9ca28197d1084447a5
detail:
type: string
example: One or more fields failed validation
fields:
type: array
items:
type: object
properties:
path:
type: string
example: notificationEmail
message:
type: string
example: Email Address is invalid
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.ondemand.batch.email.null\n"
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.forbidden.response\n * cybsapi.validation.error\n * cybsapi.media.notsupported\n"
message:
type: string
example: Field validation error
'422':
description: Failure to process request.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches
code:
type: string
description: "Valid Values:\n * FORBIDDEN_RESPONSE\n * VALIDATION_ERROR\n * UNSUPPORTED_MEDIA_TYPE\n * MALFORMED_PAYLOAD_ERROR\n * SERVER_ERROR\n"
correlationId:
type: string
example: c7b74452a7314f9ca28197d1084447a5
detail:
type: string
example: One or more fields failed validation
fields:
type: array
items:
type: object
properties:
path:
type: string
example: notificationEmail
message:
type: string
example: Email Address is invalid
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.ondemand.batch.email.null\n"
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.forbidden.response\n * cybsapi.validation.error\n * cybsapi.media.notsupported\n"
message:
type: string
example: Field validation error
/accountupdater/v1/batches/{batchId}/status:
get:
summary: Retrieve a Batch Status
description: "**Get Batch Status**<br>This resource accepts a batch id and returns:\n- The batch status.\n- The total number of accepted, rejected, updated records.\n- The total number of card association responses.\n- The billable quantities of:\n - New Account Numbers (NAN)\n - New Expiry Dates (NED)\n - Account Closures (ACL)\n - Contact Card Holders (CCH)\n"
parameters:
- name: batchId
in: path
description: Unique identification number assigned to the submitted request.
required: true
type: string
minLength: 2
maxLength: 26
pattern: ^[0-9]*$
tags:
- Batches
operationId: getBatchStatus
x-devcenter-metaData:
categoryTag: Account_Updater
developerGuides: https://developer.cybersource.com/library/documentation/dev_guides/Account_Updater_UG/html/index.html#t=Topics%2FBatch_Update.htm%23TOC_Retrieving_Update_Reportsbc-6
produces:
- application/json;charset=utf-8
responses:
'200':
description: The status of a batch.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches/16188390061150001062041064/status
report:
type: array
items:
type: object
properties:
href:
type: string
example: https://apitest.cybersource.com/accountupdater/v1/batches/16188390061150001062041064/report
batchId:
type: string
example: '16188390061150001062041064'
description: Unique identification number assigned to the submitted request.
batchCreatedDate:
type: string
example: 2018-05-22T14.38.57Z
description: 'ISO-8601 format: yyyy-MM-ddTHH:mm:ssZ'
batchSource:
type: string
description: "Valid Values:\n * SCHEDULER\n * TOKEN_API\n * CREDIT_CARD_FILE_UPLOAD\n * AMEX_REGSITRY\n * AMEX_REGISTRY_API\n * AMEX_MAINTENANCE\n"
merchantReference:
type: string
example: TC50171_3
maxLength: 255
description: Reference used by merchant to identify batch.
batchCaEndpoints:
type: string
example: VISA,MASTERCARD
status:
type: string
description: "Valid Values:\n * REJECTED\n * RECEIVED\n * VALIDATED\n * DECLINED\n * PROCESSING\n * COMPLETED\n"
totals:
type: object
properties:
acceptedRecords:
type: integer
example: 1
rejectedRecords:
type: integer
example: 1
updatedRecords:
type: integer
example: 1
caResponses:
type: integer
example: 1
caResponsesOmitted:
type: integer
example: 1
billing:
type: object
properties:
nan:
type: integer
example: 1
ned:
type: integer
example: 1
acl:
type: integer
example: 1
cch:
type: integer
example: 1
description:
type: string
example: Your batch has been received, and is being checked for errors.
'403':
description: Unable to perform action for supplied batch ID/merchant.
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: https://api.cybersource.com/accountupdater/v1/batches
code:
type: string
description: "Valid Values:\n * FORBIDDEN_RESPONSE\n * VALIDATION_ERROR\n * UNSUPPORTED_MEDIA_TYPE\n * MALFORMED_PAYLOAD_ERROR\n * SERVER_ERROR\n"
correlationId:
type: string
example: c7b74452a7314f9ca28197d1084447a5
detail:
type: string
example: One or more fields failed validation
fields:
type: array
items:
type: object
properties:
path:
type: string
example: notificationEmail
message:
type: string
example: Email Address is invalid
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.ondemand.batch.email.null\n"
localizationKey:
type: string
description: "Valid Values:\n * cybsapi.forbidden.response\n * cybsapi.validation.error\n * cybsapi.media.notsupported\n"
message:
type: string
example: Field validation error
/accountupdater/v1/batches/{batchId}/report:
get:
summary: Retrieve a Batch Report
description: "**Get Batch Report**<br>This resource accepts a batch id and returns:\n- The batch status.\n- The total number of accepted, rejected, updated records.\n- The total number of card association responses.\n- The billable quantities of:\n - New Account Numbers (NAN)\n - New Expiry Dates (NED)\n - Account Closures (ACL)\n - Contact Card Holders (CCH)\n- Source record information including token ids, masked card number, expiration dates & card type.\n- Response record information including response code, reason, token ids, masked card number, expiration dates & card type.\n"
parameters:
- name: batchId
in: path
description: Unique identification number assigned to the submitted request.
required: true
type: string
minLength: 2
maxLength: 26
pattern: ^[0-9]*$
tags:
- Batches
operationId: getBatchReport
x-devcenter-metaData:
categoryTag: Account_Updater
developerGuides: https://developer.cybersource.com/library/documentation/dev_guides/Account_Updater_UG/html/index.html#t=Topics%2FBatch_Update.htm%23TOC_Retrieving_a_Batch_withbc-10
produces:
- application/json;charset=utf-8
responses:
'200':
description: The report for a batch.
schema:
type: object
properties:
version:
type: string
example: '1.0'
reportCreatedDate:
type: string
example: 2018-05-22T14.38.57Z
description: 'ISO-8601 format: yyyy-MM-ddTHH:mm:ssZ'
batchId:
type: string
example: '16188390061150001062041064'
description: Unique identification number assigned to the submitted request.
batchSource:
type: string
description: "Valid Values:\n * SCHEDULER\n * TOKEN_API\n * CREDIT_CARD_FILE_UPLOAD\n * AMEX_REGSITRY\n * AMEX_REGISTRY_API\n * AMEX_MAINTENANCE\n"
batchCaEndpoints:
type: string
example: VISA,MASTERCARD
batchCreatedDate:
type: string
example: 2018-05-22T14.38.57Z
description: 'ISO-8601 format: yyyy-MM-ddTHH:mm:ssZ'
merchantReference:
type: string
example: TC50171_3
maxLength: 255
description: Reference used by merchant to identify batch.
totals:
type: object
properties:
acceptedRecords:
type: integer
example: 1
rejectedRecords:
type: integer
example: 1
updatedRecords:
type: integer
example: 1
caResponses:
type: integer
example: 1
caResponsesOmitted:
type: integer
example: 1
billing:
type: object
properties:
nan:
type: integer
example: 1
ned:
type: integer
example: 1
acl:
type: integer
example: 1
cch:
type: integer
example: 1
records:
type: array
items:
type: object
properties:
id:
type: string
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-batches-api-openapi.yml