CCBill RESTful Transaction API

API Version: 1.0.0.3
Release Date: July 2018

Introduction

The CCBill RESTful Transaction API is an enhancement to the CCBill Payment Platform that allows Merchants more control over their customers' purchase flow while offering additional customization options as you don’t need to use CCBill hosted payment forms.

Scope

This document outlines the API resources and endpoints of the CCBill Transaction REST API service. Merchants can use these resources to charge consumers with a payment token. This instructional document is provided as a technical resource to CCBill Merchants. It is intended to be read by programmers, technicians, and others with advanced coding skills.

Requirements & Terminology

The CCBill Transaction API service is considered to be an Advanced Feature. As such, this document assumes the following:

• The user has already enabled SMS.
• The user possesses intermediate to advanced programming skills.
• User has experience with HTTP/1.1.
• User has experience with RESTful Web Services.
• User has experience with JSON formats.
• The RESTful Transaction API supports TLS 1.2 only.

Terminology

• Merchant Account. Merchant's account number. Each CCBill merchant receives an account number for tracking purposes. The standard format is 9xxxxx-xxxx, where 9xxxxx is the main account. The main account is a six (6) digit number.
  For example: "999999".
• Merchant Sub-account. CCBill Merchants may open one or more sub-accounts. The sub-account is a four (4) digit number. The standard format is: xxxx. For example: "1234". The sub-account is part of the main account.
• API Account. The API Account is also referred to as "Datalink Extract".
• Payment Token. A Payment Token identifies a billable entity within the system.

Data Link API Account

CCBill’s RESTful Transaction API uses the DataLink Extract System. You can contact our Merchant Support Department at MerchantSupport@ccbill.com to have this enabled.

Subscription Management System

CCBill's RESTful Transaction API uses CCBill’s Subscription Management System and can be used with the Charge by Previous Transaction ID functionality.

The CCBill RESTful Transaction API enables Merchants to create $0 authorizations by using an API request that would return a subscription ID which can be used in a standard chargeByPrevious request.

Velocity Controls

CCBill Velocity Controls is an advanced feature of SMS, and it enables you to limit customer transactions by the number of transactions and/or by cash amount of transactions within a specific time-frame. This means that you can set the number of transactions for a specific customer within a given period of time.

Rules apply to all payment types and can be implemented on a single subaccount or across all subaccounts. When applied, each customer is assigned a unique ID based on their financial information and security background. By setting up CCBill Velocity Controls, you limit the chances of fraud and, on an individual basis, you allow good loyal customers to continue to make purchases beyond the established limits.

If you are interested in this advanced feature, please contact merchantsupport@ccbill.com to set up velocity controls according to your business requirements.

CCBill Transaction API Objects

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

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.

Your application will need to gain a bearer token before it can access the API. This is further discussed in the Authentication and Authorization section of this document.

CreditCardPaymentInfo

Type CreditCardPaymentInfo

{
  "cardNum": "string",
  "expDate": "string",
  "nameOnCard": "string"
}

PARAMETER	TYPE	DESCRIPTION
cardNum (required)	string	Card number
expDate (required)	string	Card expiration date
nameOnCard (required)	string	Name as it appears on consumer's credit card

CustomerInfo

Type CustomerInfo

{
  "email": "string",
  "browserHttpAcceptLanguage": "string",
  "browserHttpUserAgent": "string",
  "city": "string",
  "browserHttpAccept": "string",
  "state": "string",
  "zipcode": "string",
  "customerFname": "string",
  "address1": "string",
  "address2": "string",
  "browserHttpAcceptEncoding": "string",
  "customerLname": "string",
  "ipAddress": "string",
  "phoneNumber": "string",
  "country": "string"
}

PARAMETER	TYPE	DESCRIPTION
email (required)	string	Customer's email address
browserHttpAcceptLanguage	string	List of acceptable human languages for response
browserHttpUserAgent	string	The user agent string of the user agent
city	string	Customer's city
browserHttpAccept	string	Media type(s) that is(/are) acceptable for the response
state (required)	string	Customer's state
zipcode (required)	string	Customer's zip code
customerFname (required)	string	Customer's first name
address1	string	Customer's address
address2	string	Customer's address (additional info)
browserHttpAcceptEncoding	string	List of acceptable encodings
customerLname (required)	string	Customer's last name
ipAddress (required)	string	Customer's IP address
phoneNumber	string	Customer's phone number
country (required)	string	Customer's country

