Protected: CCBill RESTful API Resources

This content is password protected. To view it please enter your password below:

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:

Terminology

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"
}
PARAMETERTYPEDESCRIPTION
cardNum (required)stringCard number
expDate (required)stringCard expiration date
nameOnCard (required)stringName 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"
}
PARAMETERTYPEDESCRIPTION
email (required)stringCustomer's email address
browserHttpAcceptLanguagestringList of acceptable human languages for response
browserHttpUserAgentstringThe user agent string of the user agent
citystringCustomer's city
browserHttpAcceptstringMedia type(s) that is(/are) acceptable for the response
state (required)stringCustomer's state
zipcode (required)stringCustomer's zip code
customerFname (required)stringCustomer's first name
address1stringCustomer's address
address2stringCustomer's address (additional info)
browserHttpAcceptEncodingstringList of acceptable encodings
customerLname (required)stringCustomer's last name
ipAddress (required)stringCustomer's IP address
phoneNumberstringCustomer's phone number
country (required)stringCustomer's country

PassThroughEntry

Type PassThroughEntry

{
  "name": "string",
  "value": "string"
}
PARAMETERTYPEDESCRIPTION
name (required)string
value (required)string

PaymentInfo

Type PaymentInfo

{
  "creditCardPaymentInfo": {
    "cardNum": "string",
    "expDate": "string",
    "nameOnCard": "string"
  }
}
PARAMETERTYPEDESCRIPTION
creditCardPaymentInfocreditCardPaymentInfoCredit card payment information
creditCardPaymentInfo. cardNum (required)stringCredit card number
creditCardPaymentInfo. expDate (required)stringCredit card expiration date
creditCardPaymentInfo. nameOnCard (required)stringName 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"
}
PARAMETERTYPEDESCRIPTION
createdDatetime (required)datetime-onlyDate and uime of creation of the Payment Token.
timeToLive (required)integerTime for the token to exist expressed in hours
originalPaymentTokenIdstringReference to a previous Token Id
validNumberOfUse (required)integerTotal number of times the Payment Token can be used for purchases
clientAccnum (required)integerMerchant account number
clientSubacc (required)integerMerchant subaccount number
programParticipationId (required)integerThe Program connected to the Payment Token
paymentTokenId (required)stringComplex representation of Payment Token Id
paymentInfoIdstringInformation associated with the payment
subscriptionId (required)integerIdentification 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
}
PARAMETERTYPEDESCRIPTION
clientAccnum (required)integerMerchant account number
clientSubacc (required)integerMerchant subaccount number
customerInfocustomerInfoCustomer Information
customerInfo. email (required)stringCustomer's email address
customerInfo. browserHttpAcceptLanguagestringList of acceptable human languages for response
customerInfo. browserHttpUserAgentstringThe user agent string of the user agent
customerInfo. citystringCustomer's city
customerInfo. browserHttpAcceptstringMedia type(s) that is(/are) acceptable for the response
customerInfo. state(required)stringCustomer's state
customerInfo. zipcode (required)stringCustomer's zip code
customerInfo. customerFname (required)stringCustomer's first name
customerInfo. address1stringCustomer's address
customerInfo. address2stringCustomer's address (additional info)
customerInfo. browserHttpAcceptEncodingstringList of acceptable encodings
customerInfo. customerLname (required)stringCustomer's last name
customerInfo. ipAddress (required)stringCustomer's IP address
customerInfo. phoneNumberstringCustomer's phone number
customerInfo. country (required)stringCustomer's country
paymentInfopaymentInfoPayment Information
paymentInfo. cardNum (required)stringCard number
paymentInfo. expDate (required)stringCard expiration date
paymentInfo. nameOnCard (required)stringName as it appears on card
subscriptionIdintegerTransaction subscription identification number
timeToLiveintegerTime for the token to exist expressed in hours
validNumberOfUseintegerTotal 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
}
PARAMETERTYPEDESCRIPTION
errorCode (required)integerError condition value of the transaction
approved (required)booleanApproval status of the transaction
paymentUniqueId (required)stringUnique key connected to a payment account
sessionId (required)stringUnique session ID value for transaction
subscriptionId (required)integersubscription ID to which the transaction belongs
newPaymentTokenId (required)stringNew 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"
		}
	]
}
PARAMETERTYPEDESCRIPTION
CreateNewPaymentTokenbooleanReturn a new payment token for subsequent transactions or not
initialPrice (required)numberPrice of the initial transaction
clientAccnum (required)integerClient account of the merchant
clientSubacc (required)integerClient subaccount of the merchant
lifeTimeSubscriptionbooleanA continual subscription with no end date or not
initialPeriod (required)integerTime period of the initial transaction
recurringPeriodintegerTime period of recurring transactions
currencyCodeintegerA numerical representation of the currency used in transaction
rebillsintegerThe number of times recurrent transactions can occur
recurringPricenumberPrice of recurrent transactions
passThroughInfoArray[any]Paired Information Passed Through to the Transaction Service

ValidationError

Type ValidationError

{
  "field": "string",
  "message": "string"
}
PARAMETERTYPEDESCRIPTION
field (required)stringField in error
message (required)stringUser-friendly message

Error

Type Error

{
  "id": "string",
  "url": "string",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "generalMessage": "string",
  "errorCode": "string",
  "timestamp": "datetime"
}
PARAMETERTYPEDESCRIPTION
id (required)stringRandomly generated GUID.
Validation pattern: ^[a-zA-Z0-9-]*$
Example: "62432dd8-97d9-400a-8da8-4a5c1951f935"
url (required)stringThe RELATIVE URL that has caused this error. Example: "/programs/123"
errorsValidationError[object]Optional, only returned on 400 Bad Request errors for validation errors
errors. field (required)stringField in error
errors. message (required)stringDescriptional message
generalMessage (required)stringA human-readable message
errorCode (required)stringProduct defined error code.
Validation pattern: ^[0-9-]*$
timestamp (required)datetimeTimestamp 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 NAMECONTENT-TYPE
Content-Typeapplication/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.

Your account will need to be configured to allow $0 USD authorizations and to return a subscriptionId that can interact with the chargeByPrevious functionality.

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

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

/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-RESOURCESMETHODSDESCRIPTION
/payment-tokens/merchant-onlyPOSTResource used for creating payment tokens that are not tied to a specific Merchant Connect Program
/payment-tokens/merchant-only-verifyPOSTResource used for creating payment tokens with CVV2 and AVS verification

Post Method CCBill RestFul API. /payment-tokens/merchant-only

Resource used for creating a payment token.

Headers

PARAMETERTYPEDESCRIPTION
Accept (required)stringAPI 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
}
PARAMETERTYPEDESCRIPTION
programId (required)integerThe ID of the program. Example value: 123
participantAccount (required)stringThe 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


The request has been successful. Extract the paymentTokenID string to create a charge for the customer.

Note: in PaymentTokenVerifyV2 subscriptionId is returned as a string. In the v1 sample below, subscriptionId is retuned as a number/integer.

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
clientAccnum (required) integer Merchant account number
clientSubacc (required) integer Merchant subaccount number
customerInfo (required) 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 (required) 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 (required) 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 (required) 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
validNumberOfUse integer Total number of times the Payment Token can be used for purchases

The response failed to complete due to an invalid header/parameter in the request.

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

The response failed to complete due to authorization problem.

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

The response failed to complete because access to the resource is forbidden.

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

The response failed to complete due to an invalid resource.

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

The response failed to complete due to an invalid method of request.

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

The response failed to complete due to an unacceptable media type in the request.

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

The response failed to complete due to an unsupported media type in the request.

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

The response failed to complete in some way.

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

Post Method CCBill RestFul API. /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

PARAMETERTYPEDESCRIPTION
Accept (required)stringAPI 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
}
PARAMETERTYPEDESCRIPTION
programId (required)integerThe ID of the program. Example value: 123
participantAccount (required)stringThe 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


The request has been successful. Extract the paymentTokenID string to create a charge for the customer.

Type PaymentTokenVerify
{ "createdDatetime": "datetime-only", "timeToLive": "integer", "originalPaymentTokenId": "string", "validNumberOfUse": "integer", "clientAccnum": "integer", "clientSubacc": "integer", "programParticipationId": "integer", "avsResponse": "string", "paymentTokenId": "string", "paymentInfoId": "string", "cvv2Response": "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 (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
avsResponse (required) string The result of AVS verification
paymentTokenId (required) string Complex representation of Payment Token Id
paymentInfoId string Information associated with the payment
cvv2Response (required) string The result of CVV2 verification
subscriptionId (required) integer Identification of the subscription associated with the transaction

The response failed to complete due to an invalid header/parameter in the request.

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

The response failed to complete due to authorization problem.

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

The response failed to complete because access to the resource is forbidden.

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

The response failed to complete due to an invalid resource.

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

The response failed to complete due to an invalid method of request.

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

The response failed to complete due to an unacceptable media type in the request.

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

The response failed to complete due to an unsupported media type in the request.

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

The response failed to complete in some way.

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

Get method parameters for CCBill's RestFul API. /payment-tokens/{paymentTokenId}

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

Parameters

PARAMETERTYPEDESCRIPTION
paymentTokenId (required)string

Headers

PARAMETERTYPEDESCRIPTION
Accept (required)stringAPI version.
Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json

Result Format


The request has been successful. Extract the paymentTokenID string to create a charge for the customer.

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

The response failed to complete due to an invalid header/parameter in the request.

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

The response failed to complete due to authorization problem.

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

The response failed to complete because access to the resource is forbidden.

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

The response failed to complete due to an invalid resource.

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

The response failed to complete due to an invalid method of request.

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

The response failed to complete due to an unacceptable media type in the request.

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

The response failed to complete due to an unsupported media type in the request.

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

The response failed to complete in some way.

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

/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-RESOURCESMETHODSDESCRIPTION
/transactions/payment-tokens/{payment_token_id}GET & POSTSubresource 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.

Post Method CCBill RestFul API. /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

PARAMETERTYPEDESCRIPTION
payment_token_id (required)stringThe payment token ID.

Header

PARAMETERTYPEDESCRIPTION
Accept (required)stringAPI 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"
		}
	]
}
PARAMETERTYPEDESCRIPTION
createNewPaymentTokenbooleanreturn new payment token for subsequent transactions or not
initialPrice (required)numberprice of initial transaction
clientAccnum (required)integerclientAccnum of the merchant
clientSubacc(required)integerclientSubacc of the merchant
lifeTimeSubscriptionbooleansubscription is eternal or not.
initialPeriod(required)integertime period of initial transaction
recurringPeriodintegertime period of recurrent transactions
currencyCodeintegernumerical representation of the currency used in a transaction
rebillsintegernumber of times recurrent transactions can occur
recurringPricenumberprice of recurrent transactions
passThroughInfoArray[any]Paired Information Passed Through to the Transaction Service

Result Format


A 200 return value indicates that the request was successful. You will receive the following information:

Type application/json
[ { "errorCode": "integer", "approved": "boolean", "paymentUniqueId": "string", "sessionId": "string", "subscriptionId": "integer", "newPaymentTokenId": "string" } ]

