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	integer (optional)	Numerical representation of the currency used in the transaction.
rebills	integer (optional)	The number of times recurrent transactions can occur.
recurringPrice	number (optional)	Price of recurrent transactions.
passThroughInfo	array (optional)	Paired Information Passed Through to the Transaction Service.

TransactionRequest Example

{
    "clientAccnum":900123,
    "clientSubacc":0010,
    "initialPrice": 9.99,
	"initialPeriod": 10,
	"recurringPrice": 15.00,
	"recurringPeriod": 30,
	"rebills": 99,
	"currencyCode": 840,
	"lifeTimeSubscription": false,
    "createNewPaymentToken": false,
	"passThroughInfo": [
		{
			"name": "val1",
			"value": "val2"
		}
	]
}

ThreedsTransactionRequest

Parameters for initiating a charge with 3DS authentication.

Resources

/transactions/payment-tokens/threeds/{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	integer (optional)	Numerical representation of the currency used in the transaction.
rebills	integer (optional)	The number of times recurrent transactions can occur.
recurringPrice	number (optional)	Price of recurrent transactions.
passThroughInfo	array (optional)	Paired Information Passed Through to the Transaction Service.
threeedsXid	string (optional)	XID for threeds request.
threedsVersion	string (optional)	The version number for threeds request.
threedsSuccess	boolean (optional)	Success for threeds request.
threedsAmount	integer (optional)	Amount for threeds request.
threedsEci	string (required)	ECI for threeds request.
threedsCavv	string (required)	CAVV for threeds request.
threedsCavvAlgorithm	string (optional)	CAVV Algorithm for threeds request.
threedsId	string (optional)	Id for threeds request.
threedsStatus	string (optional)	Status for threeds request.
threedsTransactionId	string (optional)	Transaction Id for threeds request.
threedsError	string (optional)	Error for threeds request.

ThreedsTransactionRequest Example

{
    "clientAccnum":900123,
    "clientSubacc":0010,
    "initialPrice": 9.99,
	"initialPeriod": 10,
	"recurringPrice": 15.00,
	"recurringPeriod": 30,
	"rebills": 99,
	"currencyCode": 840,
	"lifeTimeSubscription": false,
    "createNewPaymentToken": false,
	"passThroughInfo": [
		{
			"name": "val1",
			"value": "val2"
		}
	],
	"threedsCavv": "cGFzc3dvcmQxMjM0NTZwYXNzd28=",
	"threedsCavvAlgorithm": "3",
	"threedsEci": "05",
	"threedsError": "",
	"threedsTransactionId": "id-7kzs4vel57n",
	"threedsId": "id-7kzs4vel57n",
	"threedsStatus": "Y",
	"threedsSuccess": true,
	"threedsVersion": "1.0.2",
	"threedsXid": "123",
	"threedsAmount": "999"
}

ThreeDSRequired

Require 3DS authentication for card payment.

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