CCBill RESTful API Schemas

API Summary

CCBill Transaction API objects are formatted to follow the JSON (JavaScript Object Notation) open-standard file format and use the application/json content-type.

Supported Media Types
  • application/json
Available Values
  • application/vnd.mcn.transaction-service.api.v.1+json
  • application/vnd.mcn.transaction-service.api.v.2+json

API Resources

/payment-tokens

  • /payment-tokens/merchant-only
  • /payment-tokens/merchant-only-verify
  • /payment-tokens/{paymentTokenId}
  • /payment-tokens/{paymentTokenId}/threeds-required
  • /payment-tokens/program-specified
  • /payment-tokens/target-client
  • /payment-tokens/threeds-required

/transactions

  • /transactions/payment-tokens/{payment_token_id}
  • /transactions/payment-tokens/{payment_token_id}
  • /transactions/payment-tokens/threeds/{payment_token_id}

API Schemas

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.

ValidationError

Elements of the optional errors array. Only returned on 400 Bad Request errors for validation errors.

PARAMETERTYPEDESCRIPTION
fieldstring
(required)
The field in error.
messagestring
(required)
User-friendly message.

ValidationError Example

{
  "field": "string",
  "message": "string"
}

Error

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 CODEDESCRIPTION
400The response failed to complete due to an invalid header/parameter in the request.
401The response failed to complete due to an authorization problem.
403The response failed to complete because access to the resource is forbidden.
404The response failed to complete due to an invalid resource.
405The response failed to complete due to an invalid method of request.
406The response failed to complete due to an unacceptable media type in the request.
415The response failed to complete due to an unsupported media type in the request.
500The response failed to complete in some way.
Resources
Parameters
PARAMETERTYPEDESCRIPTION
idstring
(required)
Randomly generated GUID.
Validation pattern: ^[a-zA-Z0-9-]*$
urlstring
(required)
The relative URL that has caused this error.
errorsarray
(optional)
Optional, only returned on 400 Bad Request errors for validation errors.
errors. fieldstring
(required)
The field in error.
errors. messagestring
(required)
User-friendly message.
generalMessagestring
(required)
Something human readable.
errorCodeCreditCardPaymentInfostring
(required)
Product defined error code.
Validation pattern: ^[0-9]*$
timestampDatetime
(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"
}

CreditCardPaymentInfo

Elements of the paymentinfo array.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
cardNumstring
(required)
Card number.
expMonthstring
(required)
Card expiration month in mm format.
expYearstring
(required)
Card expiration year in yyyy format
nameOnCardstring
(required)
Name as it appears on card.

CreditCardPaymentInfo Example

{
  "cardNum": "4473707989493598",
  "expMonth": "04",
  "expYear": "2026",
  "nameOnCard": "Tyler Thomas"
}

CreditCardWithCvvPaymentInfo

Elements of the paymentinfo array with CVV2 authentication.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
cardNumstring
(required)
Card number.
expMonthstring
(required)
Card expiration month in mm format.
expYearstring
(required)
Card expiration year in yyyy format.
nameOnCardstring
(required)
Name as it appears on card.
cvv2string
(required)
CVV2 code on the card.

CreditCardWithCvvPaymentInfo Example

{
  "cardNum": "4473707989493598",
  "expMonth": "04",
  "expYear": "2026",
  "nameOnCard": "Tyler Thomas"
  "cvv2": "144"
}

CustomerInfo

Elements of the customerInfo array.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
emailstring
(required)
Customer's email address.
browserHttpAcceptLanguagestring
(optional)
List of acceptable human languages for response.
browserHttpUserAgentstring
(optional)
The user agent string of the user agent.
citystring
(required)
Customer's city.
browserHttpAcceptstring
(optional)
Media type(s) that is(/are) acceptable for the response.
statestring (required)Customer's state.
zipcodestring
(required)
Customer's zip code.
customerFnamestring
(required)
Customer's first name.
address1string
(required)
Customer's address.
address2string
(optional)
Customer's address (additional info).
browserHttpAcceptEncodingstring (optional)List of acceptable encodings.
customerLnamestring
(required)
Customer's last name.
ipAddressstring
(required)
Customer's IP address.
phoneNumberstring
(optional)
Customer's phone number.
countrystring
(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"
}