Parameter Type Description
item.errorCode (required) integer Error condition value of the transaction
item. approved (required) boolean Approval status of the transaction
item. paymentUniqueId (required) string Unique key connected to payment account
item. sessionId (required) string Unique session ID value for transaction
item.subscriptionId (required) integer Subscription ID to which the transaction belongs
item.newPaymentTokenId (required) string New payment token for subsequent transactions

The response failed to complete due to an invalid header/parameter in the request.

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

The response failed to complete due to authorization problem.

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

The response failed to complete because access to the resource is forbidden.

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

The response failed to complete due to an invalid resource.

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

The response failed to complete due to an invalid method of request.

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

The response failed to complete due to an unacceptable media type in the request.

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

The response failed to complete due to an unsupported media type in the request.

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

The response failed to complete in some way.

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

Get method parameters for CCBill's RestFul API. /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

PARAMETERTYPEDESCRIPTION
payment_token_id (required)stringThe payment token ID.

Headers

PARAMETERTYPEDESCRIPTION
Accept (required)stringAPI version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json

Result Value


A 200 return value indicates that the request was successful. You will receive the following information:

Type application/json
[ { "errorCode": "integer", "approved": "boolean", "paymentUniqueId": "string", "sessionId": "string", "subscriptionId": "integer", "newPaymentTokenId": "string" } ]

Parameter Type Description
item.errorCode (required) integer Error condition value of the transaction
item. approved (required) boolean Approval status of the transaction
item. paymentUniqueId (required) string Unique key connected to payment account
item. sessionId (required) string Unique session ID value for transaction
item.subscriptionId (required) integer Subscription ID to which the transaction belongs
item.newPaymentTokenId (required) string New payment token for subsequent transactions

The response failed to complete due to an invalid header/parameter in the request.

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.
timestamp (required) datetime Timestamp of the call

The response failed to complete due to authorization problem.

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

The response failed to complete because access to the resource is forbidden.

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

The response failed to complete due to an invalid resource.

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

The response failed to complete due to an invalid method of request.

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

The response failed to complete due to an unacceptable media type in the request.

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

The response failed to complete due to an unsupported media type in the request.

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

The response failed to complete in some way.

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

CCBill RESTful API Error Codes

HTTP Status CodeHTTP Status TypeError CodeError Message
400Bad Request100100Invalid client account
400Bad Request100102Expired payment token.
400Bad Request100105Invalid payout type.
400Bad Request100106Invalid privacy type.
400Bad Request100107Invalid program category.
400Bad Request100108Invalid payment type.
400Bad Request100109Invalid program participation.
400Bad Request200000Problem with attribute size.
400Bad Request200000Attribute required.
400Bad Request200000Problem with the attribute values.
400Bad Request200000Invalid credit card number.
400Bad Request200000Invalid email address.
400Bad Request200000Invalid Client Accnum.
400Bad Request200000Invalid Client Subacc.
400Bad Request200000Invalid Subscription ID.
400Bad Request200000Invalid Target Client Accnum.
400Bad Request200000Invalid Target Client Subacc.
400Bad Request200000Invalid Program Participation ID.
400Bad Request200000Too many programs found between merchants.
400Bad Request200000Program does not exist between merchants.
400Bad Request200000Program is Inactive.
400Bad Request200000Invalid Token.
400Bad Request200000Customer and Payment Information required for zero Subscription ID.
400Bad Request200000Invalid 3DS Cavv.
400Bad Request200000Invalid 3DS Cavv Algorithm.
400Bad Request200000Invalid 3DS Xid.
400Bad Request200000Invalid 3DS Ds Trans Id.
400Bad Request200000Invalid 3DS Acs Trans Id.
400Bad Request200000Threeds request parameters need to contain either 3DS verification parameters or error parameters to be valid.
400Bad Request200000Problem with attribute digit format.
400Bad Request200000Problem with data type.
400Bad Request200000Invalid Program ID.
400Bad Request200000Invalid date range.
401UnauthorizedN/Ainvalid_token
403Forbidden100020Forbidden
404Not Found100101Invalid payment token.
404Not Found100104Lookup Object Not Found.
500Internal Server Error100103Transaction error.
500Internal Server Error100105Unable to complete the transaction required to create a payment token.
500Internal Server Error100106There was an internal or database error, and the requested action could not be completed, or Data Link is inactive for user.
500Internal Server Error100107The IP address the client was attempting to authenticate on was not in the valid range.
500Internal Server Error100108The client's account has been deactivated for use on the Datalink system or the client is not permitted to perform the requested action.
500Internal Server Error100109The 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.
500Internal Server Error100110Throttled, number of transactions has reached limit.
500Internal Server Error100111Throttled, total money amount has reached the limit.
500Internal Server Error100112Unable to determine if 3DS is required.
500Internal Server Error100113Unable to retrieve authorized amount.

3DS Authentication Error Codes

HTTP Status CodeHTTP Status TypeError CodeError Message
500Internal Server Error200000Authorization Failed due to Unknown Issue.
500Internal Server Error200001Authorization Failed due to Unexpected Response from Third Party SCA.
500Internal Server Error200400Authorization Failed due to Bad Request to Third Party SCA.
500Internal Server Error200401Authorization Failed due to Unauthorized Request to Third Party SCA.
500Internal Server Error200500Failed to Authenticate Transaction.
500Internal Server Error200501API failed to parse JSON.
400Bad Request200502Payment token does not exist.
400Bad Request200503No card associated with payment token.
500Internal Server Error200600Failed to Retrieve Status.
500Internal Server Error200601API failed to Parse JSON.
404Not Found200602Transaction ID Not Found.
400Bad Request200603Validation Error Transaction ID not valid UUID.
400Bad Request200604Validation Error Correlation Id not valid UUID.
400Bad Request200605Validation Error Transaction Updated Format not YYYY-MM-DD HH:mm:ss zzz.

Merchant Connect

Merchant Connect is a marketplace designed to bring together merchants in one centralized location. CCBill is once again improving consumers’ online purchase experience by providing a new way to make new purchases from different merchants without re-entering payment information.

Designed to simplify and secure the purchase process while increasing revenue, Merchant Connect empowers your business to reach new markets and consumers with flexibility and innovation delivered by CCBill.

With Merchant Connect we’ve created a simple user experience that allows merchants to quickly and easily connect with each other, partnering to increase traffic and revenue for both parties. You can list your program and get it in front of the network of CCBill merchants, or quickly find a partner program to share your traffic with.

Features

How Merchant Connect Works

Basically, CCBill plays matchmaker between Sponsor Merchants and Affiliate Merchants. The platform empowers one-click transactions between all merchants, so your audience can make instant purchases from other merchants. An affiliate merchant sends a member or buyer to a selected number of CCBill sponsored merchants and offer their product which can be bought with a single click of a mouse button. CCBill tracks these one-click transactions, and we track and payout on the revenue sharing - all within the Merchant Connect platform.

What makes me a Sponsor or Affiliate Merchant?

What makes you a Sponsor Merchant?What makes you an Affiliate Merchant?
You would like to offer your product or service to other CCBill website owners.You have existing or previous consumers who have purchased through CCBill.
You would like to increase your incoming traffic and automate your revenue sharing.You would like to increase your revenue by offering another product or service to your consumers.
You would like to grow your own customer base with new cross-sales from partners.You would like to automate your sales flow and simplify the up-sale process on your site.

If you see yourself in any of the above-mentioned roles, then there's nothing standing in your way of receiving or sending traffic via Merchant Connect.

Requirements

Merchant Connect is considered to be an Advanced Feature. As such this document assumes the following:

Terminology

Data Link API Account

Merchant Connect implementation requires that both Sponsor Merchant and Affiliate Merchants use CCBill’s Data Link Extract System. Data Link will be enabled for your account when you set up a program, or you can contact our Merchant Support Department at merchantsupport@ccbill.com to have this enabled if you want to familiarize yourself with the system before you create programs.

CCBill API

Merchant Connect implementation requires that both Sponsor Merchant and Affiliate Merchant use the CCBill API. This is a component of Data Link that facilitates the use of the Advanced Method of implementing Merchant Connect. This method is further discussed below.

Velocity Controls

CCBill Velocity Controls is an advanced CCBill API feature, 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.

Use Cases

The implementation of the Merchant Connect system will be different for almost every situation. This document intends to provide you with an overview of the process and the necessary calls for the supported methods of submission and retrieval; you will need to use the provided information and mold it to your own setup.

Included are four potential manners in which Merchant Connect could be used.

Use Case #1 - Redirecting consumers to a tour

1. The consumer visits the Affiliate Merchant’s site and signs in to their account.

2. From the Affiliate Merchant’s site, the consumer clicks a banner or link for the Sponsor Merchant’s program.

3. Merchant Connect redirects the consumer to the Sponsor Merchant’s program page with an attached token that contains the consumer’s identifying information (the token is not visible to the consumer).

4. Merchant Connect presents an offer to the consumer from the Sponsor Merchant.

A graph showing how Merchant Connect works.

5. The consumer accepts the terms of the transaction.

6. Merchant Connect uses the token information to process the transaction without having the consumer enter in any payment information.

7. The Sponsor Merchant completes order fulfillment and the Affiliate Merchant is credited for referring the consumer to the Sponsor Merchant.

Use Case #2 - Charging a consumer immediately

1. The consumer visits the Affiliate Merchant’s site and signs in to their account.

2. From the Affiliate Merchant’s site, the consumer clicks a banner or link for the Sponsor Merchant’s program.

3. The consumer is redirected by Merchant Connect to the Sponsor Merchant’s program page with an attached token that contains the consumer’s identifying information (the token is not transparent to the consumer).

Merchant Connect when charging the customer immediatley.

4. During the redirect the consumer is charged using the token information.

5. The consumer is redirected to the Sponsor Merchant’s site with a successful transaction.

6. The Affiliate Merchant is credited for referring the consumer to the Sponsor Merchant.

Use Case #3 - Charging a consumer with a sessionId

1. The consumer visits the Affiliate Merchant’s site and signs in to their account.

2. While signed in to the Affiliate Merchant’s site, the consumer clicks a banner or link for the Sponsor Merchant’s program.

3. Merchant Connect redirects the consumer to the Sponsor Merchant’s program page with an attached token that contains the consumer’s identifying information (the token is not visible to the consumer).

4. Sponsor Merchant uses token information to generate a session of the consumer’s information (sessions do not expire and can be used indefinitely to charge the consumer without re-entering payment information).

Merchant Connect when charging the customer with the sessionID.

5. Merchant Connect uses the session information to process the transaction without having the consumer enter in any payment information.

6. The Sponsor Merchant completes order fulfillment and the Affiliate Merchant is credited for referring the consumer to the Sponsor Merchant.

Use Case #4 - Create a profile for a consumer

1. The consumer visits the Affiliate Merchant’s site and signs in to their account.

2. While signed in to the Affiliate Merchant’s site, the consumer clicks a banner or link for the Sponsor Merchant’s program.

