CyberSource Verification API
The Verification API from CyberSource — 2 operation(s) for verification.
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 Verification API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Verification
paths:
/risk/v1/address-verifications:
post:
summary: Verify customer address
description: This call verifies that the customer address submitted is valid.
operationId: verifyCustomerAddress
tags:
- Verification
x-devcenter-metaData:
categoryTag: Risk_Management
parameters:
- name: verifyCustomerAddressRequest
in: body
required: true
schema:
type: object
properties:
clientReferenceInformation:
type: object
properties:
code:
type: string
maxLength: 59
description: 'Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
#### Used by
**Authorization**
Required field.
#### PIN Debit
Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being
reversed.
Required field for all PIN Debit requests (purchase, credit, and reversal).
#### FDC Nashville Global
Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports.
'
comments:
type: string
maxLength: 255
description: 'Brief description of the order or any comment you wish to add to the order.
'
partner:
type: object
properties:
developerId:
type: string
maxLength: 8
description: 'Identifier for the developer that helped integrate a partner solution to CyberSource.
Send this value in all requests that are sent through the partner solutions built by that developer.
CyberSource assigns the ID to the developer.
**Note** When you see a developer ID of 999 in reports, the developer ID that was submitted is incorrect.
'
solutionId:
type: string
maxLength: 8
description: 'Identifier for the partner that is integrated to CyberSource.
Send this value in all requests that are sent through the partner solution. CyberSource assigns the ID to the partner.
**Note** When you see a solutionId of 999 in reports, the solutionId that was submitted is incorrect.
'
orderInformation:
type: object
properties:
billTo:
type: object
required:
- address1
- locality
- country
- postalCode
properties:
address1:
type: string
maxLength: 60
description: 'Payment card billing street address as it appears on the credit card issuer''s records.
#### SEPA
Required for Create Mandate and Import Mandate
#### Atos
This field must not contain colons (:).
#### CyberSource through VisaNet
**Important** When you populate orderInformation.billTo.address1 and orderInformation.billTo.address2,
CyberSource through VisaNet concatenates the two values. If the concatenated value exceeds 40 characters,
CyberSource through VisaNet truncates the value at 40 characters before sending it to Visa and the issuing bank.
Truncating this value affects AVS results and therefore might also affect risk decisions and chargebacks.
Credit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet
accepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations
of the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the
credit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless
ASCII characters for transmission to the credit card networks.
#### FDMS Nashville
When the street name is numeric, it must be sent in numeric format. For example, if the address is _One First Street_,
it must be sent as _1 1st Street_.
Required if keyed; not used if swiped.
String (20)
#### TSYS Acquiring Solutions
Required when `processingInformation.billPaymentOptions.billPayment=true` and `pointOfSaleInformation.entryMode=keyed`.
#### All other processors:
Optional.
String (60)
#### For Payouts
This field may be sent only for FDC Compass.
**Important** It is your responsibility to determine whether a field is required for the transaction you are requesting.
'
address2:
type: string
maxLength: 60
description: 'Used for additional address information. For example: _Attention: Accounts Payable_
Optional field.
For Payouts: This field may be sent only for FDC Compass.
#### Atos
This field must not contain colons (:).
#### CyberSource through VisaNet
**Important** When you populate `orderInformation.billTo.address1` and `orderInformation.billTo.address2`,
CyberSource through VisaNet concatenates the two values. If the concatenated value exceeds 40 characters,
CyberSource through VisaNet truncates the value at 40 characters before sending it to Visa and the issuing bank.
Truncating this value affects AVS results and therefore might also affect risk decisions and chargebacks.
Credit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet
accepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations
of the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the
credit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless
ASCII characters for transmission to the credit card networks.
#### Chase Paymentech Solutions, FDC Compass, and TSYS Acquiring Solutions
This value is used for AVS.
#### FDMS Nashville
`orderInformation.billTo.address1` and `orderInformation.billTo.address2` together cannot exceed 20 characters.
String (20)
#### All Other Processors
String (60)
'
address3:
type: string
maxLength: 60
description: 'Additional address information (third line of the billing address)
'
address4:
type: string
maxLength: 60
description: 'Additional address information (fourth line of the billing address)
'
administrativeArea:
type: string
maxLength: 50
description: 'State or province of the billing address. Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf).
For Payouts: This field may be sent only for FDC Compass.
##### CyberSource through VisaNet
Credit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet
accepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations
of the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the
credit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless
ASCII characters for transmission to the credit card networks.
**Important** It is your responsibility to determine whether a field is required for the transaction you are requesting.
#### Chase Paymentech Solutions
Optional field.
#### Credit Mutuel-CIC
Optional field.
#### OmniPay Direct
Optional field.
#### SIX
Optional field.
#### TSYS Acquiring Solutions
Required when `processingInformation.billPaymentOptions.billPayment=true` and `pointOfSaleInformation.entryMode=keyed`.
#### Worldpay VAP
Optional field.
#### All other processors
Not used.
'
country:
type: string
maxLength: 3
description: 'Payment card billing country. Use the two-character [ISO Standard Country Codes](http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf).
#### SEPA/BACS
Required for Create Mandate and Import Mandate
#### CyberSource through VisaNet
Credit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet
accepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations
of the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the
credit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless ASCII
characters for transmission to the credit card networks.
**Important** It is your responsibility to determine whether a field is required for the transaction you are requesting.
#### Chase Paymentech Solutions
Optional field.
#### Credit Mutuel-CIC
Optional field.
#### OmniPay Direct
Optional field.
#### SIX
Optional field.
#### TSYS Acquiring Solutions
Required when `processingInformation.billPaymentOptions.billPayment=true` and `pointOfSaleInformation.entryMode=keyed`.
#### Worldpay VAP
Optional field.
#### All other processors
Not used.
'
locality:
type: string
maxLength: 50
description: 'Payment card billing city.
#### SEPA
Required for Create Mandate and Import Mandate
#### Atos
This field must not contain colons (:).
#### CyberSource through VisaNet
Credit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet accepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations of the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the credit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless ASCII characters for transmission to the credit card networks.
#### For Payouts:
This field may be sent only for FDC Compass.
#### Chase Paymentech Solutions
Optional field.
#### Credit Mutuel-CIC
Optional field.
#### OmniPay Direct
Optional field.
#### SIX
Optional field.
#### TSYS Acquiring Solutions
Required when `processingInformation.billPaymentOptions.billPayment=true` and `pointOfSaleInformation.entryMode=keyed`.
#### Worldpay VAP
Optional field.
#### All other processors
Not used.
'
postalCode:
type: string
maxLength: 10
description: "Postal code for the billing address. The postal code must consist of 5 to 9 digits.\n\nWhen the billing country is the U.S., the 9-digit postal code must follow this format:\n[5 digits][dash][4 digits]\n\n**Example** `12345-6789`\n\nWhen the billing country is Canada, the 6-digit postal code must follow this format:\n[alpha][numeric][alpha][space][numeric][alpha][numeric]\n\n**Example** `A1B 2C3`\n\n**Important** It is your responsibility to determine whether a field is required for the transaction you are requesting.\n\n#### SEPA\nRequired for Create Mandate and Import Mandate\n\n#### For Payouts:\n This field may be sent only for FDC Compass.\n\n#### American Express Direct\nBefore sending the postal code to the processor, CyberSource removes all nonalphanumeric characters and, if the remaining value is longer than nine characters, truncates the value starting from the right side.\n\n#### Atos\nThis field must not contain colons (:).\n\n#### CyberSource through VisaNet\nCredit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet\naccepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations\nof the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the\ncredit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless ASCII\ncharacters for transmission to the credit card networks.\n\n#### FDMS Nashville\nRequired if `pointOfSaleInformation.entryMode=keyed` and the address is in the U.S. or Canada.\nOptional if `pointOfSaleInformation.entryMode=keyed` and the address is **not** in the U.S. or Canada.\nNot used if swiped.\n\n#### RBS WorldPay Atlanta:\nFor best card-present keyed rates, send the postal code if `pointOfSaleInformation.entryMode=keyed`.\n\n#### TSYS Acquiring Solutions\nRequired when `processingInformation.billPaymentOptions.billPayment=true` and `pointOfSaleInformation.entryMode=keyed`.\n\n#### All other processors:\nOptional field.\n"
shipTo:
type: object
required:
- address1
- country
properties:
address1:
type: string
maxLength: 60
description: 'First line of the shipping address.
Required field for authorization if any shipping address information is included in the request; otherwise, optional.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
address2:
type: string
maxLength: 60
description: 'Second line of the shipping address.
Optional field.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
address3:
type: string
maxLength: 60
description: 'Third line of the shipping address.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
address4:
type: string
maxLength: 60
description: Fourth line of the shipping address.
administrativeArea:
type: string
maxLength: 50
description: "State or province of the shipping address. Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf) (maximum length: 2) \n\nRequired field for authorization if any shipping address information is included in the request and shipping to the U.S.\nor Canada; otherwise, optional.\n\n#### Tax Calculation\nOptional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.\nBilling address objects will be used to determine the cardholder's location when shipTo objects are not present.\n"
country:
type: string
description: 'Country of the shipping address. Use the two-character [ISO Standard Country Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf)
Required field for authorization if any shipping address information is included in the request; otherwise, optional.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
maxLength: 3
locality:
type: string
maxLength: 50
description: 'City of the shipping address.
Required field for authorization if any shipping address information is included in the request and shipping to the U.S. or
Canada; otherwise, optional.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
postalCode:
type: string
maxLength: 32
description: 'Postal code for the shipping address. The postal code must consist of 5 to 9 digits.
Required field for authorization if any shipping address information is included in the request and
shipping to the U.S. or Canada; otherwise, optional.
When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example 12345-6789
When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha][numeric]
Example A1B 2C3
#### American Express Direct
Before sending the postal code to the processor, all nonalphanumeric characters are removed and, if the
remaining value is longer than nine characters, the value is truncated starting from the right side.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
lineItems:
type: array
items:
type: object
properties:
unitPrice:
type: string
maxLength: 15
description: 'Per-item price of the product. If line items are present in the request, the unit price is a mandatory field.
'
quantity:
type: integer
minimum: 1
maximum: 999999999
default: 1
description: 'Number of units for this order. Must be a non-negative integer.
The default is `1`. For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`),
this field is required when `orderInformation.lineItems[].productCode` is not `default` or one of the other values
related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
'
productSKU:
type: string
maxLength: 255
description: 'Product identifier code. Also known as the Stock Keeping Unit (SKU) code for the product.
For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`), this field is required when `orderInformation.lineItems[].productCode` is not set to **default** or one of the other values that are related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`), this field is
required when `orderInformation.lineItems[].productCode` is not `default` or one of the values related to shipping and/or handling.
'
productRisk:
type: string
maxLength: 6
description: 'Indicates the level of risk for the product. This field can contain one of the following values:
- `low`: The product is associated with few chargebacks.
- `normal`: The product is associated with a normal number of chargebacks.
- `high`: The product is associated with many chargebacks.
'
productName:
type: string
maxLength: 255
description: 'For an authorization or capture transaction (`processingOptions.capture` is `true` or `false`),
this field is required when `orderInformation.lineItems[].productCode` is not `default` or one of
the other values that are related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
'
productCode:
type: string
maxLength: 255
description: 'Type of product. The value for this field is used to identify the product category (electronic, handling, physical,
service, or shipping). The default value is `default`.
If you are performing an authorization transaction (`processingOptions.capture` is set to `false`), and you set
this field to a value other than `default` or one of the values related to shipping and/or handling, then
`orderInformation.lineItems[].quantity`, `orderInformation.lineItems[].productName`, and
`orderInformation.lineItems[].productSku` fields are required.
Optional field.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
The Product Codes for the tax service are located in the Cybersource Tax Codes guide. Contact Customer Support to request the guide. If you don''t send a tax service Product Code in your tax request, product-based rules or exemptions will not be applied and the transaction will default to fully taxable in the locations where you''ve indicated you need to collect tax [by way of nexus, no nexus, or seller registration number fields].
'
buyerInformation:
type: object
properties:
merchantCustomerId:
type: string
maxLength: 100
description: 'Optional customer''s account ID, tracking number, reward number, or other unique number
that you assign to the customer for the purpose that you choose
'
responses:
'201':
description: Successful response
schema:
title: riskV1AddressVerificationsPost201Response
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
id:
type: string
maxLength: 26
description: 'An unique identification number generated by Cybersource to identify the submitted request. Returned by all services.
It is also appended to the endpoint of the resource.
On incremental authorizations, this value with be the same as the identification number returned in the original authorization response.
'
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
**Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.).
The `T` separates the date and the time. The `Z` indicates UTC.
Returned by Cybersource for all services.
'
submitTimeLocal:
type: string
description: Time that the transaction was submitted in local time. Generated by Cybersource.
status:
type: string
description: 'The status for the call can be:
- COMPLETED
- INVALID_REQUEST
- DECLINED
'
message:
type: string
description: "The message describing the reason of the status. Value can be\n - Apartment number missing or not found.\n - Insufficient address information.\n - House/Box number not found on street.\n - Multiple address matches were found.\n - P.O. Box identifier not found or out of range.\n - Route service identifier not found or out of range.\n - Street name not found in Postal code.\n - Postal code not found in database.\n - Unable to verify or correct address.\n - Multiple addres matches were found (international)\n - Address match not found (no reason given)\n - Unsupported character set\n"
clientReferenceInformation:
type: object
properties:
code:
type: string
maxLength: 59
description: 'Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
#### Used by
**Authorization**
Required field.
#### PIN Debit
Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being
reversed.
Required field for all PIN Debit requests (purchase, credit, and reversal).
#### FDC Nashville Global
Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports.
'
comments:
type: string
maxLength: 255
description: 'Brief description of the order or any comment you wish to add to the order.
'
partner:
type: object
properties:
developerId:
type: string
ma
# --- truncated at 32 KB (120 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-verification-api-openapi.yml