PassThroughInfo

Elements of the passThroughInfo array represent custom paired information passed through to the transaction service.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
namestring
(required)
Custom passthrough value.
valuestring
(required)
Custom passthrough value.

PassThroughInfo Example

{
  "name": "value1",
  "value": "value2"
}

PaymentInfo

Payment information on the customer's payment card. Elements of the creditCardPaymentInfo array.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
creditCardPaymentInfoobject
(array)
Credit Card Payment Information.
creditCardPaymentInfo. cardNumstring
(required)
Card number.
creditCardPaymentInfo. expMonthstring
(required)
Card expiration month in mm format.
creditCardPaymentInfo. expYearstring
(required)
Card expiration year in yyyy format.
creditCardPaymentInfo. nameOnCardstring
(required)
Name as it appears on card.

PaymentInfo Example

{
  "creditCardPaymentInfo": {
    "cardNum": "4473707989493598",
    "expMonth": "04",
    "expYear": "2026",
    "nameOnCard": "Tyler Thomas"
  }
}

PaymentInfoWithCVV

Elements of the creditCardPaymentInfo array with CVV2 authentication.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
creditCardPaymentInfoobject
(array)
Credit Card Payment Information.
creditCardPaymentInfo. cardNumstring
(required)
Card number.
creditCardPaymentInfo. expMonthstring
(required)
Card expiration month in mm format.
creditCardPaymentInfo. expYearstring
(required)
Card expiration year in yyyy format.
creditCardPaymentInfo. nameOnCardstring
(required)
Name as it appears on card.
creditCardPaymentInfo. cvv2string
(required)
CVV2 code on the card.

PaymentInfoWithCVV Example

{
  "creditCardPaymentInfo": {
    "cardNum": "4473707989493598",
    "expMonth": "04",
    "expYear": "2026",
    "nameOnCard": "Tyler Thomas",
    "cvv2": "144"
  }
}

PaymentToken

These response parameters are received when a payment token is successfully created.

  • application/vnd.mcn.transaction-service.api.v.1+json
Resources
Parameters
PARAMETERTYPEDESCRIPTION
createdDatetimeDateTime-only
(required)
Date and Time of creation of the Payment Token.
timeToLiveinteger
(required)
Time for the token to exist.
originalPaymentTokenIdstring
(optional)
Reference to a previous Token Id.
validNumberOfUseinteger
(required)
The total number of times the Payment Token can be used for purchases.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
programParticipationIdinteger
(required)
The program connected to the Payment Token.
paymentTokenIdstring
(required)
Complex representation of Payment Token Id.
paymentInfoIdstring
(optional)
Information associated with the payment.
subscriptionIdinteger
(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"
}

PaymentTokenV2

These response parameters are received when a payment token is successfully created.

  • application/vnd.mcn.transaction-service.api.v.2+json
Resources
Parameters
PARAMETERTYPEDESCRIPTION
createdDatetimeDateTime-only
(required)
Date and Time of creation of the Payment Token.
timeToLiveinteger
(required)
Time for the token to exist.
originalPaymentTokenIdstring
(optional)
Reference to a previous Token Id.
validNumberOfUseinteger
(required)
The total number of times the Payment Token can be used for purchases.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
programParticipationIdinteger
(required)
The program connected to the Payment Token.
paymentTokenIdstring
(required)
Complex representation of Payment Token Id.
paymentInfoIdstring
(optional)
Information associated with the payment.
subscriptionIdstring
(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"
}

PaymentTokenVerify