3. Merchant Connect redirects the consumer to the Sponsor Merchant’s program page with an attached token that contains the consumer’s identifying information (the token is not transparent to the consumer).

4. The Affiliate Merchant adds additional information to the redirect URL as slash delimited details (/variable1/value1/variable2/value2).

5. Sponsor Merchant receives information from affiliate merchant’s site and creates a profile for consumer.

Using Merchant Connect to create a profile for a consumer.

6. Merchant Connect uses the token information to process the transaction without having the consumer enter in any payment information.

7. The consumer is signed in to the Sponsor Merchant’s site with a successful transaction and their new profile.

8. The Sponsor Merchant completes order fulfillment and the Affiliate Merchant is credited for referring the consumer to the Sponsor Merchant.

Implementation Methods

There are two methods of Merchant Connect implementation:

Advanced Method

The Advanced Method requires Affiliate Merchants to fully integrate with the CCBill API. The Affiliate then uses the “Get Cross Sale Token” calls in the CCBill API to generate and return an authenticated token via a script when a consumer clicks on the banner or promotional material on the Affiliate Merchant's site. The Affiliate Merchant then replaces that token with a modified version that contains their program participation ID.

The Sponsor Merchant’s site will use the CCBill API to make a “Charge By Token” call to the CCBill API to complete the purchase. In the event that the token is not authenticated (the Authentication Period has lapsed) the consumer will be required to provide some identity verification to obtain a verified token and resubmit the “Charge By Token” call. The default authentication period is 24 hours.

This method, although more programming-intensive, creates a more seamless experience for the user.

Simple Method

The Simple Method requires less programming from Affiliate Merchants to implement, but results in more input from the consumer in order to complete the purchase.

In the Simple Method Affiliate Merchants attach identifying information about the subscription holder to the referring link code instead of generating a CCBill API token. The consumer is directed through Merchant Connect where an unauthenticated token that includes the Affiliate Merchant’s information and the consumer’s identifying information is created and sent to the Sponsor Merchant’s site.

The consumer clicks to confirm the purchase which triggers the “Charge By Token” call to the CCBill API which in turn recognizes the unauthenticated status of the token and prompts the consumer for identity verification. If the identity is successfully verified the CCBill API will redirect to the ”url” parameter passed in by the Sponsor Merchant (a ”failureURL” can be provided as well for instances where the consumer fails to identify themselves properly).

The Simple Method has two “sub-options” available. The only difference between the two is the parameters that are required to be sent from the Affiliate Merchant to Merchant Connect.

API Integration

authenticationInfo

MerchantAccnumIntegerCCBill Merchant Account Number
MerchantSubaccShortCCBill Merchant Subaccount Number
usingMerchantSubaccShortCCBill Merchant Subaccount Number (when applicable and MerchantSubacc is null)
usernameStringCCBill API Username
passwordStringCCBill API Password

Function Examples

Sponsor Merchant Functions

getCrossSaleSessionInfo/getCrossSaleTokenInfo

INauthenticationInfo
INsessionId/tokeninfostringsessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant; tokeninfo is a transient data object that includes information that will be used to either create or lookup a session.
OUTemailstringEmail address on record for the Affiliate Merchant's consumer.
OUTisAuthLockedbyte1 = Consumer has failed too many times to be authen ticated and must try again later;
0 = Consumer has not exhausted their authentication attempts
OUTisAuthenticatedbyte1 = Consumer Validated their Postal Code or this was an advanced token;
0 = Consumer hasn't validated their Postal Code, their validation window has expired, or an advanced token has expired.
OUTauthenticationUrlstringIf isAuthenticated = 0, the user will need to be redirected to this URL to validate their identity; The following parameters can be passed through to this system:
*url = URL to redirect to upon successful validation (if not provided will redirect to the HTTP_REFERER)
*failureUrl = URL to redirect to upon failed validation (if not provided will redirect to "url" parameter)
OUTisUserCreatedbyte1 = Sponsor has successfully registered a user for the consumer using the createUserForCrossSale method;
0=Sponsor has not yet registered a user for the consumer using the createUserForCrossSale method.
OUTpaymentUniqueIdstringUniquely identifies a particular payment account (credit card/exp date, ACH account/routing number) utilizing a hashing algorithm. Often used by Sponsor Merchants for fraud purposes.
OUTprogramParticipationIdintegerThe unique identifier that signifies the relationship between an Affiliate Merchant and a Sponsor Merchant's program.
OUTsessionIdstringSame as above.
OUTerrorCodeinteger0 = There was no error;
see Appendix A: Error Codes and Descriptions for a list of other possible codes.
OUTerrorDescstringDescription of the returned error; see Appendix A: Error Codes and Descriptions for a list of possible descriptions.
OUTsubscriptionIdintegerIf this is present the Sponsor Merchant has processed at least one sale with this session. The subscriptionId provided was the first sale processed.

Example:

<soapenv:Envelope>
<soapenv:Body>
<q0:getCrossSaleTokenInfoRequest>
<authenticationInfo>
<MerchantAccnum>9000000</MerchantAccnum>
<username>user</username>
<password>test1234</password>
</authenticationInfo>
<tokenInfo>4OJ3K6i63IOtc0Czanbz5m2boEiaFf+lE2prv1bPkXQ=</tokenInfo>
</q0:getCrossSaleTokenInfoRequest>
</soapenv:Body>
</soapenv:Envelope>

Response:

<soap:Envelope>
<soap:Body>
<getCrossSaleTokenInfoResponse>
<response>
<errorCode>0</errorCode>
<email>xxxx@ccbill.com</email>
<isAuthLocked>0</isAuthLocked>
<isAuthenticated>1</isAuthenticated>
<isUserCreated>0</isUserCreated>
<paymentUniqueId>/PvvoUQCmc3WoTssCZawbQ</paymentUniqueId>
<programParticipationId>4240</programParticipationId>
<sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId>
<subscriptionId>0106100101000000001</subscriptionId
</response>
</getCrossSaleTokenInfoResponse>
</soap:Body>
</soap:Envelope>

paymentInfo

INauthenticationInfo
INsessionId/tokeninfostringsessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant; tokeninfo is a transient data object that includes information that will be used to either create or lookup a session.
INinitialPriceintegerAmount of the initial charge. Based on two implied decimals. For example, $2.95 should be passed as 295.
INinitialPeriodintegerLength of the initial term of the subscription in days.
INrecurringPriceintegerOptionalAmount of each recurring charge. Based on two implied decimals. For example, $29.95 should be passed 2995.
INrecurringPeriodintegerOptionalLength of the recurring term of the subscription in days.
INrebillsshortOptionalNumber of times to rebill the subscription before the subscription ends (99 for unlimited).
INcurrencyCodeshortOptionalISO 4217 Numeric Currency code (i.e., US Dollars = 840); Defaults to 840.

chargeCrossSaleBySession/chargeCrossSaleByToken

INpassThrough pairsname/value pairsOptionalMiscellaenous data that the Sponsor can pass in during the signup process that will be provided back to them in the approval/denial background posts.
OUTapprovedbyte0 = Declined, 1 = Approved.
OUTpaymentUniqueIdstringUniquely identifies a particular payment account (i.e., credit card/exp date, ACH account/routing number) utilizing a hashing algorithm. Some Merchants use this for fraud purposes on their side.
OUTsessionIdstringsessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant.
OUTsubscriptionIdstringThe Subscription ID of the newly processed transaction (assuming it was approved).
OUTdenialIdintegerThe unique descriptor of the ID.
OUTdeclineCodeintegerThe decline code provided by the credit card processor.
OUTdeclineTextstringPresent if the transaction is declined; provides a description about why the transaction was declined.
OUTauthenticateUrlstringPresent if the token/session is unauthenticated. If isAuthenticated = 0, the user will need to be redirected to this URL to validate their identity; The following parameters can be passed through to this system:
* url = URL to redirect to upon successful validation (if not provided will redirect to the HTTP_REFERER)
* failureUrl = URL to redirect to upon failed validation (if not provided will redirect to "url" parameter)

Example:


<soapenv:Envelope>
<soapenv:Body>
<q0:chargeCrossSaleBySessionRequest>
<authenticationInfo>
<MerchantAccnum>900000</MerchantAccnum>
<usingMerchantSubacc>0000</usingMerchantSubacc>
<username>testuser</username>
<password>test1234</password>
</authenticationInfo>
<sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId>
<paymentInfo>
<initialPrice>1000</initialPrice>
<initialPeriod>30</initialPeriod>
</paymentInfo>
<passThroughInfo>
<pairs>
<name>field1</name>
<value>value1</value>
</pairs>
</passThroughInfo>
</q0:chargeCrossSaleBySessionRequest>
</soapenv:Body>
</soapenv:Envelope>

Response:

<soap:Envelope>
<soap:Body>
<chargeCrossSaleBySessionResponse>
<response>
<errorCode>0</errorCode>
<approved>1</approved>
<paymentUniqueId>/PvvoUQCmc3WoTssCZawbQ</paymentUniqueId>
<sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId>
<subscriptionId>910089201000000023</subscriptionId>
</response>
</chargeCrossSaleBySessionResponse>
</soap:Body>
</soap:Envelope>

createUserForCrossSaleSession/createUserForCrossSaleToken

INauthenticationInfo
INsessionId/tokeninfostringsessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant; tokeninfo is a transient data object that includes information that will be used to either create or lookup a session.
INSponsorMemberUsernamestringOptionalThe username the Sponsor Merchant added to their website and provided to us utilizing the createUserForCrossSaleToken or createUserForCrossSaleSession methods.
INSponsorMemberPasswordstringOptionalSame as SponsorMemberUsername, except for the password.
OUTsessionIdstringsessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant.

Example:

<soapenv:Envelope>
<soapenv:Body>
<q0:createUserForCrossSaleSessionRequest>
<authenticationInfo>
<MerchantAccnum>900000</MerchantAccnum>
<username>testuser</username>
<password>test1234</password>
</authenticationInfo>
<sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId>
<SponsorMemberUsername>TEST</SponsorMemberUsername>
<SponsorMemberPassword>TEST</SponsorMemberPassword>
</q0:createUserForCrossSaleSessionRequest>
</soapenv:Body>
</soapenv:Envelope>

Response:

<soap:Envelope>
<soap:Body>
<createUserForCrossSaleSessionResponse>
<response>
<errorCode>0</errorCode>
<sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId>
</response>
</createUserForCrossSaleSessionResponse>
</soap:Body>
</soap:Envelope>

Affiliate Merchant Functions

generateSessionForCrossSale