PassThroughEntry

Type PassThroughEntry

{
  "name": "string",
  "value": "string"
}

PARAMETER	TYPE	DESCRIPTION
name (required)	string
value (required)	string

PaymentInfo

Type PaymentInfo

{
  "creditCardPaymentInfo": {
    "cardNum": "string",
    "expDate": "string",
    "nameOnCard": "string"
  }
}

PARAMETER	TYPE	DESCRIPTION
creditCardPaymentInfo	creditCardPaymentInfo	Credit card payment information
creditCardPaymentInfo. cardNum (required)	string	Credit card number
creditCardPaymentInfo. expDate (required)	string	Credit card expiration date
creditCardPaymentInfo. nameOnCard (required)	string	Name as it appears on credit card

PaymentToken

Type PaymentToken

{
  "createdDatetime": "datetime-only",
  "timeToLive": "integer",
  "originalPaymentTokenId": "string",
  "validNumberOfUse": "integer",
  "clientAccnum": "integer",
  "clientSubacc": "integer",
  "programParticipationId": "integer",
  "paymentTokenId": "string",
  "paymentInfoId": "string",
  "subscriptionId": "integer"
}

PARAMETER	TYPE	DESCRIPTION
createdDatetime (required)	datetime-only	Date and uime of creation of the Payment Token.
timeToLive (required)	integer	Time for the token to exist expressed in hours
originalPaymentTokenId	string	Reference to a previous Token Id
validNumberOfUse (required)	integer	Total number of times the Payment Token can be used for purchases
clientAccnum (required)	integer	Merchant account number
clientSubacc (required)	integer	Merchant subaccount number
programParticipationId (required)	integer	The Program connected to the Payment Token
paymentTokenId (required)	string	Complex representation of Payment Token Id
paymentInfoId	string	Information associated with the payment
subscriptionId (required)	integer	Identification of the subscription associated with the transaction

PaymentTokenMerchantOnlyParams

Type

{
  "clientAccnum": "integer",
  "clientSubacc": "integer",
  "customerInfo": {
    "email": "string",
    "browserHttpAcceptLanguage": "string",
    "browserHttpUserAgent": "string",
    "city": "string",
    "browserHttpAccept": "string",
    "state": "string",
    "zipcode": "string",
    "customerFname": "string",
    "address1": "string",
    "address2": "string",
    "browserHttpAcceptEncoding": "string",
    "customerLname": "string",
    "ipAddress": "string",
    "phoneNumber": "string",
    "country": "string"
  },
  "paymentInfo": {
    "creditCardPaymentInfo": {
      "cardNum": "string",
      "expDate": "string",
      "nameOnCard": "string"
    }
  },
  "subscriptionId": "integer",
  "timeToLive": "integer",
  "validNumberOfUse": "integer"
}

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"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",
			"expDate": "201904"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}

PARAMETER	TYPE	DESCRIPTION
clientAccnum (required)	integerMerchant account number
clientSubacc (required)	integer	Merchant subaccount number
customerInfo	customerInfo	Customer Information
customerInfo. email (required)	string	Customer's email address
customerInfo. browserHttpAcceptLanguage	string	List of acceptable human languages for response
customerInfo. browserHttpUserAgent	string	The user agent string of the user agent
customerInfo. city	string	Customer's city
customerInfo. browserHttpAccept	string	Media type(s) that is(/are) acceptable for the response
customerInfo. state(required)	string	Customer's state
customerInfo. zipcode (required)	string	Customer's zip code
customerInfo. customerFname (required)	string	Customer's first name
customerInfo. address1	string	Customer's address
customerInfo. address2	string	Customer's address (additional info)
customerInfo. browserHttpAcceptEncoding	string	List of acceptable encodings
customerInfo. customerLname (required)	string	Customer's last name
customerInfo. ipAddress (required)	string	Customer's IP address
customerInfo. phoneNumber	string	Customer's phone number
customerInfo. country (required)	string	Customer's country
paymentInfo	paymentInfo	Payment Information
paymentInfo. cardNum (required)	string	Card number
paymentInfo. expDate (required)	string	Card expiration date
paymentInfo. nameOnCard (required)	string	Name as it appears on card
subscriptionId	integer	Transaction subscription identification number
timeToLive	integer	Time for the token to exist expressed in hours
validNumberOfUse	integer	Total number of times the Payment Token can be used for purchases