These response parameters are received when a payment token is successfully created. Including CVV2 and AVS authentication results.

  • application/vnd.mcn.transaction-service.api.v.1+json
Resources
Parameters
PARAMETERTYPEDESCRIPTION
createdDatetimeDateTime-only
(required)
Date and Time of creation of the Payment Token.
timeToLiveinteger
(required)
Time for the token to exist.
originalPaymentTokenIdstring
(optional)
Reference to a previous Token Id.
validNumberOfUseinteger
(required)
The total number of times the Payment Token can be used for purchases.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
programParticipationIdinteger
(required)
The program connected to the Payment Token.
avsResponsestring
(required)
The result of AVS verification.
paymentTokenIdstring
(required)
Complex representation of Payment Token Id.
paymentInfoIdstring
(optional)
Information associated with the payment.
cvv2Responsestring
(required)
The result of CVV2 verification.
subscriptionIdinteger
(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"
}

PaymentTokenVerifyV2

These response parameters are received when a payment token is successfully created. Including CVV2 and AVS authentication results.

  • application/vnd.mcn.transaction-service.api.v.2+json
Resources
Parameters
PARAMETERTYPEDESCRIPTION
createdDatetimeDateTime-only
(required)
Date and Time of creation of the Payment Token.
timeToLiveinteger
(required)
Time for the token to exist.
originalPaymentTokenIdstring
(optional)
Reference to a previous Token Id.
validNumberOfUseinteger
(required)
The total number of times the Payment Token can be used for purchases.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
programParticipationIdinteger
(required)
The program connected to the Payment Token.
avsResponsestring
(required)
The result of AVS verification.
paymentTokenIdstring
(required)
Complex representation of Payment Token Id.
paymentInfoIdstring
(optional)
Information associated with the payment.
cvv2Responsestring
(required)
The result of CVV2 verification.
subscriptionIdstring
(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"
}

PaymentTokenTransaction

Resources
Parameters
PARAMETERTYPEDESCRIPTION
clientAccnuminteger
(required)
Merchant's CCBill account number.
clientSubaccinteger
(required)
Merchant's CCBill subaccount number.
subscriptionIdstring
(required)
An existing subscription ID number.

PaymentTokenTransaction Example

{
        "clientAccnum": 900112,
        "clientSubacc": 0002,
        "subscriptionId": "918166501000000981"
}

PaymentTokenMerchantOnlyParams

Parameters for creating a payment token without CVV2 and AVS authentication.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
customerInfoobject
(array)
Customer information.
customerInfo. emailstring
(required)
Customer's email address.
customerInfo. browserHttpAcceptLanguagestring
(optional)
List of acceptable human languages for response.
customerInfo. browserHttpUserAgentstring
(optional)
The user agent string of the user agent.
customerInfo. citystring
(required)
Customer's city.
customerInfo. browserHttpAcceptstring
(optional)
Media type(s) that is(/are) acceptable for the response.
customerInfo. statestring
(required)
Customer's state.
customerInfo. zipcodestring
(required)
Customer's zip code.
customerInfo. customerFnamestring
(required)
Customer's first name.
customerInfo. address1string
(required)
Customer's address.
customerInfo. address2string
(optional)
Customer's address (additional info).
customerInfo. browserHttpAcceptEncodingstring
(optional)
List of acceptable encodings.
customerInfo. customerLnamestring
(required)
Customer's last name.
customerInfo. ipAddressstring (required)Customer's IP address.
customerInfo. phoneNumberstring
(optional)
Customer's phone number.
customerInfo. countrystring
(required)
Customer's country.
paymentInfoobject
(array)
Payment information.
paymentInfo. cardNumstring
(required)
Card number.
paymentInfo. expMonthstring
(required)
Card expiration month in mm format.
paymentInfo. expYearstring
(required)
Card expiration year in yyyy format.
paymentInfo. nameOnCardstring
(required)
Name as it appears on the card.
subscriptionIdinteger
(required)
Transaction subscription identification number.
timeToLiveinteger
(optional)
Time for the token to exist.
validNumberOfUseinteger
(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
}

