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 | string (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 (optional) | Return new payment token for subsequent transactions or not. |
clientAccnum | integer (required) | Merchant account number. |
clientSubacc | integer (required) | Merchant subaccount number. |
initialPrice | float (required) | Initial transaction price. |
initialPeriod | integer (required) | The length (in days) of the initial billing period. |
currencyCode | string (optional) | Three-digit currency code (ISO 4217 standard) for the currency used in the transaction. |
recurringPrice | float (optional) | The amount the consumer will be charged for each recurring bill. |
recurringPeriod | integer (optional) | The length of time between rebills. |
rebills | integer (optional) | The total number of times the subscription will rebill. |
lifeTimeSubscription | boolean (optional) | The presence of this variable with a value of 1 indicates that the transaction is a lifetime subscription. |
createNewPaymentToken | boolean (optional) | Return new payment token for subsequent transactions or not. |
passThroughInfo | Array[any] (optional) | Paired information being passed through to the transaction service. |
threedsCardToken | string (required) | The encrypted cardToken you receive through the 3DS verification process. As we require only the first 16 characters, trim the string to that length before sending it to the CCBill API. Sending a string longer than 16 characters results in an error. Example value: gjeoB5NdJ1r6p0dG |
threedsEci | string (required) | An Electronic Commerce Indicator (ECI). Values: '0', '1', '2', '5', '6', or '7'. |
threedsStatus | string (required) | The status of the 3DS verification ('Y', 'N', 'A', etc.) |
threedsVersion | string (required) | The version of the 3DS protocol to be followed for this specific card and transaction. Available versions are 1.0.2 and 2.1.0 |
threedsXid | string (optional/required) | The transaction identifier (XID) is a unique tracking number set by the merchant for 3DS. It is a required parameter for threedsVersion 1.0.2 |
threedsCavv | string (optional/required) | A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow and is a required parameter for threedsVersion 1.0.2 |
threedsCavvAlgorithm | string (optional/required) | CAVV Algorithm for threeds request. The threedsCavvAlgorithm parameter is required for threedsVersion 1.0.2 |
threedsDsTransId | string (optional/required) | Directory Server Transaction ID. The threedsDsTransId parameter is required for threedsVersion 2.1.0 |
threedsAcsTransId | string (optional/required) | Access Control Server Transaction ID. The threedsAcsTransId parameter is required for threedsVersion 2.1.0 |
threedsSdkTransId | string (optional) | The 3DS vendor's transaction ID. |
threedsAuthenticationType | string (optional) | A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v2.1.0). |
threedsAuthenticationValue | string (optional) | A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v2.1.0). |
threedsClientTransactionId | string (required) | The parameter is automatically generated by the Advanced Widget. Its purpose is to identify the origin of the 3DS authentication transaction. |
threedsSuccess | boolean (required) | Verification of 3DS authentication success or failure. |
threedsAmount | integer (optional) | The amount to be charged (same as initialPrice). |
threedsCurrency | integer (optional) | The 3-digit currency code for the currency to be used in this transaction. Example value: 840 |
threedsError | string (optional/required) | Error received from the 3DS vendor during the strong customer authentication process. The parameter is required if no threedsVersion is provided. |
threedsErrorDetail | string (optional) | Error details related to the threedsError. |
threedsErrorCode | string (optional) | Error code. |
threedsResponse | string (optional) | The complete response in case of an error. |
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"
}
],
"threedsEci": "05",
"threedsError": "",
"threedsStatus": "Y",
"threedsSuccess": "true",
"threedsVersion": "1.0.2",
"threedsXid": "aWQteHc4ajJnNGIxZW8gICAgICA=",
"threedsCavv": "cGFzc3dvcmQxMjM0NTZwYXNzd28=",
"threedsCavvAlgorithm": "SHA-256",
"threedsAmount": "10",
"threedsClientTransactionId": "id-wl9r6duc5zj",
"threedsCurrency": "USD",
"threedsSdkTransId": "",
"threedsAcsTransId": "",
"threedsDsTransId": "",
"threedsAuthenticationType": "",
"threedsCardToken": "gjeoB5NdJ1r6p0dG",
"threedsErrorDetail": "",
"threedsErrorCode": "",
"threedsResponse": ""
}
Response parameters after 3DS authentication request.
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"
}