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.
currencyCodeinteger
(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
(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.
currencyCodeinteger
(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.
threeedsXidstring
(optional)
XID for threeds request.
threedsVersionstring
(optional)
The version number for threeds request.
threedsSuccessboolean
(optional)
Success for threeds request.
threedsAmountinteger
(optional)
Amount for threeds request.
threedsEcistring
(required)
ECI for threeds request.
threedsCavvstring
(required)
CAVV for threeds request.
threedsCavvAlgorithmstring
(optional)
CAVV Algorithm for threeds request.
threedsIdstring
(optional)
Id for threeds request.
threedsStatusstring
(optional)
Status for threeds request.
threedsTransactionIdstring
(optional)
Transaction Id for threeds request.
threedsErrorstring
(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
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"
}