PaymentTokenMerchantOnlyVerifyParams

Parameters for creating a payment token that includes CVV2 and AVS authentication.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
customerInfoobject
(array)
Customer information.
customerInfo. emailstring
(required)
Customer's email address.
customerInfo. browserHttpAcceptLanguagestring
(optional)
List of acceptable human languages for response.
customerInfo. browserHttpUserAgentstring
(optional)
The user agent string of the user agent.
customerInfo. citystring
(required)
Customer's city.
customerInfo. browserHttpAcceptstring
(optional)
Media type(s) that is(/are) acceptable for the response.
customerInfo. statestring
(required)
Customer's state.
customerInfo. zipcodestring
(required)
Customer's zip code.
customerInfo. customerFnamestring
(required)
Customer's first name.
customerInfo. address1string
(required)
Customer's address.
customerInfo. address2string
(optional)
Customer's address (additional info).
customerInfo. browserHttpAcceptEncodingstring
(optional)
List of acceptable encodings.
customerInfo. customerLnamestring
(required)
Customer's last name.
customerInfo. ipAddressstring
(required)
Customer's IP address.
customerInfo. phoneNumberstring
(optional)
Customer's phone number.
customerInfo. countrystring
(required)
Customer's country.
paymentInfoobject
(array)
Payment information.
paymentInfo. cardNumstring
(required)
Card number.
paymentInfo. expMonthstring
(required)
Card expiration month in mm format.
paymentInfo. expYearstring
(required)
Card expiration year in yyyy format.
paymentInfo. nameOnCardstring
(required)
Name as it appears on card.
paymentInfo. cvv2string
(required)
CVV2 code on the card.
subscriptionIdinteger
(required)
Transaction subscription identification number.
timeToLiveinteger
(optional)
Time for the token to exist.
validNumberOfUseinteger
(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

PaymentTokenProgramSpecifiedParams

Parameters for generating payment tokens for cross-sale opportunities with other specified program participants (merchants).

Resources
Parameters
PARAMETERTYPEDESCRIPTION
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
customerInfoobject
(array)
Customer information.
customerInfo. emailstring
(required)
Customer's email address.
customerInfo. browserHttpAcceptLanguagestring
(optional)
List of acceptable human languages for the response.
customerInfo. browserHttpUserAgentstring
(optional)
The user agent string of the user agent.
customerInfo. citystring
(required)
Customer's city.
customerInfo. browserHttpAcceptstring
(optional)
Media type(s) that is(/are) acceptable for the response.
customerInfo. statestring
(required)
Customer's state.
customerInfo. zipcodestring
(required)
Customer's zip code.
customerInfo. customerFnamestring
(required)
Customer's first name.
customerInfo. address1string
(required)
Customer's address.
customerInfo. address2string
(optional)
Customer's address (additional info).
customerInfo. browserHttpAcceptEncodingstring
(optional)
List of acceptable encodings.
customerInfo. customerLnamestring
(required)
Customer's last name.
customerInfo. ipAddressstring
(required)
Customer's IP address.
customerInfo. phoneNumberstring
(optional)
Customer's phone number.
customerInfo. countrystring
(required)
Customer's country.
paymentInfoobject
(array)
Payment information.
paymentInfo. cardNumstring
(required)
Card number.
paymentInfo. expMonthstring
(required)
Card expiration month in mm format.
paymentInfo. expYearstring
(required)
Card expiration year in yyyy format.
paymentInfo. nameOnCardstring
(required)
Name as it appears on the card.
subscriptionIdinteger
(required)
Transaction subscription identification number.
programParticipationIdinteger
(required)
The identifier represents the program associated with the transaction.
timeToLiveinteger
(optional)
Time for the token to exist.
validNumberOfUseinteger
(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

PaymentTokenTargetClientParams

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.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
customerInfoobject
(array)
Customer information.
customerInfo. emailstring
(required)
Customer's email address.
customerInfo. browserHttpAcceptLanguagestring
(optional)
List of acceptable human languages for the response.
customerInfo. browserHttpUserAgentstring
(optional)
The user agent string of the user agent.
customerInfo. citystring
(required)
Customer's city.
customerInfo. browserHttpAcceptstring
(optional)
Media type(s) that is(/are) acceptable for the response.
customerInfo. statestring
(required)
Customer's state.
customerInfo. zipcodestring
(required)
Customer's zip code.
customerInfo. customerFnamestring
(required)
Customer's first name.
customerInfo. address1string
(required)
Customer's address.
customerInfo. address2string
(optional)
Customer's address (additional info).
customerInfo. browserHttpAcceptEncodingstring
(optional)
List of acceptable encodings.
customerInfo. customerLnamestring
(required)
Customer's last name.
customerInfo. ipAddressstring
(required)
Customer's IP address.
customerInfo. phoneNumberstring
(optional)
Customer's phone number.
customerInfo. countrystring
(required)
Customer's country.
paymentInfoobject
(array)
Payment information.
paymentInfo. cardNumstring
(required)
Card number.
paymentInfo. expMonthstring
(required)
Card expiration month in mm format.
paymentInfo. expYearstring
(required)
Card expiration year in yyyy format.
paymentInfo. nameOnCardstring
(required)
Name as it appears on card.
subscriptionIdinteger
(required)
Transaction subscription identification number.
targetClientAccnuminteger
(required)
Target merchant account number.
targetClientSubaccinteger
(required)
Target merchant subaccount number.
timeToLiveinteger
(optional)
Time for the token to exist.
validNumberOfUseinteger
(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
}

TransactionInfo

Response parameters confirm that a customer was successfully charged using a payment token.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
errorCodeinteger
(required)
Error condition value of the transaction.
approvedboolean
(required)
Approval status of the transaction.
paymentUniqueIdstring
(required)
Unique key connected to payment account.
sessionIdstring
(required)
Unique session ID value for transaction.
subscriptionIdinteger
(required)
Subscription ID to which the transaction belongs.
newPaymentTokenIdstring
(required)
New payment token for subsequent transactions.

TransactionInfo Example

{
	"errorCode": 200,
	"approved": true,
	"paymentUniqueId": "53104f5a54d3d43254def41c29aedba8",
	"sessionId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
	"subscriptionId": 900000000000000001,
	"newPaymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
}

TransactionRequest

Request parameters for initiating a transaction request for a customer.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
createNewPaymentTokenboolean
(true/false)
Return new payment token for subsequent transactions or not.
initialPricenumber
(required)
Price of the initial transaction.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
lifeTimeSubscriptionboolean
(optional)
Subscription is valid during the website's lifetime.
initialPeriodinteger
(required)
The time period of the initial transaction
recurringPeriodinteger
(optional)
The time period of recurrent transactions.
currencyCodestring
(optional)
Numerical representation of the currency used in the transaction.
rebillsinteger
(optional)
The number of times recurrent transactions can occur.
recurringPricenumber
(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"
		}
	]
}