TransactionInfo

Type TransactionInfo

{
  "errorCode": "integer",
  "approved": "boolean",
  "paymentUniqueId": "string",
  "sessionId": "string",
  "subscriptionId": "integer",
  "newPaymentTokenId": "string"
}

Example

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

PARAMETER	TYPE	DESCRIPTION
errorCode (required)	integer	Error condition value of the transaction
approved (required)	boolean	Approval status of the transaction
paymentUniqueId (required)	string	Unique key connected to a payment account
sessionId (required)	string	Unique session ID value for transaction
subscriptionId (required)	integer	subscription ID to which the transaction belongs
newPaymentTokenId (required)	string	New payment token for subsequent transactions

TransactionRequest

Type TransactionRequest

{
  "createNewPaymentToken": "boolean",
  "initialPrice": "number",
  "clientAccnum": "integer",
  "clientSubacc": "integer",
  "lifeTimeSubscription": "boolean",
  "initialPeriod": "integer",
  "recurringPeriod": "integer",
  "currencyCode": "integer",
  "rebills": "integer",
  "recurringPrice": "number",
  "passThroughInfo": [
    "any"
  ]
}

Example

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

PARAMETER	TYPE	DESCRIPTION
CreateNewPaymentToken	boolean	Return a new payment token for subsequent transactions or not
initialPrice (required)	number	Price of the initial transaction
clientAccnum (required)	integer	Client account of the merchant
clientSubacc (required)	integer	Client subaccount of the merchant
lifeTimeSubscription	boolean	A continual subscription with no end date or not
initialPeriod (required)	integer	Time period of the initial transaction
recurringPeriod	integer	Time period of recurring transactions
currencyCode	integer	A numerical representation of the currency used in transaction
rebills	integer	The number of times recurrent transactions can occur
recurringPrice	number	Price of recurrent transactions
passThroughInfo	Array[any]	Paired Information Passed Through to the Transaction Service

ValidationError

Type ValidationError

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

PARAMETER	TYPE	DESCRIPTION
field (required)	string	Field in error
message (required)	string	User-friendly message

Error

Type Error

{
  "id": "string",
  "url": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "generalMessage": "string",
  "errorCode": "string",
  "timestamp": "datetime"
}

PARAMETER	TYPE	DESCRIPTION
id (required)	string	Randomly generated GUID. Validation pattern: ^[a-zA-Z0-9-]*$ Example: "62432dd8-97d9-400a-8da8-4a5c1951f935"
url (required)	string	The RELATIVE URL that has caused this error. Example: "/programs/123"
errors	ValidationError[object]	Optional, only returned on 400 Bad Request errors for validation errors
errors. field (required)	string	Field in error
errors. message (required)	string	Descriptional message
generalMessage (required)	string	A human-readable message
errorCode (required)	string	Product defined error code. Validation pattern: ^[0-9-]*$
timestamp (required)	datetime	Timestamp of the call

API Endpoints

With each POST request, please supply the myme type of the body of the request as a header. For futher details, please see example below:

HEADER NAME	CONTENT-TYPE
Content-Type	application/json

All endpoints are rooted in https://api.ccbill.com/

Authentication and Authorization

The CCBill RESTful Transaction API uses bearer token-based authentication and authorization. Prior to accessing the API, you need to register your application with CCBill. Upon registration, your app will be assigned a merchant application ID and secret key. Use these credentials to generate a token by providing them to the authorization server.

Authorization Server: https://api.ccbill.com/ccbill-auth/oauth/token

See curl example below:

curl -X POST 
\
 'https://api.ccbill.com/ccbill-auth/oauth/token' 
\
    -i -u 'MERCHANT_APPLICATION_ID:APPLICATION_SECRET' 
\
    -H 'Content-Type: application/x-www-form-urlencoded' 
\
    -d 'grant_type=client_credentials'

Once you have generated an access token (not to be confused with a payment token), provide it in the Authorization header of each API request. You will have access until the access token expires or is revoked. The acquired token is a random string of data that does not hold any important piece of information or has value on its own. It works only as an authentication and authorization tool and grants access to an application.

If the authorization token isn't authenticated correctly, you will either receive a 401 or 403 response code.