INauthenticationInfo
INsubscriptionIdintegerOptionalThe Subscription ID that the Affiliate Merchant wishes to create the token from.
INAffiliateMemberUsernamestringOptionalThe Username that the Affiliate Merchant wishes to include in the token (will be overriden with what we have on record if they're using our user management).
IN
AffiliateMemberPassword
stringOptionalThe Password that the Affiliate Merchant wishes to include in the token (will be overriden with what we have on record if they're using our user management).
OUTtokeninfostringThe authenticated token that's created based on the information above that they will utilize to forward the consumer through WMS to the Sponsor's website.

Example:

<soapenv:Envelope>
<soapenv:Body>
<q0:generateSessionForCrossSaleByTokenRequest>
<authenticationInfo>
<MerchantAccnum>900000</MerchantAccnum>
<username>testuser</username>
<password>test1234</password>
</authenticationInfo>
<subscriptionId>0910089201000000022</subscriptionId>
</q0:generateSessionForCrossSaleByTokenRequest>
</soapenv:Body>
</soapenv:Envelope>

Response:

<soap:Envelope>
<soap:Body>
<generateSessionForCrossSaleByTokenResponse>
<return>
<errorCode>0</errorCode>
<tokeninfo>4OJ3K6i63IOtc0Czanbz5thajxTbspyOu7DBqLoLt9w%3D</tokeninfo>
</return>
</generateSessionForCrossSaleByTokenResponse>
</soap:Body>
</soap:Envelope>

Appendix A: Error Codes and Descriptions

Error CodeError Description
-101Invalid Subscription ID
-102Invalid Program Participation ID
-103Session not Found
-104Session is not Authenticated
-105Subscription ID not Present
-106System Error
-107User Already Created
-108Transaction Declined
-109Invalid Subscription
-110Unable to Verify Subscription
-111Unable to Find Customer Info
-112Invalid Merchant Subaccount
-113Invalid Recurring Info

Affiliate Merchant

Merchant Connect is a marketplace designed to bring together merchants in one centralized location. Merchant Connect builds on our One-Click Cross Sale System you can provide consumers a new way to make additional purchases from different merchants without re-entering payment information.

Affiliate Merchant Benefits

How Do I Join a Merchant Connect Program?

To join a Merchant Connect Program:

1. Sign in to the Admin Portal.

2. Click the Merchant Connect mega menu, then click Explore & Join Programs.

3. Browse the list of Merchant Connect programs available. When you find a program that interests you, click View Details for more information. View Details displays the following information:

Program Overview
Program NameName of the available Sponsor Program.
Program URLThe URL a consumer is directed to from your site.
Payout Type
RevsharePays a percentage of the consumer's purchase.
Pay per SalePays a flat dollar amount per sale.
Sponsor ManagedPayment is variable; Sponsor Merchant will provide more information.
Payout Details
Pay for Trials/Initials/RebillsShows which transaction types the program pays for.
Rebill Payout FrequencyThe number of rebills the program pays for.
Percent of Sale Payout or Flat Payout AmountSpecific payout amounts.
Payout TimeWhether you receive payment at the time of initial sale or after the first rebill is successful.
Method
Simple & Advanced/AdvancedCross Sale Method selected for the program.
Program Details
InstructionsGeneral Merchant Connect instructions.
Special InstructionsSpecific Sponsor instructions for this program.

4. Locate a program that you would like to promote and click Join Program.

5. After clicking Join Program, a notification is sent to the program owner expressing your interest in partnering with them. When the Sponsor approves your request you will receive an email confirming your acceptance.

Download the PHP Script

1. Sign in to the Admin Portal.

2. On the Merchant Connect mega menu, click Programs Currently Enrolled In to view your current partnerships.

3. Locate the program you wish to create a script for and click View Details.

4. In the API Account section, click Generate PHP Script.

5. After clicking this link you will be prompted to select an available API Account to use for this script. Select the radio button for the username you would like to use and click Generate PHP.

Once this button is clicked your download will begin in a new tab.

How Can I Begin Sending Traffic?

After joining the programs you wish to promote and downloading the PHP script, you just need to complete the technical integration. Click the Technical Features tab at the top of this page for details and example use cases/flows for Merchant Connect.

Sponsor Merchant

Merchant Connect is a marketplace designed to bring together merchants in one centralized location. By expanding our one click cross sale system you can provide consumers a new way to make additional purchases from different merchants without re-entering payment information.

Sponsor Merchant Benefits

How Can I Become a Sponsor Merchant?

Becoming a Merchant Connect Sponsor requires configuration from the CCBill Merchant Support Staff. Please contact merchantsupport@ccbill.com to begin the process.

Once the CCBill Staff has configured your account to be a Merchant Connect Sponsor you can configure your program.

How Do I Create a Merchant Connect Program?

To create a Sponsor Merchant Connect Program:

1. Sign in to the Admin Portal.

2. On the Merchant Connect mega menu, click Create Program to view your current partnerships.

3. The wizard will help you configure your Merchant Connect Program. The Create Program screen contains the following fields:

Payout Type
RevsharePercentage of the consumer's purchase paid out for sales paid out by CCBill.
Pay per SaleFlat dollar amount paid out per sale paid out by CCBill.
Sponsor ManagedIf you will be handling the payouts yourself; CCBill will not payout for programs with this setting.
Method
Simple & Advanced/AdvancedCross Sale Integration methods.
Program Details
InstructionsGeneral Merchant Connect instructions.
Special InstructionsYour specific instructions for this program.

4. Fill in the required fields and click Save at the top of the page.

How Do I Manage My Programs?

1. Sign in to the Admin Portal.

2. On the Merchant Connect mega menu, click Manage my Programs to view your current partnerships. This screen will list all your Merchant Connect Programs.

3. Select your preferred action from the Actions drop down menu. The available options are:

View/Modify Program

From within the View/Modify Program screen you will have the ability to make edits to your existing program setup. The CCBill system will automatically notify your Merchant Connect partners via email when changes are made to your program.

1. Click Edit at the top left of the screen.

2. Update any fields where changes are needed.

3. Click Save at the top left of the screen.

Deactivate Program

If you would like to deactivate a Merchant Connect Program you can do this from the Manage My Program Screen.

1. Locate the program you wish to deactivate from your program list.

2. Select Deactivate Program from the drop down menu.

3. You will be presented with a confirmation box to deactivate the program.

4. Select Yes.

Reactivate Program

If you have a program that has been deactivated, you can reactivate it from the Manage My Program screen as well.

1. Locate the program you wish to reactive from your program list.

2. Select Reactive Program from the drop-down menu.

3. You will be presented with a confirmation box to reactive the program.

4. Select Yes.

View Assigned Affiliates

This option will present you with all Merchant Connect partners currently active in your program. From here you can either view the Merchant's details, or remove them from your program.

Viewing Merchant Details

In order to view the details of a particular partner just click View Details next to their name. From this screen you'll be able to view the below listed details.

NAME
Affiliate ID
Participation ID
Name
Email
Address
Remove an Affiliate

You have two options to remove an affiliate from your program:

Option 1: From the Overview Page

1. Check the box to the left of the Affiliate ID for the merchant you wish to remove.You may select multiple Affiliates to be removed at once

2. Click Remove Selected Affiliate from this Program.

Option 2: From the Details Page

1. Locate the Affiliate you would like to remove from your program and click View Details.

2. Click Remove Affiliate from this Program.

Invitation Queue

All requests to join your program will be sent to the Invitation Queue and require approval before they can begin promoting your program. When an Affiliate requests to join your program you will be notified of a pending invitation via Email. Viewing and managing the invitation queue can be done in a few simple steps.

1. Sign in to the Admin Portal.

2. On the Merchant Connect mega menu, click Invitation Queue to view your pending invitations. This screen will list all your pending invitations.

3. Check the box next to the Affiliates you wish to accept or reject.

4. Click the appropriate button (Accept Selected Invitations or Reject Selected Invitations) at the top of the screen.

Affiliates will be notified via email when they are accepted or denied access to your program.

Webhooks

Introduction

Webhooks is an event-driven push notification system; when an event (e.g. a rebill) occurs, we deliver a post of data to a script that you designed based on our Webhook Documentation.

Webhooks is an alternative to our Background Post to URL feature and an add-on feature to our ENS system. The Webhooks system is much more robust, providing real-time notifications in addition to covering a greater array of event types.

What's a Webhook?

In general terminology, Webhooks is an API concept of sending real-time push notifications to Webhook endpoints.

  1. Your Webhook endpoint is your previously defined URL. All event notifications will be delivered to your URL.
  2. An Event is an occurrence surrounding your account, e.g., a user reactivating their subscription or a successful sale. Whenever a payment event occurs, you will receive a push notification.
  3. An HTTP POST is the process of submitting data to a specified resource. The data sent is not stored in browser history or in web server logs; you will need a script that will read the data and store it in your database. When it comes to sending data, this is a safe and secure data transfer method.

Simply put, when something happens (an event) with your account, CCBill’s Webhooks will send a notification to your URL (Webhook endpoint), providing you valuable insight into your online business.

Why Would I Want to Use Webhooks?

For Merchants, Webhooks is a way of receiving valuable information as soon as it happens, rather than checking your account’s data continually and getting no valuable data most of the time. In a lot of ways, Webhooks is just like receiving push notifications on your smartphone, i.e. Facebook sends you a notification whenever you receive a friend request. In a similar manner, CCBill Webhooks will send you a notification if, for example, a new sale was successfully performed. You can write this data to a database for record-keeping or pass them to another script.

Webhooks are especially helpful for:

How Webhooks Work

A Webhook is an HTTP POST operation that occurs when something happens (e.g. a sale). It’s like an inverted API endpoint; instead of making an API call, you can have information sent to your callback URL. You register a URL that we will notify each time an account event occurs.

The diagram below exemplifies how CCBill Webhooks work:

How Webhooks work.

What Is Exactly an Event?

As noted, an Event is some action regarding your account. Every push notification is sent as an XML data package and your URL should be a script, such as CGI, PHP, ASP, etc, programmed to receive and parse the information posted by CCBill.

Below you will find a Webhooks Post example.

POST /webhooks.php?clientAccnum=999999&clientSubacc=9999&eventType=Expiration&eventGroupType=Subscription HTTP/1.1
X-Allowed-Satellites: PHX,ASH,AMS
Content-Type: application/x-www-form-urlencoded
Content-Length: 102
Host: merchanturl.com
User-Agent: Java/1.6.0_03
Via: 1.1 wmq1.ccbill.com:3129 (squid/2.7.STABLE5), 1.0 internal
Cache-Control: max-age=0
Connection: keep-alive
clientAccnum=999999&clientSubacc=9999&subscriptionId=0913024401000012340&timestamp=2013-01-25 03:22:44

Enabling and Configuring Webhooks

To configure Webhooks:

  1. From the Subaccount Admin, click the Webhooks link on the left side of the screen.
  2. Enter the URL that you wish posts to be directed to in the Webhook URL field.
  3. Select the post types you wish to subscribe to (click All to select all types, or pick and choose any combination of post types by selecting the check box next to it).
  4. Select the Satellite Locations that Webhooks should post to you from. Try to choose a location that is geographically close to the server that the URL you selected in step 2 in order to ensure that posts get to your URL as quickly as the can. The satellite locations are currently:
    • Phoenix, Arizona
    • Ashburn, Virginia
    • Amsterdam, Netherlands
  5. Click Update to save the configuration.

For an in-depth description of Webhooks post types, variables, and other important information, please see the User Guide.

Note: We recommend testing your Webhook configuration before relying on its accuracy. You can do so by creating a CCBill Test account.

Can I Have Multiple URLs Acting as Webhook Endpoints?

After at least one Webhook has been saved you will be presented with the option to edit, remove, or add more. You may add up to four (4) Webhooks, and each may use different URLs if you wish.

Webhooks Events

Webhooks notifications are outlined in the Webhooks Documentation.

Events included are:

Support

If you encounter any issues in setting up Webhooks, please contact Merchant Support and a member of our team will assist you immediately.

CCBill API Guide

Introduction

This document is provided as a technical resource to CCBill merchants.

The information contained in this document concerns establishing and using the merchant-side consumer service Application Program Interface (API). The Subscription Management script replaces the Custom Cancel script and provides additional new features. The information contained in this document outlines the Subscription Management functionality and its interaction with the CCBill User Management System. Proper setup of the Data Link Extract System is required before the CCBill API can be utilized.

CCBill API

The subscriptionManagement.cgi script replaces the customCancel.cgi script in the Data Link Extract System. The CCBill API has additional features that were not included in the customCancel.cgi.

Before the subscriptionManagement.cgi script can be used your system must be set up to access the CCBill Data Link Extract System.

The CCBill Data Link Extract System allows CCBill merchants to access transaction data from the CCBill database with a CGI script. Consult the Data Link Extract User Guide for further information about Data Link Extract.

Required Parameters for Authentication

clientAccnum

This parameter specifies the main CCBill merchant account number of the merchant that is requesting the data. The value must be a six digit number.

username

This is the username that was setup for authentication on the Data Link Extract system.

password

This is the password that was setup for authentication on the Data Link Extract system.

action

This is the function to be performed within the CCBill API. See Supported Actions for a complete list of available options.

The table lists the parameters that are always required regardless if the action is to be performed on the main account or on a subaccount:

clientAccnumusernamepasswordaction
Main Account XXX
Sub Account XXX

Main Account Number - All CCBill merchants receive an account number for tracking purposes. The standard format is 9xxxxx-xxxx, where 9xxxxx is the main account. The main account is a 6-digit number. For example: "900000".

Sub Account Number - After a merchant signs up for website billing, they may open one or more subaccounts. The subaccount is a 4-digit number. The standard format is: xxxx. For example: "0002". The subaccount is part of the main account.

Optional Parameters

clientSubacc

This is the specific subaccount number the subscription is related to; it must be four digits long. If this parameter is provided, you will be authenticated on a specific subaccount and not on the main account. Any requested action must pertain to this subaccount,otherwise the operation will fail.

usingSubacc

Use this parameter if you wish to be authenticated on the main account but not on a specific subaccount. This parameter specifies a subaccount on which a requested operation will be performed.

Note: If clientSubacc is passed in along with usingSubacc, they must have the same value for a successful authentication. Different values would cause you to authenticate on a specific subaccount and operate on another.

returnXML

If this parameter is passed in, you will receive the information in XML format; otherwise the information is returned in CSV (comma separated values) format.

Supported Actions and Required Parameters

viewSubscriptionStatus

Reports the status of a customer subscription.

Required (X) and Optional (O) Parameters

viewSubscriptionStatusclientSubaccusingSubaccsubscriptionIdreturnXML
Main Account  OX 
Main Account w/XML  OXX
Sub Account X X 
Sub Account w/XML X XX

Information Returned

Status Codes:

CSV Version Example

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=viewSubscriptionStatus&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Return

"cancelDate","signupDate","chargebacksIssued","timesRebilled","expirationDate","recurringSubscription","subscriptionStatus","refundsIssued","voidsIssued""20050228","20050228170442","0","0","20050228","1","0","1","0"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123& returnXML=1&action=viewSubscriptionStatus&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Return

<?xml version='1.0' standalone='yes'?> 
<results>
   <cancelDate>20050228</cancelDate>
   <chargebacksIssued>0</chargebacksIssued>
   <expirationDate>20050228</expirationDate>
   <recurringSubscription>1</recurringSubscription>
   <refundsIssued>1</refundsIssued>
   <signupDate>20050228170442</signupDate>
   <subscriptionStatus>0</subscriptionStatus>
   <timesRebilled>0</timesRebilled>
   <voidsIssued>0</voidsIssued> 
</results>

viewDiscountInfo

Reports the discount information of a consumer subscription.

Required (X) and Optional (O) Parameters

viewDiscountInfoclientSubaccusingSubaccsubscriptionIdreturnXML
Main Account  O X X
Main Account w/XML  O X X
Sub Account X  X 
Sub Account w/XML X  X X

Information Returned

Note: Discounts can only be setup for recurring subscriptions. Also, to be eligible for a discount, the subscription’s recurring price must be at least $5.00.

CSV Version Example

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=viewDiscountInfo&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Return

"startPeriod","amount","discounts","discountInterval","type","startDate""1","1.00","1","1","CANCEL","20050228173436"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password =test123&returnXML=1&action=viewDiscountInfo&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Return

<?xml version='1.0' standalone='yes'?> 
<results>
   <discountInfo>
     <amount>1.00</amount>
     <discountInterval>1</discountInterval>
     <discounts>1</discounts>
     <startDate>20050228173436</startDate>
     <startPeriod>1</startPeriod>
     <type>CANCEL</type>
   </discountInfo> 
</results>

applyDiscount

Applies a previously set up cancel discount to a given subscription.

Required (X) and Optional (O) Parameters

applyDiscountclientSubaccusingSubaccsubscriptionIdreturnXML
Main Account  O X 
Main Account w/XML  O X X
Sub Account X O X 
Sub Account w/XML X O X X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&discountType=cancel&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&action=applyDiscount&clientAccnum=923590

Return

"results" 
"1"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&discountType=cancel&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&returnXML=1&action=applyDiscount&clientAccnum=923590

Return

<?xml version='1.0' standalone='yes'?> 
<results>1</results>

voidTransaction

Voids a consumer’s transaction, if still eligible. The most current consumer transaction can be annulled for a defined period before the transaction is settled.

The consumer will not be charged.

Required (X) and Optional (O) Parameters

voidTransactionclientSubaccusingSubaccsubscriptionIdreturnXML
Main Account  O X 
Main Account w/XML  O X X
Sub Account X  X 
Sub Account w/XML X  X X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&action=voidTransaction&clientAccnum=923590

Return

"results" 
"1"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&returnXML=1&action=voidTransaction&clientAccnum=923590

Return

<?xml version='1.0' standalone='yes'?> 
<results>1</results>

refundTransaction

Allows a full or partial refund. Passing in the amount will refund for that amount; please note that refunds cannot be given for an amount higher than that of the initial transaction. Omitting the value will give a full refund in the amount of the initial transaction.

Required (X) and Optional (O) Parameters

modifyUserCredentialsclientSubaccusingSubaccsubscriptionIdAmount
Main Account  O X O
Main Account w/XML  O X O
Sub Account X  X O
Sub Account w/XML X  X O

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=refundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=900000&amount=5.95

Return

"results" 
"1"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&action=refundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=900000&amount=5.95

Return

<?xml version='1.0' standalone='yes'?> 
<results>1</results>

voidOrRefundTransaction

Attempts to void the transaction. If the transaction can no longer be annulled because the defined period has passed, the transaction will be refunded. Partial refunds can be given by passing in the amount parameter. If the amount is passed in but the transaction can be voided, the transaction will be voided. To issue full or partial refunds without attempting to void the transaction, see the refundTransaction section of this document.

Required (X) and Optional (O) Parameters

voidOrRefundTransactionclientSubaccusingSubaccsubscriptionIdreturnXMLamount
Main Account  O X  O
Main Account w/XML  O X X O
Sub Account  X  O
Sub Account w/XML  X X O

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=voidOrRefundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Return

"results" 
"1"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&action=voidOrRefundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Return

<?xml version='1.0' standalone='yes'?> 
<results>1</results>

modifyUserCredentials

Re-adds or changes the username and/or password for an active subscription.

Required (X) and Optional (O) Parameters

modifyUserCredentialsclientSubaccusingSubaccsubscriptionIdcustUsernamecustPasswordreturnXML
Main Account  O X O O 
Main Account w/XML  O X O O X
Sub Account X  X O O 
Sub Account w/XML X  X O O X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=randomUN&password=test123&action=modifyUserCredentials&custPassword=randomPW&clientAccnum=923590

Return

"results" 
"1"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=randomUN&password=test123&action=modifyUserCredentials&custPassword=randomPW&clientAccnum=923590&returnXML=1

Return

<?xml version='1.0' standalone='yes'?> 
<results>1</results>

manualAdd

Manually adds a user to the account. The user will have access to the site up until the date specified by the 'endDate' parameter. This option bypasses the subscription model.

Required (X) and Optional (O) Parameters

manualAddclientSubaccusingSubacccustUsernamecustPasswordendDategenerateRandomreturnXML
Main Account  X X X X  
Main Account w/XML  X X X X  X
Sub Account X  X X X  
Sub Account w/XML X  X X X  X
Main Account w/Random  X   X X 
Main Account w/XML and Random  X   X X
Sub Account w/Random X    X X 
Sub Account w/XML and Random X    X X X

Optional Parameters

generateRandom

When this option is used, the username and password will be generated randomly and therefore, the parameters username and password are not required.

custUsername/custPassword

When these parameters are passed in, the username and password will be set to the respective values and therefore not be generated randomly.

Information Returned

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=manualAdd1&password=test123&endDate=20050330&action=manualAdd&custPassword=manualAdd2&clientAccnum=923590

Return

“endDate”,” username”,” password” 
20050330,manualAdd1,test123

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=manualAdd1&password=test123&returnXML=1&endDate=20050330&action=manualAdd&custPassword=manualAdd2&clientAccnum=923590

Return

<?xml version='1.0' standalone='yes'?> 
<results>
   <endDate>20050330</endDate>
   <username> manualAdd1</username>
   <password> test123</password> 
</results>

manualRemove

Removes a consumer’s ability to access your site.

Required (X) and Optional (O) Parameters

manualRemoveclientSubaccusingSubacccustUsernamereturnXML
Main Account  X X 
Main Account w/XML  X X X
Sub Account X  X 
Sub Account w/XML X  X X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&custUsername=quarter&action=manualRemove&usingSubacc=0005&username=ccbill12&clientAccnum=923590

Return

"results" 
"1"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&custUsername=quarter&action=manualRemove&usingSubacc=0005&username=ccbill12&clientAccnum=923590

Return

<?xml version='1.0' standalone='yes'?> 
<results>1</results>

extendSubscription

Extends the length of an existing consumer subscription. The ‘extendLength’ parameter is used to extend the subscription by a number of days.

Required (X) and Optional (O) Parameters

manualRemoveclientSubaccusingSubaccreturnXMLextendLength
Main Account  X  X
Main Account w/XML  X X X
Sub Account X   X
Sub Account w/XML X  X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&username=test123&clientAccnum=999999&clientSubacc=0000&action=extendSubscription&subscriptionId=1234567890&extendLength=30

Return

"results" 
"1"

XML VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&username=test123&clientAccnum=999999&clientSubacc=0000&action=extendSubscription&subscriptionId=1234567890&extendLength=30&returnXML=1

Return

<?xml version='1.0' standalone='yes'?> 
<results>1</results>

Success and Failure Codes

Success Codes
1The requested action was a success.

Error Codes

CodeDescription
0The requested action failed.
-1The arguments provided to authenticate the merchant were invalid or missing.
-2The subscription id provided was invalid or the subscription type is not supported by the requested action.
-3No record was found for the given subscription.
-4The given subscription was not for the account the merchant was authenticated on.
-5The arguments provided for the requested action were invalid or missing.
-6The requested action was invalid
-7There was an internal error or a database error and the requested action could not complete.
-8The IP Address the merchant was attempting to authenticate on was not in the valid range.
-9The merchant’s account has been deactivated for use on the Datalink system or the merchant is not permitted to perform the requested action
-10The merchant has not been set up to use the Datalink system.
-11Subscription is not eligible for a discount, recurring price less than $5.00.
-12The merchant has unsuccessfully logged into the system 3 or more times in the last hour. The merchant should wait an hour before attempting to login again and is advised to review the login information.
-15Merchant over refund threshold
-16Merchant over void threshold
-23Transaction limit reached
-24Purchase limit reached

Example 1: XML Version - Cancelled Subscription

Request

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900100&username=myusername&password=mypassword&action=cancelSubscription&subscriptionId=1000000000&returnXML=1

Description

The merchant is attempting to authenticate on the main account 900100. The clientSubacc parameter is not passed in and therefore will the authentication take place on the main account. The request is to see the subscription status of Subscription ID 1000000000. Since the clientSubacc parameter was not passed in, the Subscription ID can be from any subaccount under the 900100 account. Had it been passed in, the Subscription ID would have to be for the specified subaccount. The merchant is requesting the information to be returned in XML format.

Response

<?xml version='1.0' standalone='yes'?> 
<results>
   <cancelDate>20050223</cancelDate>
   <chargebacksIssued>0</chargebacksIssued>
   <expirationDate>20050324</expirationDate>
   <recurringSubscription>1</recurringSubscription>
   <refundsIssued>0</refundsIssued>
   <signupDate>20050222162551</signupDate>
   <subscriptionStatus>1</subscriptionStatus>
   <timesRebilled>0</timesRebilled>
   <voidsIssued>0</voidsIssued> 
</results>

Description

The subscription’s initial signup date and time was 02/22/2005 at 04:25:51 PM. It is a recurring subscription. The expiration date for the subscription is 03/24/2005. The subscription is in an active status; however, it has been cancelled by the customer on 02/23/2005. There were no rebills, voids, refunds or chargebacks for the subscription.

Example 2: CSV Version - Discount Subscription

Request

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900000&username=myusername&password=mypassword&action=discountSubscription&discountAmount=2.00&subscriptionId=0012946984374168

Description

The merchant is attempting to authenticate on the 0002 subaccount that is under the account 900100. The request is to view the discount information for Subscription ID 1000000002. Because the merchant is authenticating on the 0002 subaccount, the subscription must be for that subaccount. A returnXML was not passed in and therefore the information will be returned in CSV format.

Response

"startPeriod","amount","discounts","discountInterval","type","startDate"
"3","5.00","2","1","LOYALTY","20050222162551"

Description

The information reports that there is a discount set up for the subscription. The type of discount that was setup for the subscription type is a loyalty discount. The discount will start after 3 rebills. The discount is for $5.00 (the recurring price will be $5.00 less). The maximum of 2 discounts can be applied to the subscription. The interval between applied discounts is 1 rebill; this is the number or rebills that must occur before applying successive discounts. The initial subscription signup occurred on 02/22/2005.

Special CCBill API Functions:

CCBill API: Cancel Subscription
CCBill API: Advanced Dynamic Upgrades
CCBill API: One Click
CCBill API: Charge by Previous Transaction ID

CCBill API: Tangibles

Introduction

This document is an Addendum to the CCBill API and discusses Merchant configuration of the CCBill API to implement sales of Subscription Tangibles.

Scope

The CCBill API is considered to be an Advanced Feature of CCBill’s system. This document assumes the following:

Overview

Three actions have been added to the CCBill API, createFulfillment, updateFulfillment, and getFulfillmentStatus. These actions allow for shipment information to be inserted and maintained in our system.

Action Structure

Each action made through the CCBill API to the CCBill system must include the standard applicable CCBill API parameters (clientAccnum, clientSubacc, usingSubacc, username, password, returnXML- not all are required. See the CCBill API Guide for more information about the CCBill API basic structure.

Actions

The Actions and their respective parameters are listed in this section. CCBill’s system will send a response to the action; possible responses are defined in the Response section later in this document.

createFulfillment

The createFulfillment action allows you to insert shipment information into our system. The action consists of the following required parameters:

ParameterPurposeData
transactionIdIdentifies the transaction the shipment is associated with.19-20 numerical characters; subscriptionId or ID associated with rebill.
shippingCompanyIdentifies the name of the company performing the physical shipment.Allowed parameters are:   1. UPS (United Parcel Service)
2. USPS (United States Postal Service)
3. FedEx (Formerly Federal Express)
These parameters are case sensitive.
trackingIdIdentifies the tracking number for the company performing the physical shipment.For UPS:   *4-20 character alphanumeric. For USPS
(Mail Class or Service (With Sample Label ID Number)): *Express Mail® EA 000 000 000 US
*Express Mail International® EC 000 000 000 US
*Priority Mail International® CP 000 000 000 US
*Global Express Guaranteed® 82 000 000 00
*Registered Mail RA 000 000 000 US
*Delivery Confirmation 0000 0000 0000 0000 0000 00 For FedEx: *12 digit numeric

createFulfillment Sample Action

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=createFulfillment&transactionId=12345678987654321&shippingCompany=FedEx&trackingId=123456789987

updateFulfillment

The updateFulfillment action allows you to update existing shipper and/or tracking number for a transactionId. Any data you send using this action will replace the previously sent shippingCompany and trackingId parameters from the previous createFulfillment or updateFulfillment actions and replace it with the data being sent.

The following parameters are required for an updateFulfillment action:

ParameterPurposeData
transactionIdIdentifies the transaction the shipment is associated with.19-20 numerical characters; subscriptionId or ID associated with rebill.
shipmentIdGenerated by CCBill and sent with the original createFulfillment response and used to identify the shipment.Numerical characters of varying length, never more than 20 characters.
shippingCompanyIdentifies the name of the company performing the physical shipment.Allowed parameters are:   1. UPS (United Parcel Service)
2. USPS (United States Postal Service)
3. FedEx (Formerly Federal Express)
These parameters are case sensitive.
trackingIdIdentifies the tracking number for the company performing the physical shipment.For UPS:   *4-20 character alphanumeric. For USPS
(Mail Class or Service (With Sample Label ID Number)): *Express Mail® EA 000 000 000 US
*Express Mail International® EC 000 000 000 US
*Priority Mail International® CP 000 000 000 US
*Global Express Guaranteed® 82 000 000 00
*Registered Mail RA 000 000 000 US
*Delivery Confirmation 0000 0000 0000 0000 0000 00 For FedEx: *12 digit numeric

updateFulfillment Sample Action

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=updateFulfillment&transactionId=12345678987654321&shipmentId=123456&shippingCompany=FedEx&trackingId=123456789887

getFulfillmentStatus

The getFulfillmentStatus action allows you to query the CCBill system for previously stored fulfillment data for a transaction.

The getFulfillmentStatus action uses the following parameters:

ParameterPurposeData
transactionIdIdentifies the transaction the shipment is associated with.19-20 numerical characters; subscriptionId or ID associated with rebill.
shipmentIdGenerated by CCBill and sent with the original createFulfillment response and used to identify the shipment.Optional parameter. Numerical characters of varying length, never more than 20 characters.

getFulfillmentStatus Sample Action

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=getFulfillmentStatus&transactionId=12345678987654321&shipmentId=123456

Response

Success

Successful responses will be returned with some or all of the following parameters:

ResponsePurposeData
trackingIdIdentifies the tracking number for the company performing the physical shipment.For UPS:   *4-20 character alphanumeric. For USPS
(Mail Class or Service (With Sample Label ID Number)): *Express Mail® EA 000 000 000 US
*Express Mail International® EC 000 000 000 US
*Priority Mail International® CP 000 000 000 US
*Global Express Guaranteed® 82 000 000 00
*Registered Mail RA 000 000 000 US
*Delivery Confirmation 0000 0000 0000 0000 0000 00 For FedEx: *12 digit numeric
shipmentIdGenerated by CCBill and sent with the original createFulfillment response and used to identify the shipment.Optional parameter. Numerical characters of varying length, never more than 20 characters.
creationDateThe date and time that the record was created.2010-06-01T15:27:11.529-07:00   YYYY-MM-DDTHH:mm:ss.lllooo:00 *YYYY is the 4-digit year$$$*MM is the 2-digit month
*DD is the 2-digit day
*HH is the 2-digit hour
*mm is the 2-digit minute
*ss is the 2-digit second
*lll is the 3 digit milliseconds
*ooo:00 is the GMT offset (IE -07:00 is GMT-7)
nextCheckTimeThe next time the CCBill system will check the shipment status.2010-06-01T15:27:11.529-07:00   YYYY-MM-DDTHH:mm:ss.lllooo:00 *YYYY is the 4-digit year$$$*MM is the 2-digit month
*DD is the 2-digit day
*HH is the 2-digit hour
*mm is the 2-digit minute
*ss is the 2-digit second
*lll is the 3 digit milliseconds
*ooo:00 is the GMT offset (IE -07:00 is GMT-7)
prevShipmentIdAllows clients to retrieve previously stored shipment information for a transaction; always the most recent.Numerical characters of varying length, never more than 20 characters.
checkStatusURLThe URL that CCBill uses to check the status of the shipment.http://www.shipperurl.com/
ccbillShipmentStatusThe status code that CCBill uses for shipments.*See section: Status Codes later in this document for a list of CCBill Status Codes and their meanings.
shippingCompanyIdentifies the name of the company performing the physical shipment.Allowed parameters are:   *UPS (United Parcel Service)

Success Response Sample

Comma Delimited Response

"trackingId","shipmentId","creationDate","shipperStatus","nextCheckTime","prevShipmentId","checkStatusURL","ccbillShipmentStatus","shippingCompany"
"1","13","2010-06-01T15:27:11.529-07:00","ERROR RESPONSE","2010-06-01T23:27:23.326-07:00","0", "http://www.fedex.com/Tracking?language=english&cntry_code=&tracknumbers=1","SHIPPER_ERROR","FedEx"

XML Response

<?xml version='1.0' standalone='yes'?> 
<results>
   <shipmentInfos>
     <name>ShipmentTO</name>
     <ccbillShipmentStatus>SHIPPER_ERROR</ccbillShipmentStatus>
     <checkStatusURL>http://www.fedex.com/Tracking?language=english&cntry_code=&tracknumbers=1</checkStatusURL>
     <creationDate>2010-06-01T15:36:05.159-07:00</creationDate>
     <nextCheckTime>2010-06-01T23:36:08.211-07:00</nextCheckTime>
     <prevShipmentId>13</prevShipmentId>
     <shipmentId>14</shipmentId>
     <shipperStatus>ERROR RESPONSE</shipperStatus>
     <shippingCompany>FedEx</shippingCompany>
     <trackingId> EA 000 000 000 US</trackingId>
   </shipmentInfos>
   <transactionInfo>
     <clientAccnum>900000</clientAccnum>
     <clientSubacc>0000</clientSubacc>
     <creationDate>2010-06-01T15:27:10-07:00</creationDate>
     <subscriptionId>910130101000000003</subscriptionId>
     <transactionId>910068201000000000</transactionId>
   </transactionInfo> 
</results>

Status Codes

CodeDescription
NO_DATAThe initial status for each Shipment that appears when fulfillment information has not been added or has not been added successfully.
PENDINGIndicates that fulfillment data entered by the client is waiting to be sent to the shipper for its first status check; fulfillment data has been entered but the 8 hour waiting period for the initial shipper check has not yet passed.
SHIPPEDThis is the status indicating a Shipment is with the shipper but not yet received by the consumer.
SHIPPER_ERRORThe Shipment company has returned an error similar to “status not available” to our system during the most recent status check.
DELIVEREDThe Shipment company has returned a status to us that indicates that the shipment has been delivered to the receiver.
NOT_DELIVERABLEIndicates that a shipment cannot be delivered to the consumer for some reason, including address errors and refusals.
CLEAREDA CCBill staff member has cleared the status and set it as OK.

Error

Errors can be caused for any number of reasons, the most common being data validation errors. Here is a list of data validation performed by the Subscription Tangibles functions:

An error response will typically contain two parameters:

All possible errors, along with troubleshooting information, are included in this table:

errorDescerrorCodeDescription
ERROR_SERVICE_ERROR-200This is a generic error code and usually indicates that the service is temporarily unavailable.
ERROR_MISSING_PARAM-201One of the parameters required for the function was not included in the action. Refer to the chart above for required parameters for the action you are trying to make, and verify that the format for your action is correctly constructed.
ERROR_NO_MATCHING_SHIPMENT-202The shipmentId parameter contains unknown/non-matching shipment identification information.
ERROR_INVALID_TRACKING_NUMBER-203The trackingId parameter contains invalid information. Check to make sure that the trackingId contains all expected characters, matches the format expected for the shippingCompany parameter (see chart above) and verify the trackingId on the shipment receipt provided by your shipping company.
ERROR_NO_MATCHING_TRANSACTION-204The transactionId provided in the action does not match any previously known transactionId for your Account number (and Subaccount number, if applicable). Verify the transactionId and resubmit, if necessary.

Background Post

This document is provided as a technical resource to CCBill merchants. It discusses the features and implementation of the CCBill Background Post system. This document is intended to be read by programmers, technicians, and others with advanced coding skills.

Overview

CCBill Background Post is a method of passing data between the merchant’s system and CCBill’s system. Background Post essentially serves two purposes:

These two applications of the Background Post system are mutually exclusive and neither is required to use the other.

TLS Support

Background Post supports TLS 1.2 security protocol. If you are experiencing difficulties and not receiving posts from CCBill, please check which TLS protocol you’re using.

Passing Variables to the Signup Form

Variables can be passed to the signup form in order to pre-fill consumer information. This can be implemented for the purpose of multi-part forms, custom tracking, and other implementations. Variables are passed to the signup form from the page preceding it through the use of an HTML form, or by passing in the variables through the URL string. Code examples are given below.

Custom tracking variables can also be sent to the form. These values will be posted back using Background Post when the transaction is complete. To define these variables, simply specify a variable name and a value in the same manner as the other variables being passed.

To pre-fill the form, you must first generate HTML code for the form within the CCBill Admin. (For more information on how to generate this code, please consult the CCBill help file.) After generating your code, optional custom tracking variables can be added manually by creating additional HTML form fields or passing the additional variables into the URL string, depending on the chosen submission method.
The following example shows basic HTML button code, with two custom variables added. The button created will, when clicked, take the consumer to the CCBill signup form while passing in the two custom variables:

<form action='https://bill.ccbill.com/jpost/signup.cgi' method=POST> 
<input type=hidden name=clientAccnum value='900000'> 
<input type=hidden name=clientSubacc value='0001'> 
<input type=hidden name=formName value='13cc'> 
<input type=hidden name=language value='English'> 
<input type=hidden name=allowedTypes value='0000003361:840,0000004657:840,0000060748:840,0000060750:840,0000060752:840' >
<input type=hidden name=subscriptionTypeId value='0000004657:840'> 
<input type=hidden name=customVarName1 value=customVarValue1> 
<input type=hidden name=customVarName2 value=customVarValue2> 
<input type=submit name=submit value='Join Now'> 
</form>

customVarName1 and customVarName2 are only example names and can be anything you choose. The values are also an example.
You can use a text link instead of a button. The following example shows how to do this using data identical to the previous form example:

https://bill.ccbill.com/jpost/signup.cgi?clientAccnum=900000&clientSubacc=0001&formName=11wc&language=English&allowedTypes=0000003761:840,0000004607:840,0000060248:840,0000063750:840,0000060752:840&subscriptionTypeId=0000004657:840&customVarName1=customVarValue1&customVarName2=customVarValue2

Both methods serve the same purpose and either can be used.

CCBill flow for passing variables


Information can also be passed to the CCBill signup form using dynamic variables in a custom script. A custom HTML form can call the script, which then sends the variables to the CCBill signup form. The data flows in this path:

CCBill signup form flow when using dynamic variables in a custom script


The form you create will pass data entered by the consumer to the next form, which will then pass the variables to the CCBill signup form. Upon completion of the transaction, data will be sent to the Approval or Denial Post URL.
The following code example uses Perl/CGI code to output a hidden HTML form field using a dynamic variable:

print "<input type=hidden name=customer_fname value='$cust_first_name'>";

Other languages will have different statements and syntax for data output, such as print or echo statements in PHP. Link code can be output in a similar fashion to the HTML form code above, replacing any number of static variable values with dynamic variables. Please refer any questions you have concerning this type of code to a qualified programmer.

Approval and Denial Posts

When a transaction is approved or denied, data will be sent to the Approval or Denial URL, respectively. The data sent will include everything passed into the signup form through Background Post along with the data entered into the payment form by the consumer, excluding payment information. This data can be parsed and handled in whichever way the script is coded.

Data can be captured in multiple ways depending on the language in which the Approval or Denial script is written. For example:

Other languages will have appropriate functions to capture POST data. A full list of CCBill variables is available later in this document. Note that variable names must be entered exactly as they appear in this document.

Once the script captures these variable values, the script can handle the data in any manner specified in the script, such as inputting the information into a database.
The image illustrates the process of sending and receiving data using Approval and Denial URLs:

The flow for the process of sending and receiving data using Approval and Denial URLs:

Variables

Background Post contains a set of specified system variables that can be used to pull data from CCBill’s system. Two variable sets are used, one for each of the following situations:

In both cases, custom variables will be sent exactly as they were entered.
System variable names must be entered exactly as they appear in this list.

Signup Form

The following chart lists each variable that can be pre-filled in the signup form:

Variable NameDescription
customer_fnameConsumer first name
customer_lnameConsumer last name
address1Consumer address
emailConsumer email address
cityConsumer city
stateConsumer state
zipcodeConsumer Zip Code
countryConsumer country
phone_numberConsumer phone number
usernameConsumer username
passwordConsumer password
lifeTimeSubscription

The following variables can also be passed into the signup form, but are not shown on the form:

Variable NameDescriptionExample Value
ccbill_refererCCBill affiliate ID number. This value is passed as ‘reseller’ when using Traffic Manager to cascade to Epoch forms.1626321
formNameThree or more character code identifying the form.13cc
confirm_passwordConfirm password on signup form.0 or 1 (yes or no)
subscriptionTypeIdSubscription Type ID.0108191202000001259
allowedTypesThe subscription options that will appear on the form; this value is generated automatically in the Admin.0000003761:840,0000004607:840

Postback

The variables listed below are posted back to the Approval or Denial Post URLs:

Variable NameDescriptionData Type (Max Length)Example Value
accountingAmountActual payout price in USD that the merchant will receive from the purchase.decimal(9,2)14.83
address1Consumer address.varchar(30)123 Main Street
affiliateNon-custom referrer for legacy transaction; non-CCBill accounts (EC Suite, etc…)string1234567
affiliate_idProgram Participation Identification.string3542
affiliate_system-1– Unavailable, retrieve from DataLink
1 – CCBill
2 – WMS Affiliate
3 – Miscellaneous
4 – WMS Tracker
numeric-1
allowedTypesValue used to determine pricing options on the signup form.N/A (no limit)
baseCurrencyCurrency in which the price was configured.int(3)840
cardTypeType of credit card used.stringVISA or MASTERCARD
ccbill_refererCCBill affiliate ID number. This value is passed as 'reseller' when using Traffic Manager to cascade to Epoch forms.string1626321
cityConsumer city.varchar(30)Anytown
clientAccnumCCBill merchant main account number.mediumint(6) unsigned900100
clientDrivenSettlementReflects whether or not the transaction was pre-approved using Merchant-Driven Settlement.boolean1 or 0 (yes or no, respectively)
clientSubaccCCBill client subaccount Number.smallint(4) unsigned zerofill0000
consumerUniqueIdUnique consumer ID number.bigint(20)unsigned
countryConsumer country.varchar(30)US
currencyCodeThree-digit currency in which the consumer was billed.int(3)978
customer_fnameConsumer first name.varchar(20)John
customer_lnameConsumer last name.varchar(30)Smith
denialIdThe number that identifies a consumer’s declined transaction.
NOTE: This number is only provided with declines and is blank with approvals.
bigint(20) unsigned111140501000005157
emailConsumer Email address.varchar(40)user@example.com
formNameThree or more character code for the form.char(255)13cc
initialFormattedPriceInitial price with HTML entity for the currency symbol.string$10.00
initialPeriodThe initial period of the subscription (in days).smallint(4) unsigned7
initialPriceThe initial price of the subscription.decimal(9,2)4.99
ip_addressConsumer IP address.varchar(31)192.168.27.4
lifeTimeSubscriptionIndicates if the transaction is a Lifetime Subscription.
Is not posted if not positive.
int1
passwordConsumer password.varchar(30)mYPaSSw0rD
paymentAccountHash digest of consumer billing information.string(32)e1w4858fgb34e5ab2b0e8bd94cb09565
phone_numberConsumer phone number; appears as entered by consumer.varchar(20)(123) 456-7890
priceHTML-formatted product price as shown on the form.string&36;5.95 for 30 days (non-recurring)
productDescProduct description.varchar(50)
reasonForDeclineThe decline reason (Denial Post URL only). Text description of reasonForDeclineCode.
See “Postback Decline Codes” section below for a full list of codes.
stringSubscription ID Provided is invalid
(Please refer to the Postback Decline Codes section at the end of this document for a full list of decline codes and their reason descriptions.)
reasonForDeclineBeforeOverrideThe decline reason error that appears when a transaction was declined and later approved using Web Verify.StringTransaction requires additional approval: please refer to your confirmation e-mail for further instructions.
(Please refer to the Postback Decline Codes section at the end of this document for a full list of decline codes and their reason descriptions.)
reasonForDeclineCodeNumeric decline code (Denial Post URL only).string16
(Please refer to the Postback Decline Codes section at the end of this document for a full list of decline codes and their reason descriptions.)
reasonForDeclineCodeBeforeOverrideThe decline reason error code that appears when a transaction was declined and later approved using Web Verify.45
(Please refer to the Postback Decline Codes section at the end of this document for a full list of decline codes and their reason descriptions.)
rebillsThe total number of rebills.
A value of ‘99’ will rebill indefinitely.
tinyint(2) unsigned12
recurringFormattedPriceRecurring price with HTML entity for the currency symbol.string$19.95
recurringPeriodThe period of the subscription (recurring, in days).smallint(4) unsigned30
recurringPriceThe price of the subscription (recurring).decimal(7,2)19.99
refererNon - CCBill affiliate ID number. This variable is mainly utilized by third party systems.varchar(16)1626321
referringUrlURL from which the transaction was referred.stringhttp://www.example.com
reservationIdConsumer’s subscription Reservation ID number.bigint(20) unsigned0109072310330002423
responseDigestHash digest of a Dynamic Pricing response. If not using Dynamic Pricing, this value will return as a blank string.string(32)s4f5198jgd21a4pk1p2s7sd23lm58937
start_dateSubscription start date.date2008-08-05 15:18:17
stateConsumer state.varchar(20)AZ
subscription_idSubscription ID Number (Approval Post URL only).bigint(20)unsigned1000000000
typeIdSubscription Type ID number identifying the price point used in the transaction.int(10)0000060748
usernameConsumer username.varchar(16)username1
zipcodeConsumer Zip Code.varchar(10)85251

Other CCBill services, when used, will return additional variables using Background Post. For more information on the variables returned, please consult the User’s Guide for that service.

Postback Decline Codes

The following table lists potential values for the reasonForDeclineCode parameter and their related reasonForDecline text responses.

reasonForDeclineCodereasonForDecline
1Website is not available for signup
2Unable to determine website signup requirements
3Your card type is not accepted, please try another type of credit card
4Banking system error
5The credit card you entered is not valid
6Please check to ensure you entered your expiration dateUsed to show individual corresponding yearly, monthly or daily dates for report data. The date function's format is year-month-day; for example, 2002-01-01.
7Please check to ensure you entered your bank account number correctly
8Please check to ensure you entered your bank's routing number correctly
9Banking system error, please try again
10Website has invalid pricing
11Transaction declined
12You currently have a subscription and are unable to signup
13You have already had a free trial
14You must enter your CVV2 number on the back of your card
15Your account is currently being processed, please check the website you are joining to see if you have access. If not, please contact support@ccbill.com
16Subscription ID provided is invalid
17Subscription ID does not exist in system
18Previous transaction attempt in request was declined
19You are not authorized to signup with the provided credentials
20No decline
21You have already had a trial, please select a normal recurring membership option
22Error contacting bank, please try again later
23Invalid credit card provided
24Transaction denied by bank
25Bank error
26Card processing setup incorrect for Merchant
27System error, please try again
28We are unable to process your transaction at this time. Please try again at a later time
29Card expired
30We are unable to bill the telephone number provided for this transaction. Please return to the website and choose an alternate payment method
31Insufficient funds
32You must provide CVV2 to complete transaction
33Unable to determine transaction type
34Error contacting bank, please try again later
35Card declined at Pre-Auth SC
36Unable to contact bank
37We currently do not process for your banks bin
38Transaction refused by issuing bank
39You have submitted too many times today
40The card you are using is not accepted by this Merchant
41Merchant inactive
42Incorrect address provided
43We are unable to process your telephone billing transaction because your provider only allows for one charge, per telephone number, per day, and our records show that you have an existing daily charge to this telephone number. Please return to the website and choose an alternative payment method
44We're sorry, at this time prepaid cards are not allowed. Please try a different card type
45Transaction requires additional approval: please refer to your confirmation e-mail for further instructions
46Transaction declined
47Your transaction limit has been exceeded
48Your purchase limit has been reached
49Unable to authenticate your payment method. Please choose a different payment method and try again. If you need more information, please see 3DS Consumer Authentication
50Email address exceeds ACH transaction throttle
51Processor not supported by CDS
52TGS transaction has already been captured
53Exceeds refund limit
54Transaction has already been voided
55Transaction has already been refunded
56Invalid credit card
57Initial Price exceeds maximum
58Initial Price below minimum
59Recurring Price exceeds maximum
60Recurring Price below minimum
61System error while creating store credit card
62Payment Account Exceeds Transaction Number Throttle
63Payment Account Exceeds Transaction Amount Throttle
643DS authentication failed

Background Post IP Ranges

You will receive Background Posts from the following CCBill IP ranges:
64.38.240.0/24
64.38.241.0/24
64.38.212.0/24
64.38.215.0/24

You can use this information to setup firewall rules or confirm the validity of an IP from within your application.

WordPress and iThemes Security Plugin

If you use these features on a WordPress installation and iThemes Security plugin, you may encounter issues receiving posts from CCBill.

Follow these steps to resolve the issue:

  1. Log into the WordPress website.
  2. Click on Security Settings.
  3. Click on Banned Users.
  4. Uncheck the Enable HackRepair.com's blacklist feature.

Resending Failed Posts

The Background Post system automatically resends unsuccessful posts up to 30 times over the course of a few hours. If you do not receive posts we have no way to resend them to you beyond that.

If you are experiencing many failed posts, check to make sure that you are not experiencing a connection issue like trouble with your hosting company, among other things. Then contact Merchant Support and we will do what we can to help you find a solution.

Datalink Subscription Management

Datalink CCBill API lets you submit data to CCBill that changes existing transactions or subscriptions. Merchants build custom scripts that allow you to enter and submit information to us without signing in to the Admin Portal.

Transaction Functions Available

Our standard Subscription Management functions can be found in our CCBill API Guide.

Some examples are:

Dynamic Pricing User Guide

 

This document is provided as a technical resource to CCBill merchants. It is intended for programmers, technicians, and others with advanced coding skills. Some prior knowledge of the MD5 hashing algorithm is required.

Overview

Dynamic Pricing allows you to create new pricing options dynamically by passing variables into the signup form. This can be done using hidden HTML form fields or by including the variables into the URL string. To enhance security, an MD5 Hex Digest is used to validate the input of the new price.

Single billing and recurring billing subscriptions can be created using Dynamic Pricing, with the passed-in variables defining the pricing structure. Variable values will be passed to this script:

https://bill.ccbill.com/jpost/signup.cgi

Variables are explained in detail in the next section.

Please note that if Dynamic Pricing is enabled on the subaccount level, ALL signup forms on that subaccount must use Dynamic Pricing in order to function correctly. This includes forms created on the subaccount prior to Dynamic Pricing being enabled.

If Dynamic Pricing is enabled only on a particular form and not the entire subaccount, other forms on that subaccount will not be required to use Dynamic Pricing.

Default Dynamic Pricing Settings

Dynamic Pricing includes the following default settings. Changes to these settings may be available. Please contact Merchant Support for more information.

Variables

The set of variables passed into the form will depend on the type of transaction. The following variables are required for both single and recurring transactions:

The following variables are required for recurring transactions only. Omitting these variables will result in a single billing transaction:

Generating the MD5 Hash

The formDigest value is a hex-encoded MD5 hash, calculated using a combination of the above fields and a salt value. The salt value is used by CCBill to verify the hash and can be obtained in one of two ways:

Using your preferred MD5 hash generation tool and the Hex encoding method, you will need to create an MD5 Hex Digest using certain variable values. Values should be concatenated into one single string with no spaces prior to hashing.
For single billing transactions, use the following values in the order they are listed:

formPrice formPeriod currencyCode salt

For recurring transactions, use the following values in the order they are listed:

formPrice formPeriod formRecurringPrice formRecurringPeriod formRebills currencyCode salt

The resulting MD5 hash will be used as the value for the formDigest variable. This value can be statically hard-coded into a page or generated “on the fly” using a custom script.
Note that the values for clientAccnum, clientSubacc, and formName are not used when creating the MD5 hash for either transaction type.

Code Examples

The following example shows the data being passed through the URL string:

https://bill.ccbill.com/jpost/signup.cgi?clientAccnum=900100&clientSubacc=0000&formName=75cc&formPrice=18.00&formPeriod=10&formRecurringPrice=25.00&formRecurringPeriod=30¤cyCode=840&formRebills=1&formDigest=14258aa803845b8ce6916ebba4015e91

This URL string would be used as a link to the signup form.

Variables can also be passed using hidden fields in an HTML form. The following example shows possible code for a button that will take the consumer to the signup form:

<form id="myForm" method="post" action="https://bill.ccbill.com/jpost/signup.cgi"> 
<input type="hidden" name="clientAccnum" value="900100"> 
<input type="hidden" name="clientSubacc” value="0000"> 
<input type="hidden" name="formName” value="75cc"> 
<input type="hidden" name="formPrice” value="18.00"> 
<input type="hidden" name="formPeriod” value="10"> 
<input type="hidden" name="formRecurringPrice" value="25.00"> 
<input type="hidden" name="formRecurringPeriod" value="30"> 
<input type="hidden" name="currencyCode" value="840"> 
<input type="hidden" name="formRebills" value="1"> 
<input type="hidden" name="formDigest" value="14251aa803845b1ce6916ebba4015e91"> 
<input type="submit" value="Join Now!"> 
</form>

Postback

Dynamic Pricing requests will return the responseDigestvalue using the Background Post system. This value is an MD5 hash of transaction results which can be used to verify that the response was received properly by CCBill.
The value for responseDigest will contain an MD5 hash of the following values for approved transactions, concatenated into a single string:

These values will be sent to the Approval Post URL.
The value for responseDigest will contain an MD5 hash of the following values for denied transactions, concatenated into a single string:

These values will be sent to the Denial Post URL.

For more information on Background Post, including the use of Approval/Denial Post URLs, consult the Background Post User’s Guide.

v.3 12.30.2014

CCBill Velocity Controls

CCBill Velocity Controls is an enhancement to our billing API that utilizes new controls to throttle billing API transactions. Based on your own business model, you can set up CCBill Velocity Controls and limit purchases by the number of transactions and/or by cash amount of transactions within a given period of time.

Benefits for your business:

How it works?

Both rules can be used simultaneously and apply to all payment types. Each customer is assigned a unique ID based on the financial information the customer types in as well as other security considerations. This feature can be applied at an individual subaccount level or across all subaccounts. By setting up passive rules, 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.

Billing API Transactions

You can establish CCBill Velocity Controls for Charge by Previous, Merchant Connect, and CCBill API Upgrades transactions. Generate more meaningful purchases with protection from undue risk.

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