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.

PARAMETER	TYPE	DESCRIPTION
field	string (required)	The field in error.
message	string (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 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.

Resources

Parameters

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"
}

CreditCardPaymentInfo

Elements of the paymentinfo array.

Resources

Parameters

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"
}

CreditCardWithCvvPaymentInfo

Elements of the paymentinfo array with CVV2 authentication.

Resources

/payment-tokens/merchant-only-verify

Parameters

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"
}

CustomerInfo

Elements of the customerInfo array.

Resources

Parameters

PARAMETER	TYPE	DESCRIPTION
email	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"
}

PassThroughInfo

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

Resources

Parameters

PARAMETER	TYPE	DESCRIPTION
name	string (required)	Custom passthrough value.
value	string (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

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"
  }
}

PaymentInfoWithCVV

Elements of the creditCardPaymentInfo array with CVV2 authentication.

Resources

/payment-tokens/merchant-only-verify

Parameters

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"
  }
}

PaymentToken

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

application/vnd.mcn.transaction-service.api.v.1+json

Resources

Parameters

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"
}

PaymentTokenV2

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

application/vnd.mcn.transaction-service.api.v.2+json

Resources

Parameters

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"
}

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

/payment-tokens/merchant-only-verify

Parameters

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"
}

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

/payment-tokens/merchant-only-verify

Parameters

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"
}

PaymentTokenTransaction

Resources

/transactions/payment-tokens/{payment_token_id}

Parameters

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"
}

PaymentTokenMerchantOnlyParams

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

Resources

/payment-tokens/merchant-only

Parameters

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
}

PaymentTokenMerchantOnlyVerifyParams

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

Resources

/payment-tokens/merchant-only-verify

Parameters

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
}

PaymentTokenProgramSpecifiedParams

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

Resources

/payment-tokens/program-specified

Parameters

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
}

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

/payment-tokens/target-client

Parameters

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
}

TransactionInfo

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

Resources

Parameters

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"
}

TransactionRequest

Request parameters for initiating a transaction request for a customer.

Resources

/transactions/payment-tokens/{payment_token_id}

Parameters

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"
		}
	]
}

ThreedsTransactionRequest

Parameters for initiating a charge with 3DS authentication.

Resources

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

Parameters

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": ""
}

ThreeDSRequired

Response parameters after 3DS authentication request.

Resources

Parameters

PARAMETER	TYPE	DESCRIPTION
required	boolean (true/false)	3DS required for payment card.
amount	number	Authorized charge amount.

ThreeDSRequired Example

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

CVV2 Verification Responses

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.

AVS Responses

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"
}