Use Case -Create a Token with Payment and Customer Information by Creating $0 Subscriptions

To successfully create a payment token with payment and customer information by creating $0 subscriptions, you need to:

1. Gather credit card and customer information.
2. Create a payment token by submitting payment and customer info (such as credit card number, exp. date, name on card, etc.) as an API request to the /payment-tokens endpoint.
3. You can create two types of tokens:
   • Token with limited usage. This type of token is valid only for a specified number of uses after which it expires.
   • Token without an expiration. Tokens do not expire if you do not define the validNumberOfUse and timeToLive parameters. Non-expiring tokens are a great resource to use with chargeByPrevious API requests.
4. Submit a $0 auth and receive a CCBill subscription ID.
5. Charge a customer with a chargeByPrevious API request. Set up your own rules by which the system determines whether to decline or complete the transaction.

The example below illustrates the parameters necessary to create a token with payment and customer information by creating $0 subscriptions.

{
"clientAccnum": 900003,
"clientSubacc": 1234,
"subscriptionId": 0,
"timeToLive": 30,
"customerInfo": {
      "customerFname" : "Charlie",
      "customerLname" : "Test",
      "address1" : "1501 W 17th St",
      "city" : "Tempe",
      "state" : "AZ",
      "zipcode" : "85281",
      "country" : "US",
      "phoneNumber" : "602-111-2222",
      "email" : "ccbill@email.com",
      "ipAddress" : "64.39.194.13"
},
"paymentInfo" : {
      "creditCardPaymentInfo" : {
             "cardNum" : "5105105105105100",
             "nameOnCard" : "Charlie Test",
             "expDate" : "122020"
      }
}

CVV2 and AVS Verification

Your account will need to be configured for the CVV2 and AVS verification for $0 subscription.

Below is the 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"
}

CVV2 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 matches but the postal/ZIP code does not, or the request does not include the postal/ZIP code.
B	Street addresses match. Postal code is not verified due to incompatible formats (both street address and postal code were sent.)
C	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

/payment-tokens Endpoint

Charge consumers by using payment tokens. Use the /payment-tokens endpoint to create a token that identifies a user in the system. The token can be passed on to the system in a transaction request, thus enabling you to bill a customer.

SUB-RESOURCES	METHODS	DESCRIPTION
/payment-tokens/merchant-only	POST	Resource used for creating payment tokens that are not tied to a specific Merchant Connect Program
/payment-tokens/merchant-only-verify	POST	Resource used for creating payment tokens with CVV2 and AVS verification

/payment-tokens/merchant-only

Resource used for creating a payment token.

Headers

PARAMETER	TYPE	DESCRIPTION
Accept (required)	string	API version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json

Body

Type PaymentTokenMerchantOnlyParams

{
  "clientAccnum": "integer",
  "clientSubacc": "integer",
  "customerInfo": {
    "email": "string",
    "browserHttpAcceptLanguage": "string",
    "browserHttpUserAgent": "string",
    "city": "string",
    "browserHttpAccept": "string",
    "state": "string",
    "zipcode": "string",
    "customerFname": "string",
    "address1": "string",
    "address2": "string",
    "browserHttpAcceptEncoding": "string",
    "customerLname": "string",
    "ipAddress": "string",
    "phoneNumber": "string",
    "country": "string"
  },
  "paymentInfo": {
    "creditCardPaymentInfo": {
      "cardNum": "string",
      "expDate": "string",
      "nameOnCard": "string"
    }
  },
  "subscriptionId": "integer",
  "timeToLive": "integer",
  "validNumberOfUse": "integer"
}

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"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",
			"expDate": "201904"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}

PARAMETER	TYPE	DESCRIPTION
programId (required)	integer	The ID of the program. Example value: 123
participantAccount (required)	string	The account number of the participant/affiliate merchant. The value is comprised of the account and subaccount separated by a dash. Example value: 900000-1234

Result Format

/payment-tokens/merchant-only-verify

The resource is used to enhance authentication during the payment token creation. This endpoint includes cvvResponse and avsResponse parameters in the response. These parameters help in reducing the chargeback ratios for merchants.

Headers

PARAMETER	TYPE	DESCRIPTION
Accept (required)	string	API version. Example value: application/vnd.mcn.transaction-service.api.v.1+json, application/vnd.mcn.transaction-service.api.v.2+json

Body

