CCBill Transaction API objects are formatted to follow the JSON (JavaScript Object Notation) open-standard file format and use the application/json
content-type.
Use this comprehensive list of CCBill RESTful API objects to determine what parameters are required for endpoint requests and which parameters are returned as responses.
Elements of the optional errors array. Only returned on 400 Bad Request errors for validation errors.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
field | string (required) | The field in error. |
message | string (required) | User-friendly message. |
ValidationError Example
{
"field": "string",
"message": "string"
}
Response if the action failed or could not be completed.
The CCBill Transaction API service uses conventional HTTP response codes to indicate errors. Generally, codes in the range of 4xx
indicate an error due to the information provided in the request. Codes in the range of 5xx
indicate an error due to an unexpected issue.
ERROR CODE | DESCRIPTION |
---|---|
400 | The response failed to complete due to an invalid header/parameter in the request. |
401 | The response failed to complete due to an authorization problem. |
403 | The response failed to complete because access to the resource is forbidden. |
404 | The response failed to complete due to an invalid resource. |
405 | The response failed to complete due to an invalid method of request. |
406 | The response failed to complete due to an unacceptable media type in the request. |
415 | The response failed to complete due to an unsupported media type in the request. |
500 | The response failed to complete in some way. |
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
id | string (required) | Randomly generated GUID. Validation pattern: ^[a-zA-Z0-9-]*$ |
url | string (required) | The relative URL that has caused this error. |
errors | array (optional) | Optional, only returned on 400 Bad Request errors for validation errors. |
errors. field | string (required) | The field in error. |
errors. message | string (required) | User-friendly message. |
generalMessage | string (required) | Something human readable. |
errorCode | CreditCardPaymentInfostring (required) | Product defined error code. Validation pattern: ^[0-9]*$ |
timestamp | Datetime (required) | Timestamp of the call. |
Error Example
{
"id": "62432dd8-97d9-400a-8da8-4a5c1951f935",
"url": "/songs/0",
"errors": [],
"generalMessage": "An error occurred, please try again later.",
"errorCode": "100019",
"timestamp": "2022-12-27T10:36:38.067Z"
}
Elements of the paymentinfo array.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
cardNum | string (required) | Card number. |
expMonth | string (required) | Card expiration month in mm format. |
expYear | string (required) | Card expiration year in yyyy format |
nameOnCard | string (required) | Name as it appears on card. |
CreditCardPaymentInfo Example
{
"cardNum": "4473707989493598",
"expMonth": "04",
"expYear": "2026",
"nameOnCard": "Tyler Thomas"
}
Elements of the paymentinfo array with CVV2 authentication.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
cardNum | string (required) | Card number. |
expMonth | string (required) | Card expiration month in mm format. |
expYear | string (required) | Card expiration year in yyyy format. |
nameOnCard | string (required) | Name as it appears on card. |
cvv2 | string (required) | CVV2 code on the card. |
CreditCardWithCvvPaymentInfo Example
{
"cardNum": "4473707989493598",
"expMonth": "04",
"expYear": "2026",
"nameOnCard": "Tyler Thomas"
"cvv2": "144"
}
Elements of the customerInfo array.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
string (required) | Customer's email address. | |
browserHttpAcceptLanguage | string (optional) | List of acceptable human languages for response. |
browserHttpUserAgent | string (optional) | The user agent string of the user agent. |
city | string (required) | Customer's city. |
browserHttpAccept | string (optional) | Media type(s) that is(/are) acceptable for the response. |
state | string (required) | Customer's state. |
zipcode | string (required) | Customer's zip code. |
customerFname | string (required) | Customer's first name. |
address1 | string (required) | Customer's address. |
address2 | string (optional) | Customer's address (additional info). |
browserHttpAcceptEncoding | string (optional) | List of acceptable encodings. |
customerLname | string (required) | Customer's last name. |
ipAddress | string (required) | Customer's IP address. |
phoneNumber | string (optional) | Customer's phone number. |
country | string (required) | Customer's country. |
CustomerInfo Example
{
"email": "tthomas@xyz.com",
"browserHttpAcceptLanguage": "en-US,en;q=0.5",
"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
"city": "Tempe",
"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"state": "AZ",
"zipcode": "85281",
"customerFname": "Tyler",
"address1": "Woodland Drive",
"address2": "Apt 21",
"browserHttpAcceptEncoding": "gzip, deflate, br",
"customerLname": "Thomas",
"ipAddress": "10.70.60.14",
"phoneNumber": "5555555555",
"country": "US"
}
Elements of the passThroughInfo array represent custom paired information passed through to the transaction service.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
name | string (required) | Custom passthrough value. |
value | string (required) | Custom passthrough value. |
PassThroughInfo Example
{
"name": "value1",
"value": "value2"
}
Payment information on the customer's payment card. Elements of the creditCardPaymentInfo array.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
creditCardPaymentInfo | object (array) | Credit Card Payment Information. |
creditCardPaymentInfo. cardNum | string (required) | Card number. |
creditCardPaymentInfo. expMonth | string (required) | Card expiration month in mm format. |
creditCardPaymentInfo. expYear | string (required) | Card expiration year in yyyy format. |
creditCardPaymentInfo. nameOnCard | string (required) | Name as it appears on card. |
PaymentInfo Example
{
"creditCardPaymentInfo": {
"cardNum": "4473707989493598",
"expMonth": "04",
"expYear": "2026",
"nameOnCard": "Tyler Thomas"
}
}
Elements of the creditCardPaymentInfo array with CVV2 authentication.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
creditCardPaymentInfo | object (array) | Credit Card Payment Information. |
creditCardPaymentInfo. cardNum | string (required) | Card number. |
creditCardPaymentInfo. expMonth | string (required) | Card expiration month in mm format. |
creditCardPaymentInfo. expYear | string (required) | Card expiration year in yyyy format. |
creditCardPaymentInfo. nameOnCard | string (required) | Name as it appears on card. |
creditCardPaymentInfo. cvv2 | string (required) | CVV2 code on the card. |
PaymentInfoWithCVV Example
{
"creditCardPaymentInfo": {
"cardNum": "4473707989493598",
"expMonth": "04",
"expYear": "2026",
"nameOnCard": "Tyler Thomas",
"cvv2": "144"
}
}
These response parameters are received when a payment token is successfully created.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
createdDatetime | DateTime-only (required) | Date and Time of creation of the Payment Token. |
timeToLive | integer (required) | Time for the token to exist. |
originalPaymentTokenId | string (optional) | Reference to a previous Token Id. |
validNumberOfUse | integer (required) | The total number of times the Payment Token can be used for purchases. |
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
programParticipationId | integer (required) | The program connected to the Payment Token. |
paymentTokenId | string (required) | Complex representation of Payment Token Id. |
paymentInfoId | string (optional) | Information associated with the payment. |
subscriptionId | integer (required) | Identification of the subscription associated with the transaction. |
PaymentToken Example
{
"paymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"programParticipationId": 1,
"originalPaymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"clientAccnum": 900000,
"clientSubacc": 0000,
"createdDatetime": "2022-01-01T01:00:00",
"timeToLive": 30,
"validNumberOfUse": 20,
"subscriptionId": 900000000000000001,
"paymentInfoId": "53104f5a54d3d43254def41c29aedba8"
}
These response parameters are received when a payment token is successfully created.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
createdDatetime | DateTime-only (required) | Date and Time of creation of the Payment Token. |
timeToLive | integer (required) | Time for the token to exist. |
originalPaymentTokenId | string (optional) | Reference to a previous Token Id. |
validNumberOfUse | integer (required) | The total number of times the Payment Token can be used for purchases. |
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
programParticipationId | integer (required) | The program connected to the Payment Token. |
paymentTokenId | string (required) | Complex representation of Payment Token Id. |
paymentInfoId | string (optional) | Information associated with the payment. |
subscriptionId | string (required) | Identification of the subscription associated with the transaction. |
PaymentTokenV2 Example
{
"paymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"programParticipationId": 1,
"originalPaymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"clientAccnum": 900000,
"clientSubacc": 0000,
"createdDatetime": "2022-01-01T01:00:00",
"timeToLive": 30,
"validNumberOfUse": 20,
"subscriptionId": 900000000000000001,
"paymentInfoId": "53104f5a54d3d43254def41c29aedba8"
}
These response parameters are received when a payment token is successfully created. Including CVV2 and AVS authentication results.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
createdDatetime | DateTime-only (required) | Date and Time of creation of the Payment Token. |
timeToLive | integer (required) | Time for the token to exist. |
originalPaymentTokenId | string (optional) | Reference to a previous Token Id. |
validNumberOfUse | integer (required) | The total number of times the Payment Token can be used for purchases. |
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
programParticipationId | integer (required) | The program connected to the Payment Token. |
avsResponse | string (required) | The result of AVS verification. |
paymentTokenId | string (required) | Complex representation of Payment Token Id. |
paymentInfoId | string (optional) | Information associated with the payment. |
cvv2Response | string (required) | The result of CVV2 verification. |
subscriptionId | integer (required) | Identification of the subscription associated with the transaction. |
PaymentTokenVerify Example
{
"paymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"programParticipationId": 1,
"originalPaymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"clientAccnum": 900000,
"clientSubacc": 0000,
"createdDatetime": "2022-01-01T01:00:00",
"timeToLive": 30,
"validNumberOfUse": 20,
"subscriptionId": "900000000000000001",
"paymentInfoId": "53104f5a54d3d43254def41c29aedba8",
"cvv2Response": "M",
"avsResponse": "Y"
}
These response parameters are received when a payment token is successfully created. Including CVV2 and AVS authentication results.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
createdDatetime | DateTime-only (required) | Date and Time of creation of the Payment Token. |
timeToLive | integer (required) | Time for the token to exist. |
originalPaymentTokenId | string (optional) | Reference to a previous Token Id. |
validNumberOfUse | integer (required) | The total number of times the Payment Token can be used for purchases. |
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
programParticipationId | integer (required) | The program connected to the Payment Token. |
avsResponse | string (required) | The result of AVS verification. |
paymentTokenId | string (required) | Complex representation of Payment Token Id. |
paymentInfoId | string (optional) | Information associated with the payment. |
cvv2Response | string (required) | The result of CVV2 verification. |
subscriptionId | string (required) | Identification of the subscription associated with the transaction. |
PaymentTokenVerifyV2 Example
{
"paymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"programParticipationId": 1,
"originalPaymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"clientAccnum": 900000,
"clientSubacc": 0000,
"createdDatetime": "2022-01-01T01:00:00",
"timeToLive": 30,
"validNumberOfUse": 20,
"subscriptionId": "900000000000000001",
"paymentInfoId": "53104f5a54d3d43254def41c29aedba8",
"cvv2Response": "M",
"avsResponse": "Y"
}
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
clientAccnum | integer (required) | Merchant's CCBill account number. |
clientSubacc | integer (required) | Merchant's CCBill subaccount number. |
subscriptionId | string (required) | An existing subscription ID number. |
PaymentTokenTransaction Example
{
"clientAccnum": 900112,
"clientSubacc": 0002,
"subscriptionId": "918166501000000981"
}
Parameters for creating a payment token without CVV2 and AVS authentication.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
customerInfo | object (array) | Customer information. |
customerInfo. email | string (required) | Customer's email address. |
customerInfo. browserHttpAcceptLanguage | string (optional) | List of acceptable human languages for response. |
customerInfo. browserHttpUserAgent | string (optional) | The user agent string of the user agent. |
customerInfo. city | string (required) | Customer's city. |
customerInfo. browserHttpAccept | string (optional) | Media type(s) that is(/are) acceptable for the response. |
customerInfo. state | string (required) | Customer's state. |
customerInfo. zipcode | string (required) | Customer's zip code. |
customerInfo. customerFname | string (required) | Customer's first name. |
customerInfo. address1 | string (required) | Customer's address. |
customerInfo. address2 | string (optional) | Customer's address (additional info). |
customerInfo. browserHttpAcceptEncoding | string (optional) | List of acceptable encodings. |
customerInfo. customerLname | string (required) | Customer's last name. |
customerInfo. ipAddress | string (required) | Customer's IP address. |
customerInfo. phoneNumber | string (optional) | Customer's phone number. |
customerInfo. country | string (required) | Customer's country. |
paymentInfo | object (array) | Payment information. |
paymentInfo. cardNum | string (required) | Card number. |
paymentInfo. expMonth | string (required) | Card expiration month in mm format. |
paymentInfo. expYear | string (required) | Card expiration year in yyyy format. |
paymentInfo. nameOnCard | string (required) | Name as it appears on the card. |
subscriptionId | integer (required) | Transaction subscription identification number. |
timeToLive | integer (optional) | Time for the token to exist. |
validNumberOfUse | integer (optional) | The total number of times the Payment Token can be used for purchases. |
PaymentTokenMerchantOnlyParams Example
{
"clientAccnum": 900000,
"clientSubacc": 0000,
"customerInfo": {
"customerFname": "Tyler",
"customerLname": "Thomas",
"address1": "Woodland Drive",
"address2": "Apt 21",
"city": "Tempe",
"state": "AZ",
"zipcode": "85281",
"country": "US",
"phoneNumber": "5555555555",
"email": "tthomas@xyz.com",
"ipAddress": "10.70.60.14",
"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"browserHttpAcceptLanguage": "en-US,en;q=0.5",
"browserHttpAcceptEncoding": "gzip, deflate, br"
},
"paymentInfo": {
"creditCardPaymentInfo": {
"cardNum": "4473707989493598",
"nameOnCard": "Tyler Thomas",
"expMonth": "04",
"expYear": "2026"
}
},
"subscriptionId":900000000000000001,
"timeToLive": 30,
"validNumberOfUse": 3
}
Parameters for creating a payment token that includes CVV2 and AVS authentication.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
customerInfo | object (array) | Customer information. |
customerInfo. email | string (required) | Customer's email address. |
customerInfo. browserHttpAcceptLanguage | string (optional) | List of acceptable human languages for response. |
customerInfo. browserHttpUserAgent | string (optional) | The user agent string of the user agent. |
customerInfo. city | string (required) | Customer's city. |
customerInfo. browserHttpAccept | string (optional) | Media type(s) that is(/are) acceptable for the response. |
customerInfo. state | string (required) | Customer's state. |
customerInfo. zipcode | string (required) | Customer's zip code. |
customerInfo. customerFname | string (required) | Customer's first name. |
customerInfo. address1 | string (required) | Customer's address. |
customerInfo. address2 | string (optional) | Customer's address (additional info). |
customerInfo. browserHttpAcceptEncoding | string (optional) | List of acceptable encodings. |
customerInfo. customerLname | string (required) | Customer's last name. |
customerInfo. ipAddress | string (required) | Customer's IP address. |
customerInfo. phoneNumber | string (optional) | Customer's phone number. |
customerInfo. country | string (required) | Customer's country. |
paymentInfo | object (array) | Payment information. |
paymentInfo. cardNum | string (required) | Card number. |
paymentInfo. expMonth | string (required) | Card expiration month in mm format. |
paymentInfo. expYear | string (required) | Card expiration year in yyyy format. |
paymentInfo. nameOnCard | string (required) | Name as it appears on card. |
paymentInfo. cvv2 | string (required) | CVV2 code on the card. |
subscriptionId | integer (required) | Transaction subscription identification number. |
timeToLive | integer (optional) | Time for the token to exist. |
validNumberOfUse | integer (optional) | The total number of times the Payment Token can be used for purchases. |
PaymentTokenMerchantOnlyVerifyParams Example
{
"clientAccnum": 900000,
"clientSubacc": 0000,
"customerInfo": {
"customerFname": "Tyler",
"customerLname": "Thomas",
"address1": "Woodland Drive",
"address2": "Apt 21",
"city": "Tempe",
"state": "AZ",
"zipcode": "85281",
"country": "US",
"phoneNumber": "5555555555",
"email": "tthomas@xyz.com",
"ipAddress": "10.70.60.14",
"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"browserHttpAcceptLanguage": "en-US,en;q=0.5",
"browserHttpAcceptEncoding": "gzip, deflate, br"
},
"paymentInfo": {
"creditCardPaymentInfo": {
"cardNum": "4473707989493598",
"nameOnCard": "Tyler Thomas",
"expMonth": "04",
"expYear": "2026",
"cvv2": "123"
}
},
"subscriptionId":900000000000000001,
"timeToLive": 30,
"validNumberOfUse": 3
}
Parameters for generating payment tokens for cross-sale opportunities with other specified program participants (merchants).
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
customerInfo | object (array) | Customer information. |
customerInfo. email | string (required) | Customer's email address. |
customerInfo. browserHttpAcceptLanguage | string (optional) | List of acceptable human languages for the response. |
customerInfo. browserHttpUserAgent | string (optional) | The user agent string of the user agent. |
customerInfo. city | string (required) | Customer's city. |
customerInfo. browserHttpAccept | string (optional) | Media type(s) that is(/are) acceptable for the response. |
customerInfo. state | string (required) | Customer's state. |
customerInfo. zipcode | string (required) | Customer's zip code. |
customerInfo. customerFname | string (required) | Customer's first name. |
customerInfo. address1 | string (required) | Customer's address. |
customerInfo. address2 | string (optional) | Customer's address (additional info). |
customerInfo. browserHttpAcceptEncoding | string (optional) | List of acceptable encodings. |
customerInfo. customerLname | string (required) | Customer's last name. |
customerInfo. ipAddress | string (required) | Customer's IP address. |
customerInfo. phoneNumber | string (optional) | Customer's phone number. |
customerInfo. country | string (required) | Customer's country. |
paymentInfo | object (array) | Payment information. |
paymentInfo. cardNum | string (required) | Card number. |
paymentInfo. expMonth | string (required) | Card expiration month in mm format. |
paymentInfo. expYear | string (required) | Card expiration year in yyyy format. |
paymentInfo. nameOnCard | string (required) | Name as it appears on the card. |
subscriptionId | integer (required) | Transaction subscription identification number. |
programParticipationId | integer (required) | The identifier represents the program associated with the transaction. |
timeToLive | integer (optional) | Time for the token to exist. |
validNumberOfUse | integer (optional) | The total number of times the Payment Token can be used for purchases. |
PaymentTokenProgramSpecifiedParams Example
{
"clientAccnum": 900000,
"clientSubacc": 0000,
"customerInfo": {
"customerFname": "Tyler",
"customerLname": "Thomas",
"address1": "Woodland Drive",
"address2": "Apt 21",
"city": "Tempe",
"state": "AZ",
"zipcode": "85281",
"country": "US",
"phoneNumber": "5555555555",
"email": "tthomas@xyz.com",
"ipAddress": "10.70.60.14",
"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"browserHttpAcceptLanguage": "en-US,en;q=0.5",
"browserHttpAcceptEncoding": "gzip, deflate, br"
},
"paymentInfo": {
"creditCardPaymentInfo": {
"cardNum": "4473707989493598",
"nameOnCard": "Tyler Thomas",
"expMonth": "04",
"expYear": "2026"
}
},
"subscriptionId": 900000000000000001,
"programParticipationId": 1,
"timeToLive": 30,
"validNumberOfUse": 3
}
Parameters for generating a payment token for the specified merchant/client. It requires an active program participation and enables merchants to create payment tokens for cross-sale opportunities with other merchants.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
customerInfo | object (array) | Customer information. |
customerInfo. email | string (required) | Customer's email address. |
customerInfo. browserHttpAcceptLanguage | string (optional) | List of acceptable human languages for the response. |
customerInfo. browserHttpUserAgent | string (optional) | The user agent string of the user agent. |
customerInfo. city | string (required) | Customer's city. |
customerInfo. browserHttpAccept | string (optional) | Media type(s) that is(/are) acceptable for the response. |
customerInfo. state | string (required) | Customer's state. |
customerInfo. zipcode | string (required) | Customer's zip code. |
customerInfo. customerFname | string (required) | Customer's first name. |
customerInfo. address1 | string (required) | Customer's address. |
customerInfo. address2 | string (optional) | Customer's address (additional info). |
customerInfo. browserHttpAcceptEncoding | string (optional) | List of acceptable encodings. |
customerInfo. customerLname | string (required) | Customer's last name. |
customerInfo. ipAddress | string (required) | Customer's IP address. |
customerInfo. phoneNumber | string (optional) | Customer's phone number. |
customerInfo. country | string (required) | Customer's country. |
paymentInfo | object (array) | Payment information. |
paymentInfo. cardNum | string (required) | Card number. |
paymentInfo. expMonth | string (required) | Card expiration month in mm format. |
paymentInfo. expYear | string (required) | Card expiration year in yyyy format. |
paymentInfo. nameOnCard | string (required) | Name as it appears on card. |
subscriptionId | integer (required) | Transaction subscription identification number. |
targetClientAccnum | integer (required) | Target merchant account number. |
targetClientSubacc | integer (required) | Target merchant subaccount number. |
timeToLive | integer (optional) | Time for the token to exist. |
validNumberOfUse | integer (optional) | The total number of times the Payment Token can be used for purchases. |
PaymentTokenTargetClientParams Example
{
"clientAccnum": 900000,
"clientSubacc": 0000,
"customerInfo": {
"customerFname": "Tyler",
"customerLname": "Thomas",
"address1": "Woodland Drive",
"address2": "Apt 21",
"city": "Tempe",
"state": "AZ",
"zipcode": "85281",
"country": "US",
"phoneNumber": "5555555555",
"email": "tthomas@xyz.com",
"ipAddress": "10.70.60.14",
"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"browserHttpAcceptLanguage": "en-US,en;q=0.5",
"browserHttpAcceptEncoding": "gzip, deflate, br"
},
"paymentInfo": {
"creditCardPaymentInfo": {
"cardNum": "4473707989493598",
"nameOnCard": "Tyler Thomas",
"expMonth": "04",
"expYear": "2026"
}
},
"subscriptionId": 900000000000000001,
"targetClientAccnum": 900000,
"targetClientSubacc": 0001,
"timeToLive": 30,
"validNumberOfUse": 3
}
Response parameters confirm that a customer was successfully charged using a payment token.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
errorCode | integer (required) | Error condition value of the transaction. |
approved | boolean (required) | Approval status of the transaction. |
paymentUniqueId | string (required) | Unique key connected to payment account. |
sessionId | string (required) | Unique session ID value for transaction. |
subscriptionId | integer (required) | Subscription ID to which the transaction belongs. |
newPaymentTokenId | string (required) | New payment token for subsequent transactions. |
TransactionInfo Example
{
"errorCode": 200,
"approved": true,
"paymentUniqueId": "53104f5a54d3d43254def41c29aedba8",
"sessionId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"subscriptionId": 900000000000000001,
"newPaymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
}
Request parameters for initiating a transaction request for a customer.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
createNewPaymentToken | boolean (true/false) | Return new payment token for subsequent transactions or not. |
initialPrice | number (required) | Price of the initial transaction. |
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
lifeTimeSubscription | boolean (optional) | Subscription is valid during the website's lifetime. |
initialPeriod | integer (required) | The time period of the initial transaction |
recurringPeriod | integer (optional) | The time period of recurrent transactions. |
currencyCode | integer (optional) | Numerical representation of the currency used in the transaction. |
rebills | integer (optional) | The number of times recurrent transactions can occur. |
recurringPrice | number (optional) | Price of recurrent transactions. |
passThroughInfo | array (optional) | Paired Information Passed Through to the Transaction Service. |
TransactionRequest Example
{
"clientAccnum":900123,
"clientSubacc":0010,
"initialPrice": 9.99,
"initialPeriod": 10,
"recurringPrice": 15.00,
"recurringPeriod": 30,
"rebills": 99,
"currencyCode": 840,
"lifeTimeSubscription": false,
"createNewPaymentToken": false,
"passThroughInfo": [
{
"name": "val1",
"value": "val2"
}
]
}
Parameters for initiating a charge with 3DS authentication.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
createNewPaymentToken | boolean (true/false) | Return new payment token for subsequent transactions or not. |
initialPrice | number (required) | Price of the initial transaction. |
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
lifeTimeSubscription | boolean (optional) | Subscription is valid during the website's lifetime. |
initialPeriod | integer (required) | The time period of the initial transaction |
recurringPeriod | integer (optional) | The time period of recurrent transactions. |
currencyCode | integer (optional) | Numerical representation of the currency used in the transaction. |
rebills | integer (optional) | The number of times recurrent transactions can occur. |
recurringPrice | number (optional) | Price of recurrent transactions. |
passThroughInfo | array (optional) | Paired Information Passed Through to the Transaction Service. |
threeedsXid | string (optional) | XID for threeds request. |
threedsVersion | string (optional) | The version number for threeds request. |
threedsSuccess | boolean (optional) | Success for threeds request. |
threedsAmount | integer (optional) | Amount for threeds request. |
threedsEci | string (required) | ECI for threeds request. |
threedsCavv | string (required) | CAVV for threeds request. |
threedsCavvAlgorithm | string (optional) | CAVV Algorithm for threeds request. |
threedsId | string (optional) | Id for threeds request. |
threedsStatus | string (optional) | Status for threeds request. |
threedsTransactionId | string (optional) | Transaction Id for threeds request. |
threedsError | string (optional) | Error for threeds request. |
ThreedsTransactionRequest Example
{
"clientAccnum":900123,
"clientSubacc":0010,
"initialPrice": 9.99,
"initialPeriod": 10,
"recurringPrice": 15.00,
"recurringPeriod": 30,
"rebills": 99,
"currencyCode": 840,
"lifeTimeSubscription": false,
"createNewPaymentToken": false,
"passThroughInfo": [
{
"name": "val1",
"value": "val2"
}
],
"threedsCavv": "cGFzc3dvcmQxMjM0NTZwYXNzd28=",
"threedsCavvAlgorithm": "3",
"threedsEci": "05",
"threedsError": "",
"threedsTransactionId": "id-7kzs4vel57n",
"threedsId": "id-7kzs4vel57n",
"threedsStatus": "Y",
"threedsSuccess": true,
"threedsVersion": "1.0.2",
"threedsXid": "123",
"threedsAmount": "999"
}
Require 3DS authentication for card payment.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
required | boolean (true/false) | 3DS required for payment card. |
amount | number | Authorized charge amount. |
ThreeDSRequired Example
{
"required": "true",
"amount": "1.0"
}
VALUE | DESCRIPTION |
---|---|
M | CVV2/CVC2/CID Match |
N | CVV2/CVC2/CID No Match |
P | Not Processed |
S | The CVV2/CVC2/CID should be on the card, but the merchant indicates it is not. |
U | The Issuer is not certified or has not provided Visa with encryption keys. |
VALUE | DESCRIPTION |
---|---|
A | The street addresses match but the postal/ZIP code does not, or the request does not include the postal/ZIP code. |
B | Street addresses match. The postal code is not verified due to incompatible formats (both street address and postal code were sent.) |
C | The street address and postal code not verified due to incompatible formats. (both street address and postal code were sent) |
D | Street addresses and postal codes match |
F | Street address and postal code match. (U.K.- issued cards) |
G | Issuer is not an AVS participant, or AVS data was present in the request but issuer did not return an AVS result, or Visa performs AVS on behalf of the issuer and there was no address record on file for this account. |
O | Address information is not verified. |
M | Street address and postal code match. |
N | No match.Transaction contained Postal/ZIP code only, or street address only, or postal code and street address. Also used when transaction requests AVS but sends no AVS data. |
P | Postal codes match. Postal code and street address were sent, but street address not verified due to incompatible formats. |
R | Retry; System unavailable or timed out. |
S | AVS currently not supported |
U | No data from Issuer/Authorization platform |
V | Nine character postal code matches; address does not match |
X | Nine character postal code and address match |
Y | Street address and postal code match |
Z | Postal/ZIP matches, street address does not match, or street address not included in request. |
1 | Cardholder name and ZIP match |
2 | Cardholder name, address, and ZIP match |
3 | Cardholder name and address match |
4 | Cardholder name matches |
5 | Cardholder name incorrect, ZIP matches |
6 | Cardholder name incorrect; address and ZIP match |
7 | Cardholder name incorrect, address matches |
8 | Cardholder name, address, and ZIP do not match |
paymentTokenVerify Example
{
"paymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"programParticipationId": 1,
"originalPaymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
"clientAccnum": 900000,
"clientSubacc": 0,
"createdDatetime": "2018-01-01T01:00:00",
"timeToLive": 30,
"validNumberOfUse": 20,
"subscriptionId": "900000000000000001",
"paymentInfoId": "53104f5a54d3d43254def41c29aedba8",
"cvv2Response": "M",
"avsResponse": "Y"
}