ThreedsTransactionRequest

Parameters for initiating a charge with 3DS authentication.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
createNewPaymentTokenboolean
(optional)
Return new payment token for subsequent transactions or not.
clientAccnuminteger
(required)
Merchant account number.
clientSubaccinteger
(required)
Merchant subaccount number.
initialPricefloat
(required)
Initial transaction price.
initialPeriodinteger
(required)
The length (in days) of the initial billing period.
currencyCodestring
(optional)
Three-digit currency code (ISO 4217 standard) for the currency used in the transaction.
recurringPricefloat
(optional)
The amount the consumer will be charged for each recurring bill.
recurringPeriodinteger
(optional)
The length of time between rebills.
rebillsinteger
(optional)
The total number of times the subscription will rebill.
lifeTimeSubscriptionboolean
(optional)
The presence of this variable with a value of 1 indicates that the transaction is a lifetime subscription.
createNewPaymentTokenboolean
(optional)
Return new payment token for subsequent transactions or not.
passThroughInfoArray[any]
(optional)
Paired information being passed through to the transaction service.
threedsCardTokenstring
(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
threedsEcistring
(required)
An Electronic Commerce Indicator (ECI).
Values: '0', '1', '2', '5', '6', or '7'.
threedsStatusstring
(required)
The status of the 3DS verification ('Y', 'N', 'A', etc.)
threedsVersionstring
(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
threedsXidstring
(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
threedsCavvstring
(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
threedsCavvAlgorithmstring
(optional/required)
CAVV Algorithm for threeds request. The threedsCavvAlgorithm parameter is required for threedsVersion 1.0.2
threedsDsTransIdstring
(optional/required)
Directory Server Transaction ID. The threedsDsTransId parameter is required for threedsVersion 2.1.0
threedsAcsTransIdstring
(optional/required)
Access Control Server Transaction ID. The threedsAcsTransId parameter is required for threedsVersion 2.1.0
threedsSdkTransIdstring
(optional)
The 3DS vendor's transaction ID.
threedsAuthenticationTypestring
(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).
threedsAuthenticationValuestring
(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).
threedsClientTransactionIdstring
(required)
The parameter is automatically generated by the Advanced Widget. Its purpose is to identify the origin of the 3DS authentication transaction.
threedsSuccessboolean
(required)
Verification of 3DS authentication success or failure.
threedsAmountinteger
(optional)
The amount to be charged (same as initialPrice).
threedsCurrencyinteger
(optional)
The 3-digit currency code for the currency to be used in this transaction.
Example value: 840
threedsErrorstring
(optional/required)
Error received from the 3DS vendor during the strong customer authentication process. The parameter is required if no threedsVersion is provided.
threedsErrorDetailstring
(optional)
Error details related to the threedsError.
threedsErrorCodestring
(optional)
Error code.
threedsResponsestring
(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": ""
}

ThreeDSRequired

Response parameters after 3DS authentication request.

Resources
Parameters
PARAMETERTYPEDESCRIPTION
requiredboolean
(true/false)
3DS required for payment card.
amountnumberAuthorized charge amount.

ThreeDSRequired Example

{
  "required": "true",
  "amount": "1.0"
}

CVV2 Verification Responses

VALUEDESCRIPTION
MCVV2/CVC2/CID Match
NCVV2/CVC2/CID No Match
PNot Processed
SThe CVV2/CVC2/CID should be on the card, but the merchant indicates it is not.
UThe Issuer is not certified or has not provided Visa with encryption keys.

AVS Responses

VALUEDESCRIPTION
AThe street addresses match but the postal/ZIP code does not, or the request does not include the postal/ZIP code.
BStreet addresses match. The postal code is not verified due to incompatible formats (both street address and postal code were sent.)
CThe street address and postal code not verified due to incompatible formats. (both street address and postal code were sent)
DStreet addresses and postal codes match
FStreet address and postal code match. (U.K.- issued cards)
GIssuer 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.
OAddress information is not verified.
MStreet address and postal code match.
NNo 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.
PPostal codes match. Postal code and street address were sent, but street address not verified due to incompatible formats.
RRetry; System unavailable or timed out.
SAVS currently not supported
UNo data from Issuer/Authorization platform
VNine character postal code matches; address does not match
XNine character postal code and address match
YStreet address and postal code match
ZPostal/ZIP matches, street address does not match, or street address not included in request.
1Cardholder name and ZIP match
2Cardholder name, address, and ZIP match
3Cardholder name and address match
4Cardholder name matches
5Cardholder name incorrect, ZIP matches
6Cardholder name incorrect; address and ZIP match
7Cardholder name incorrect, address matches
8Cardholder 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"
}