Type PaymentTokenMerchantOnlyVerifyParams

{
  "clientAccnum": "integer",
  "clientSubacc": "integer",
  "customerInfo": {
    "email": "string",
    "browserHttpAcceptLanguage": "string",
    "browserHttpUserAgent": "string",
    "city": "string",
    "browserHttpAccept": "string",
    "state": "string",
    "zipcode": "string",
    "customerFname": "string",
    "address1": "string",
    "address2": "string",
    "browserHttpAcceptEncoding": "string",
    "customerLname": "string",
    "ipAddress": "string",
    "phoneNumber": "string",
    "country": "string"
  },
  "paymentInfo": {
    "creditCardPaymentInfo": {
      "cardNum": "string",
      "nameOnCard": "string",
      "expMonth": "string",
      "expYear": "string",
      "cvv2": "string"
    }
  },
  "subscriptionId": "integer",
  "timeToLive": "integer",
  "validNumberOfUse": "integer"
}

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"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": "2019",
			"cvv2": "123"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}

PARAMETER	TYPE	DESCRIPTION
programId (required)	integer	The ID of the program. Example value: 123
participantAccount (required)	string	The account number of the participant/affiliate merchant. The value is comprised of the account and subaccount separated by a dash. Example value: 900000-1234

Result Format

/payment-tokens/{paymentTokenId}

Use this request to retrieve details of a Payment Token based on its ID.

Parameters

PARAMETER	TYPE	DESCRIPTION
paymentTokenId (required)	string

Headers

PARAMETER	TYPE	DESCRIPTION
Accept (required)	string	API version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json

Result Format

/transactions Endpoint

Use the Transactions endpoint to create a charge for an existing or NEW customer, or to retrieve data on a charge. A charge represents a transaction on a customer's billing details by a sponsor, based on a token obtained from an affiliate which identifies one of their clients.

SUB-RESOURCES	METHODS	DESCRIPTION
/transactions/payment-tokens/{payment_token_id}	GET & POST	Subresource used to bill a client, or retrieve details about a charge.

Use the POST /transactions/payment-tokens/{payment_token_id} API call to bill a customer, and the GET /transactions/payment-tokens/{payment_token_id} API call to retrieve details about a charge that was made in the system.

/transactions/payment-tokens/{payment_token_id}

The POST /transactions/payment-tokens/{payment_token_id} API call will create a transaction request for a customer. The customer is identified by a token that is obtained from an affiliate. If the token is short lived, and this is the first billing for this customer a longer lived token is returned.

Supply the payment token ID as a URI parameter.

Parameters

PARAMETER	TYPE	DESCRIPTION
payment_token_id (required)	string	The payment token ID.

Header

PARAMETER	TYPE	DESCRIPTION
Accept (required)	string	API version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json

Body

Type TransactionRequest

{
  "createNewPaymentToken": "boolean",
  "initialPrice": "number",
  "clientAccnum": "integer",
  "clientSubacc": "integer",
  "lifeTimeSubscription": "boolean",
  "initialPeriod": "integer",
  "recurringPeriod": "integer",
  "currencyCode": "integer",
  "rebills": "integer",
  "recurringPrice": "number",
  "passThroughInfo": [
    "any"
  ]
}

Example

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

PARAMETER	TYPE	DESCRIPTION
createNewPaymentToken	boolean	return new payment token for subsequent transactions or not
initialPrice (required)	number	price of initial transaction
clientAccnum (required)	integer	clientAccnum of the merchant
clientSubacc(required)	integer	clientSubacc of the merchant
lifeTimeSubscription	boolean	subscription is eternal or not.
initialPeriod(required)	integer	time period of initial transaction
recurringPeriod	integer	time period of recurrent transactions
currencyCode	integer	numerical representation of the currency used in a transaction
rebills	integer	number of times recurrent transactions can occur
recurringPrice	number	price of recurrent transactions
passThroughInfo	Array[any]	Paired Information Passed Through to the Transaction Service

Result Format

/transactions/payment-tokens/{payment_token_id}

Use this API call to obtain data on a previously made charge. You will need to identify the charge by the ID.

Supply the payment token ID as a URI parameter.

Parameters

PARAMETER	TYPE	DESCRIPTION
payment_token_id (required)	string	The payment token ID.

Headers

PARAMETER	TYPE	DESCRIPTION
Accept (required)	string	API version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json

Result Value

CCBill RESTful API Error Codes

HTTP Status Code	HTTP Status Type	Error Code	Error Message
400	Bad Request	100100	Invalid client account
400	Bad Request	100102	Expired payment token.
400	Bad Request	100105	Invalid payout type.
400	Bad Request	100106	Invalid privacy type.
400	Bad Request	100107	Invalid program category.
400	Bad Request	100108	Invalid payment type.
400	Bad Request	100109	Invalid program participation.
400	Bad Request	200000	Problem with attribute size.
400	Bad Request	200000	Attribute required.
400	Bad Request	200000	Problem with the attribute values.
400	Bad Request	200000	Invalid credit card number.
400	Bad Request	200000	Invalid email address.
400	Bad Request	200000	Invalid Client Accnum.
400	Bad Request	200000	Invalid Client Subacc.
400	Bad Request	200000	Invalid Subscription ID.
400	Bad Request	200000	Invalid Target Client Accnum.
400	Bad Request	200000	Invalid Target Client Subacc.
400	Bad Request	200000	Invalid Program Participation ID.
400	Bad Request	200000	Too many programs found between merchants.
400	Bad Request	200000	Program does not exist between merchants.
400	Bad Request	200000	Program is Inactive.
400	Bad Request	200000	Invalid Token.
400	Bad Request	200000	Customer and Payment Information required for zero Subscription ID.
400	Bad Request	200000	Invalid 3DS Cavv.
400	Bad Request	200000	Invalid 3DS Cavv Algorithm.
400	Bad Request	200000	Invalid 3DS Xid.
400	Bad Request	200000	Invalid 3DS Ds Trans Id.
400	Bad Request	200000	Invalid 3DS Acs Trans Id.
400	Bad Request	200000	Threeds request parameters need to contain either 3DS verification parameters or error parameters to be valid.
400	Bad Request	200000	Problem with attribute digit format.
400	Bad Request	200000	Problem with data type.
400	Bad Request	200000	Invalid Program ID.
400	Bad Request	200000	Invalid date range.
401	Unauthorized	N/A	invalid_token
403	Forbidden	100020	Forbidden
404	Not Found	100101	Invalid payment token.
404	Not Found	100104	Lookup Object Not Found.
500	Internal Server Error	100103	Transaction error.
500	Internal Server Error	100105	Unable to complete the transaction required to create a payment token.
500	Internal Server Error	100106	There was an internal or database error, and the requested action could not be completed, or Data Link is inactive for user.
500	Internal Server Error	100107	The IP address the client was attempting to authenticate on was not in the valid range.
500	Internal Server Error	100108	The client's account has been deactivated for use on the Datalink system or the client is not permitted to perform the requested action.
500	Internal Server Error	100109	The client has unsuccessfully logged into the system 3 or more times in the last hour. The client should wait an hour before attempting to log in again and is advised to review the login information.
500	Internal Server Error	100110	Throttled, number of transactions has reached limit.
500	Internal Server Error	100111	Throttled, total money amount has reached the limit.
500	Internal Server Error	100112	Unable to determine if 3DS is required.
500	Internal Server Error	100113	Unable to retrieve authorized amount.

3DS Authentication Error Codes

HTTP Status Code	HTTP Status Type	Error Code	Error Message
500	Internal Server Error	200000	Authorization Failed due to Unknown Issue.
500	Internal Server Error	200001	Authorization Failed due to Unexpected Response from Third Party SCA.
500	Internal Server Error	200400	Authorization Failed due to Bad Request to Third Party SCA.
500	Internal Server Error	200401	Authorization Failed due to Unauthorized Request to Third Party SCA.
500	Internal Server Error	200500	Failed to Authenticate Transaction.
500	Internal Server Error	200501	API failed to parse JSON.
400	Bad Request	200502	Payment token does not exist.
400	Bad Request	200503	No card associated with payment token.
500	Internal Server Error	200600	Failed to Retrieve Status.
500	Internal Server Error	200601	API failed to Parse JSON.
404	Not Found	200602	Transaction ID Not Found.
400	Bad Request	200603	Validation Error Transaction ID not valid UUID.
400	Bad Request	200604	Validation Error Correlation Id not valid UUID.
400	Bad Request	200605	Validation Error Transaction Updated Format not YYYY-MM-DD HH:mm:ss zzz.