API Version: 1.0.0.3
Release Date: July 2018

Introduction

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

Scope

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

Requirements & Terminology

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

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

Terminology

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

Data Link API Account

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

Subscription Management System

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

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

Velocity Controls

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

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

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

CCBill Transaction API Objects

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

The CCBill Transaction API service uses conventional HTTP response codes to indicate errors. Generally, codes in the range of 4xx indicate an error due to the information provided in the request. Codes in the range of 5xx indicate an error due to an unexpected issue.

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

CreditCardPaymentInfo

Type CreditCardPaymentInfo

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

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

CustomerInfo

Type CustomerInfo

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

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

PassThroughEntry

Type PassThroughEntry

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

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

PaymentInfo

Type PaymentInfo

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

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

PaymentToken

Type PaymentToken

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

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

PaymentTokenMerchantOnlyParams

Type

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

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"customerInfo": {
		"customerFname": "Tyler",
		"customerLname": "Thomas",
		"address1": "Woodland Drive",
		"address2": "Apt 21",
		"city": "Tempe",
		"state": "AZ",
		"zipcode": "85281",
		"country": "US",
		"phoneNumber": "5555555555",
		"email": "tthomas@xyz.com",
		"ipAddress": "10.70.60.14'",
		"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
		"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
		"browserHttpAcceptLanguage": "en-US,en;q=0.5",
		"browserHttpAcceptEncoding": "gzip, deflate, br"
	},
	"paymentInfo": {
		"creditCardPaymentInfo": {
			"cardNum": "4473707989493598",
			"nameOnCard": "Tyler Thomas",
			"expDate": "201904"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}

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

TransactionInfo

Type TransactionInfo

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

Example

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

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

TransactionRequest

Type TransactionRequest

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

Example

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

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

ValidationError

Type ValidationError

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

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

Error

Type Error

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

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

API Endpoints

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

HEADER NAME	CONTENT-TYPE
Content-Type	application/json

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

Authentication and Authorization

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

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

See curl example below:

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

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

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

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

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

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

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

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

CVV2 and AVS Verification

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

Below is the paymentTokenVerify example:

{
	"paymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
	"programParticipationId": 1,
	"originalPaymentTokenId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"createdDatetime": "2018-01-01T01:00:00",
	"timeToLive": 30,
	"validNumberOfUse": 20,
	"subscriptionId": "900000000000000001",
	"paymentInfoId": "53104f5a54d3d43254def41c29aedba8",
	"cvv2Response": "M",
	"avsResponse": "Y"
}

CVV2 Responses

VALUE	DESCRIPTION
M	CVV2/CVC2/CID Match
N	CVV2/CVC2/CID No Match
P	Not Processed
S	The CVV2/CVC2/CID should be on the card, but the merchant indicates it is not.
U	The Issuer is not certified or has not provided Visa with encryption keys.

AVS Responses

VALUE	DESCRIPTION
A	The street addresses matches but the postal/ZIP code does not, or the request does not include the postal/ZIP code.
B	Street addresses match. Postal code is not verified due to incompatible formats (both street address and postal code were sent.)
C	Street address and postal code not verified due to incompatible formats. (both street address and postal code were sent)
D	Street addresses and postal codes match
F	Street address and postal code match. (U.K.- issued cards)
G	Issuer is not an AVS participant, or AVS data was present in the request but issuer did not return an AVS result, or Visa performs AVS on behalf of the issuer and there was no address record on file for this account.
O	Address information is not verified.
M	Street address and postal code match.
N	No match.Transaction contained Postal/ZIP code only, or street address only, or postal code and street address. Also used when transaction requests AVS but sends no AVS data.
P	Postal codes match. Postal code and street address were sent, but street address not verified due to incompatible formats.
R	Retry; System unavailable or timed out.
S	AVS currently not supported
U	No data from Issuer/Authorization platform
V	Nine character postal code matches; address does not match
X	Nine character postal code and address match
Y	Street address and postal code match
Z	Postal/ZIP matches, street address does not match, or street address not included in request.
1	Cardholder name and ZIP match
2	Cardholder name, address, and ZIP match
3	Cardholder name and address match
4	Cardholder name matches
5	Cardholder name incorrect, ZIP matches
6	Cardholder name incorrect; address and ZIP match
7	Cardholder name incorrect, address matches
8	Cardholder name, address, and ZIP do not match

/payment-tokens Endpoint

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

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

/payment-tokens/merchant-only

Resource used for creating a payment token.

Headers

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

Body

Type PaymentTokenMerchantOnlyParams

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

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"customerInfo": {
		"customerFname": "Tyler",
		"customerLname": "Thomas",
		"address1": "Woodland Drive",
		"address2": "Apt 21",
		"city": "Tempe",
		"state": "AZ",
		"zipcode": "85281",
		"country": "US",
		"phoneNumber": "5555555555",
		"email": "tthomas@xyz.com",
		"ipAddress": "10.70.60.14'",
		"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
		"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
		"browserHttpAcceptLanguage": "en-US,en;q=0.5",
		"browserHttpAcceptEncoding": "gzip, deflate, br"
	},
	"paymentInfo": {
		"creditCardPaymentInfo": {
			"cardNum": "4473707989493598",
			"nameOnCard": "Tyler Thomas",
			"expDate": "201904"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}

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

Result Format

/payment-tokens/merchant-only-verify

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

Headers

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

Body

Type PaymentTokenMerchantOnlyVerifyParams

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

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"customerInfo": {
		"customerFname": "Tyler",
		"customerLname": "Thomas",
		"address1": "Woodland Drive",
		"address2": "Apt 21",
		"city": "Tempe",
		"state": "AZ",
		"zipcode": "85281",
		"country": "US",
		"phoneNumber": "5555555555",
		"email": "tthomas@xyz.com",
		"ipAddress": "10.70.60.14'",
		"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
		"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
		"browserHttpAcceptLanguage": "en-US,en;q=0.5",
		"browserHttpAcceptEncoding": "gzip, deflate, br"
	},
	"paymentInfo": {
		"creditCardPaymentInfo": {
			"cardNum": "4473707989493598",
			"nameOnCard": "Tyler Thomas",
			"expMonth": "04",
			"expYear": "2019",
			"cvv2": "123"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}

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

Result Format

/payment-tokens/{paymentTokenId}

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

Parameters

PARAMETER	TYPE	DESCRIPTION
paymentTokenId (required)	string

Headers

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

Result Format

/transactions Endpoint

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

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

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

/transactions/payment-tokens/{payment_token_id}

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

Supply the payment token ID as a URI parameter.

Parameters

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

Header

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

Body

Type TransactionRequest

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

Example

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

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

Result Format

/transactions/payment-tokens/{payment_token_id}

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

Supply the payment token ID as a URI parameter.

Parameters

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

Headers

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

Result Value

CCBill RESTful API Error Codes

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

3DS Authentication Error Codes

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

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

• Searchable program listing. All Merchant Connect Sponsors will be visible to all merchants, including details of their program. From this list you can quickly select the program(s) you’re interested in partnering with and join immediately
• Flexible and reliable payments. Whether it’s Pay per Sale and Revshare through CCBill or sponsor managed, Merchant Connect comes with a variety of payment options for you.
• Simplified integration process. Merchant Connect comes with a pre-built script to handle the Affiliate Merchant functions. Spend less time integrating and more time making money.
• Cross-sell WITHOUT re-entering payment information. Expand on the success of our Cross Sale system to add promotional sales to your site as a post-sale tool and eliminate away the need to enter payment information so your consumers can get what they want without delay.
• Easily add related products to your site. Work with already established partners to add a tangible item, a cam purchase, or a dating site for your members. Reap the benefits of add-on purchases without taking on the overhead or workload for a solution you aren’t familiar with.
• Automate the purchase process. Once configured you can let the feature run itself. Receive automated notifications when purchases happen and get notified if program settings change. Spend more time growing your business and less time worrying about your partner setups.

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:

• The user has already enabled the CCBill API.
• The user possesses intermediate to advanced programming skills.
• The user possesses the programming skills necessary to create scripts and implement them in the context of this document.
• The user possesses knowledge of SOAP, HTML, XML and other web development technologies.
• The user has already set up User Management, if desired.

Terminology

• Sponsor Merchant. The Sponsor Merchant is a Merchant that wants to have other Merchants refer sales to them using the Merchant Connect feature.
• Affiliate Merchant. The Affiliate Merchant is a Merchant who assumes the role of an Affiliate in order to use Merchant Connect to refer its existing consumers to a Sponsor Merchant in exchange for a portion of the revenue generated by that sale.
• API Account. The API Account is also referred to as "Datalink Extract".

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.

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).

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).

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.

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. This method is preferred. The Advanced Method requires the Affiliate Merchant’s full integration with both CCBill API and User Management but provides the most seamless experience for consumers. This is the method the default PHP script provided by Merchant Connect uses.
• Simple Method. The Simple Method is an alternative method for Affiliate Merchants, but may result in more consumer intervention; including ID verification and/or re-entering payment and user information. There are two sub-options available for the Simple Method:
  • With Subscription ID requires the least Affiliate Merchant intervention.
  • With Username requires Affiliate Merchant integration with User Management.

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

• The Merchant Connect API is implemented as SOAP Call. The access point is https://bill.ccbill.com/dss.
• Responses are in SOAP format and contain errorCode and errorDesc along with additional information, if applicable.
• All operations include the following parameters for authentication purposes:

authenticationInfo

MerchantAccnum	Integer	CCBill Merchant Account Number
MerchantSubacc	Short	CCBill Merchant Subaccount Number
usingMerchantSubacc	Short	CCBill Merchant Subaccount Number (when applicable and MerchantSubacc is null)
username	String	CCBill API Username
password	String	CCBill API Password

Function Examples

Sponsor Merchant Functions

getCrossSaleSessionInfo/getCrossSaleTokenInfo

IN	authenticationInfo
IN	sessionId/tokeninfo	string	sessionId 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.
OUT	email	string	Email address on record for the Affiliate Merchant's consumer.
OUT	isAuthLocked	byte	1 = Consumer has failed too many times to be authen ticated and must try again later; 0 = Consumer has not exhausted their authentication attempts
OUT	isAuthenticated	byte	1 = 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.
OUT	authenticationUrl	string	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)
OUT	isUserCreated	byte	1 = 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.
OUT	paymentUniqueId	string	Uniquely 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.
OUT	programParticipationId	integer	The unique identifier that signifies the relationship between an Affiliate Merchant and a Sponsor Merchant's program.
OUT	sessionId	string	Same as above.
OUT	errorCode	integer	0 = There was no error; see Appendix A: Error Codes and Descriptions for a list of other possible codes.
OUT	errorDesc	string	Description of the returned error; see Appendix A: Error Codes and Descriptions for a list of possible descriptions.
OUT	subscriptionId	integer	If 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

IN	authenticationInfo
IN	sessionId/tokeninfo	string		sessionId 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.
IN	initialPrice	integer		Amount of the initial charge. Based on two implied decimals. For example, $2.95 should be passed as 295.
IN	initialPeriod	integer		Length of the initial term of the subscription in days.
IN	recurringPrice	integer	Optional	Amount of each recurring charge. Based on two implied decimals. For example, $29.95 should be passed 2995.
IN	recurringPeriod	integer	Optional	Length of the recurring term of the subscription in days.
IN	rebills	short	Optional	Number of times to rebill the subscription before the subscription ends (99 for unlimited).
IN	currencyCode	short	Optional	ISO 4217 Numeric Currency code (i.e., US Dollars = 840); Defaults to 840.

chargeCrossSaleBySession/chargeCrossSaleByToken

IN	passThrough pairs	name/value pairs	Optional	Miscellaenous data that the Sponsor can pass in during the signup process that will be provided back to them in the approval/denial background posts.
OUT	approved	byte		0 = Declined, 1 = Approved.
OUT	paymentUniqueId	string		Uniquely 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.
OUT	sessionId	string		sessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant.
OUT	subscriptionId	string		The Subscription ID of the newly processed transaction (assuming it was approved).
OUT	denialId	integer		The unique descriptor of the ID.
OUT	declineCode	integer		The decline code provided by the credit card processor.
OUT	declineText	string		Present if the transaction is declined; provides a description about why the transaction was declined.
OUT	authenticateUrl	string		Present 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

IN	authenticationInfo
IN	sessionId/tokeninfo	string		sessionId 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.
IN	SponsorMemberUsername	string	Optional	The username the Sponsor Merchant added to their website and provided to us utilizing the createUserForCrossSaleToken or createUserForCrossSaleSession methods.
IN	SponsorMemberPassword	string	Optional	Same as SponsorMemberUsername, except for the password.
OUT	sessionId	string		sessionId 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

IN	authenticationInfo
IN	subscriptionId	integer	Optional	The Subscription ID that the Affiliate Merchant wishes to create the token from.
IN	AffiliateMemberUsername	string	Optional	The 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	string	Optional	The 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).
OUT	tokeninfo	string		The 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 Code	Error Description
-101	Invalid Subscription ID
-102	Invalid Program Participation ID
-103	Session not Found
-104	Session is not Authenticated
-105	Subscription ID not Present
-106	System Error
-107	User Already Created
-108	Transaction Declined
-109	Invalid Subscription
-110	Unable to Verify Subscription
-111	Unable to Find Customer Info
-112	Invalid Merchant Subaccount
-113	Invalid 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

• Searchable program listing. All Merchant Connect Sponsors are visible to all merchants, including details of their program. From this list quickly select a program you’re interesting in partnering with and join immediately.
• Flexible and reliable payments. Whether it's Pay per Sale and Revshare through CCBill or sponsor managed, Merchant Connect comes with a variety of payment options for you.
• Simplified integration process. Merchant Connect contains a pre-built script to handle the Affiliate functions, so you can spend less time integrating and more time making money.
• Cross sell without re-entering payment information. Expand on the success of our cross sale system to add promotional sales to your site as a post-sale tool, removing the need to enter payment information your consumers can get what they want without delay.
• Easily add related products to your site. Work with established partners to add a tangible item, a cam purchase, or a dating site for your members. Reap the benefits of add-on purchases without taking on the overhead of a solution you’re not familiar with.
• Automate the purchase process. Once configured the feature runs itself. You will receive automated notifications for purchases and get notified if program settings change. Spend more time growing your business and less time worrying about your partner setups.

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 Name	Name of the available Sponsor Program.
Program URL	The URL a consumer is directed to from your site.
Payout Type
Revshare	Pays a percentage of the consumer's purchase.
Pay per Sale	Pays a flat dollar amount per sale.
Sponsor Managed	Payment is variable; Sponsor Merchant will provide more information.
Payout Details
Pay for Trials/Initials/Rebills	Shows which transaction types the program pays for.
Rebill Payout Frequency	The number of rebills the program pays for.
Percent of Sale Payout or Flat Payout Amount	Specific payout amounts.
Payout Time	Whether you receive payment at the time of initial sale or after the first rebill is successful.
Method
Simple & Advanced/Advanced	Cross Sale Method selected for the program.
Program Details
Instructions	General Merchant Connect instructions.
Special Instructions	Specific 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

• Searchable program listing. All Merchant Connect Sponsors will be visible to all merchants. Instead of searching for new partners, Merchant Connect lets CCBill's entire merchant base quickly and easily find and join your program.
• Simplified integration process. By providing a script for Affiliate Merchants to utilize, CCBill has taken out the difficulties normally associated with a system like this. This simplified approach opens up more potential partners and revenue streams.
• Cross sell without re-entering payment information. Online sales are extremely difficult sales to capture. The consumer is ready to get their purchase immediately, and doesn't want to type in the credit card information and waste time in getting what they want. With Merchant Connect, consumers can be charged immediately without re-entering their information, thus allowing for faster, smoother sales.
• Works with any business model. Easy purchases are no longer the domain of only cam sites. Whether you have a tangible product, a membership site, dating services, or a cam site the CCBill merchant base can sell your product quickly and easily.
• Expand your brand. CCBill's Merchant Connect allows you to bridge the gap between your product and our user base. By getting your name and product visible to more merchants you can reach new revenue streams that will benefit you both now and in the future.

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
Revshare	Percentage of the consumer's purchase paid out for sales paid out by CCBill.
Pay per Sale	Flat dollar amount paid out per sale paid out by CCBill.
Sponsor Managed	If you will be handling the payouts yourself; CCBill will not payout for programs with this setting.
Method
Simple & Advanced/Advanced	Cross Sale Integration methods.
Program Details
Instructions	General Merchant Connect instructions.
Special Instructions	Your 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
• Deactivate Program
• Reactivate Program
• View Assigned Affiliates.

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.

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:

• Working out your taxes can get vexing, but with CCBill Webhooks you can track your payments easier by logging in an accounting entry any time you’re notified about a successful sale.
• If you don’t use CCBill’s management system, Webhooks will help you immensely in updating customers’ memberships.
• Dealing with chargebacks and refunds. You are notified about chargebacks and refunds immediately, thus giving you precious time to act accordingly.

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:

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:

• UserReactivation
• NewSaleSuccess
• NewSaleFailure
• UpgradeSuccess
• UpgradeFailure
• UpSaleSuccess
• UpSaleFailure
• CrossSaleSuccess
• CrossSaleFailure
• Cancellation
• Expiration
• BillingDateChange
• CustomerDataUpdate
• RenewalSuccess (Rebill)
• Renewal Failure (Declined Rebill)
• Chargeback
• Return
• Refund
• Void

Support

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

• Hours: 24/7
• Toll-Free: 800.510.2859
• Email: merchantsupport@ccbill.com
• Live chat
• International number listing: https://www.ccbill.com/contact-us-phonenumbers.php
• Webhooks User 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:

clientAccnum	username	password	action
Main Account	X	X	X
Sub Account	X	X	X

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.

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

viewSubscriptionStatus	clientSubacc	usingSubacc	subscriptionId	returnXML
Main Account		O	X
Main Account w/XML		O	X	X
Sub Account	X		X
Sub Account w/XML	X		X	X

Information Returned

• Whether or not the subscription is active.
• The cancellation date of a cancelled subscription.
• Is the subscription recurring or a single billing subscription?
• The next billing date for recurring subscriptions or the expiration date for single billing subscriptions.
• If the subscription has been voided, refunded, or charged back and the number of each occurrence.
• The status of the subscription.

Status Codes:

• 0 - The subscription is inactive.
• 1 - The subscription is active but the customer has cancelled the subscription (pertains to recurring subscriptions).
• 2 - The subscription is active and the customer has NOT cancelled their subscription or the subscription is a nonrecurring subscription.
• On failure, an error code will be returned.

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

viewDiscountInfo	clientSubacc	usingSubacc	subscriptionId	returnXML
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

• Is the subscription eligible for a discount?

• Is a discount currently setup for the subscription?
• What are the properties of the discount?
• On failure, an error code will be returned.

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

applyDiscount	clientSubacc	usingSubacc	subscriptionId	returnXML
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

voidTransaction	clientSubacc	usingSubacc	subscriptionId	returnXML
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

modifyUserCredentials	clientSubacc	usingSubacc	subscriptionId	Amount
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

voidOrRefundTransaction	clientSubacc	usingSubacc	subscriptionId	returnXML	amount
Main Account		O	X		O
Main Account w/XML		O	X	X	O
Sub Account	X		X		O
Sub Account w/XML	X		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

modifyUserCredentials	clientSubacc	usingSubacc	subscriptionId	custUsername	custPassword	returnXML
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

manualAdd	clientSubacc	usingSubacc	custUsername	custPassword	endDate	generateRandom	returnXML
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	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

• The username that was added.
• The password that was added.
• The endDate is the date when the consumer’s access will be removed.
• On failure, an error code will be 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

manualRemove	clientSubacc	usingSubacc	custUsername	returnXML
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

manualRemove	clientSubacc	usingSubacc	returnXML	extendLength
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&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
1	The requested action was a success.

Error Codes

Code	Description
0	The requested action failed.
-1	The arguments provided to authenticate the merchant were invalid or missing.
-2	The subscription id provided was invalid or the subscription type is not supported by the requested action.
-3	No record was found for the given subscription.
-4	The given subscription was not for the account the merchant was authenticated on.
-5	The arguments provided for the requested action were invalid or missing.
-6	The requested action was invalid
-7	There was an internal error or a database error and the requested action could not complete.
-8	The IP Address the merchant was attempting to authenticate on was not in the valid range.
-9	The merchant’s account has been deactivated for use on the Datalink system or the merchant is not permitted to perform the requested action
-10	The merchant has not been set up to use the Datalink system.
-11	Subscription is not eligible for a discount, recurring price less than $5.00.
-12	The 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.
-15	Merchant over refund threshold
-16	Merchant over void threshold
-23	Transaction limit reached
-24	Purchase 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

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:

• The user has already enabled the CCBill API.
• The user possesses intermediate to advanced programming skills.
• The user’s company sells single and/or recurring shipments and has completed all required processes to enable said feature on the account and/or subaccount.
• The user has access to the supported shippers; UPS, USPS, and/or FedEx.

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:

Parameter	Purpose	Data
transactionId	Identifies the transaction the shipment is associated with.	19-20 numerical characters; subscriptionId or ID associated with rebill.
shippingCompany	Identifies 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.
trackingId	Identifies 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:

Parameter	Purpose	Data
transactionId	Identifies the transaction the shipment is associated with.	19-20 numerical characters; subscriptionId or ID associated with rebill.
shipmentId	Generated 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.
shippingCompany	Identifies 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.
trackingId	Identifies 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:

Parameter	Purpose	Data
transactionId	Identifies the transaction the shipment is associated with.	19-20 numerical characters; subscriptionId or ID associated with rebill.
shipmentId	Generated 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:

Response	Purpose	Data
trackingId	Identifies 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
shipmentId	Generated 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.
creationDate	The 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)
nextCheckTime	The 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)
prevShipmentId	Allows clients to retrieve previously stored shipment information for a transaction; always the most recent.	Numerical characters of varying length, never more than 20 characters.
checkStatusURL	The URL that CCBill uses to check the status of the shipment.	http://www.shipperurl.com/
ccbillShipmentStatus	The 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.
shippingCompany	Identifies 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

Code	Description
NO_DATA	The initial status for each Shipment that appears when fulfillment information has not been added or has not been added successfully.
PENDING	Indicates 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.
SHIPPED	This is the status indicating a Shipment is with the shipper but not yet received by the consumer.
SHIPPER_ERROR	The Shipment company has returned an error similar to “status not available” to our system during the most recent status check.
DELIVERED	The Shipment company has returned a status to us that indicates that the shipment has been delivered to the receiver.
NOT_DELIVERABLE	Indicates that a shipment cannot be delivered to the consumer for some reason, including address errors and refusals.
CLEARED	A 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:

• The Merchant Account Number, Subaccount Number, Subscription ID, or Transaction ID information is checked for accuracy.
• The Tracking ID and Shipper must be present.
• The Transaction ID provided belongs to the Merchant’s account (and Subaccount, if applicable).
• The Tracking ID provided must match one of the Shipper’s accepted formats (provided above).

An error response will typically contain two parameters:

• errorDesc: This is a description of the error your action received from our system.
• errorCode: This is the code number that the error is stored under in our system.

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

errorDesc	errorCode	Description
ERROR_SERVICE_ERROR	-200	This is a generic error code and usually indicates that the service is temporarily unavailable.
ERROR_MISSING_PARAM	-201	One 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	-202	The shipmentId parameter contains unknown/non-matching shipment identification information.
ERROR_INVALID_TRACKING_NUMBER	-203	The 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	-204	The 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.

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:

• Pass consumer data into the CCBill signup form. This can be used to pre-fill consumer data on the form or pass custom tracking parameters to be sent to the Approval/Denial Post URLs (see below). A list of standard CCBill system variables, used for pre-filling consumer data, is provided later in this document.
• Pass data to an Approval Post URL or Denial Post URL, depending on the outcome of the transaction. The Approval and Denial URLs are custom-coded scripts that capture returned post data from CCBill and process it according to the coding of the script. Approval and Denial Post URLs are coded by the merchant and are required to use the Background Post system. This guide will discuss potential applications of these URLs. For more information on setting your Approval and Denial Post URLs, please consult the CCBill help file.

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.

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:

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:

• Using PHP, the line $fname = $_POST%22customer_fname%22 will capture the consumer’s first name and assign it to a variable called $fname. The variable $fname can be named anything you choose.
• Using Perl/CGI, the line <strong>$fname = param("customer_fname")__</strong> will capture the consumer’s first name and assign it to a variable called <strong>$fname</strong>. The variable <strong>$fname</strong> can be named anything you choose.

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:

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:

• Signup Form. These variables are used to pre-fill the signup form. Naming the variables correctly, as listed below, will ensure the data properly stored in CCBill’s system as the variables are intended.
• Postback. These variables are sent to the Approval or Denial Post URLs, depending on the outcome of the transaction.

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 Name	Description
customer_fname	Consumer first name
customer_lname	Consumer last name
address1	Consumer address
email	Consumer email address
city	Consumer city
state	Consumer state
zipcode	Consumer Zip Code
country	Consumer country
phone_number	Consumer phone number
username	Consumer username
password	Consumer password
lifeTimeSubscription

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

Variable Name	Description	Example Value
ccbill_referer	CCBill affiliate ID number. This value is passed as ‘reseller’ when using Traffic Manager to cascade to Epoch forms.	1626321
formName	Three or more character code identifying the form.	13cc
confirm_password	Confirm password on signup form.	0 or 1 (yes or no)
subscriptionTypeId	Subscription Type ID.	0108191202000001259
allowedTypes	The 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 Name	Description	Data Type (Max Length)	Example Value
accountingAmount	Actual payout price in USD that the merchant will receive from the purchase.	decimal(9,2)	14.83
address1	Consumer address.	varchar(30)	123 Main Street
affiliate	Non-custom referrer for legacy transaction; non-CCBill accounts (EC Suite, etc…)	string	1234567
affiliate_id	Program Participation Identification.	string	3542
affiliate_system	-1– Unavailable, retrieve from DataLink 1 – CCBill 2 – WMS Affiliate 3 – Miscellaneous 4 – WMS Tracker	numeric	-1
allowedTypes	Value used to determine pricing options on the signup form.	N/A (no limit)
baseCurrency	Currency in which the price was configured.	int(3)	840
cardType	Type of credit card used.	string	VISA or MASTERCARD
ccbill_referer	CCBill affiliate ID number. This value is passed as 'reseller' when using Traffic Manager to cascade to Epoch forms.	string	1626321
city	Consumer city.	varchar(30)	Anytown
clientAccnum	CCBill merchant main account number.	mediumint(6) unsigned	900100
clientDrivenSettlement	Reflects whether or not the transaction was pre-approved using Merchant-Driven Settlement.	boolean	1 or 0 (yes or no, respectively)
clientSubacc	CCBill client subaccount Number.	smallint(4) unsigned zerofill	0000
consumerUniqueId	Unique consumer ID number.	bigint(20)	unsigned
country	Consumer country.	varchar(30)	US
currencyCode	Three-digit currency in which the consumer was billed.	int(3)	978
customer_fname	Consumer first name.	varchar(20)	John
customer_lname	Consumer last name.	varchar(30)	Smith
denialId	The number that identifies a consumer’s declined transaction. NOTE: This number is only provided with declines and is blank with approvals.	bigint(20) unsigned	111140501000005157
email	Consumer Email address.	varchar(40)	user@example.com
formName	Three or more character code for the form.	char(255)	13cc
initialFormattedPrice	Initial price with HTML entity for the currency symbol.	string	$10.00
initialPeriod	The initial period of the subscription (in days).	smallint(4) unsigned	7
initialPrice	The initial price of the subscription.	decimal(9,2)	4.99
ip_address	Consumer IP address.	varchar(31)	192.168.27.4
lifeTimeSubscription	Indicates if the transaction is a Lifetime Subscription. Is not posted if not positive.	int	1
password	Consumer password.	varchar(30)	mYPaSSw0rD
paymentAccount	Hash digest of consumer billing information.	string(32)	e1w4858fgb34e5ab2b0e8bd94cb09565
phone_number	Consumer phone number; appears as entered by consumer.	varchar(20)	(123) 456-7890
price	HTML-formatted product price as shown on the form.	string	&36;5.95 for 30 days (non-recurring)
productDesc	Product description.	varchar(50)
reasonForDecline	The decline reason (Denial Post URL only). Text description of reasonForDeclineCode. See “Postback Decline Codes” section below for a full list of codes.	string	Subscription 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.)
reasonForDeclineBeforeOverride	The decline reason error that appears when a transaction was declined and later approved using Web Verify.	String	Transaction 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.)
reasonForDeclineCode	Numeric decline code (Denial Post URL only).	string	16 (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.)
reasonForDeclineCodeBeforeOverride	The 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.)
rebills	The total number of rebills. A value of ‘99’ will rebill indefinitely.	tinyint(2) unsigned	12
recurringFormattedPrice	Recurring price with HTML entity for the currency symbol.	string	$19.95
recurringPeriod	The period of the subscription (recurring, in days).	smallint(4) unsigned	30
recurringPrice	The price of the subscription (recurring).	decimal(7,2)	19.99
referer	Non - CCBill affiliate ID number. This variable is mainly utilized by third party systems.	varchar(16)	1626321
referringUrl	URL from which the transaction was referred.	string	http://www.example.com
reservationId	Consumer’s subscription Reservation ID number.	bigint(20) unsigned	0109072310330002423
responseDigest	Hash digest of a Dynamic Pricing response. If not using Dynamic Pricing, this value will return as a blank string.	string(32)	s4f5198jgd21a4pk1p2s7sd23lm58937
start_date	Subscription start date.	date	2008-08-05 15:18:17
state	Consumer state.	varchar(20)	AZ
subscription_id	Subscription ID Number (Approval Post URL only).	bigint(20)unsigned	1000000000
typeId	Subscription Type ID number identifying the price point used in the transaction.	int(10)	0000060748
username	Consumer username.	varchar(16)	username1
zipcode	Consumer 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.

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

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:

• View a subscription Status
• View discount information
• Apply a discount
• Refund a transaction
• Void a transaction
• Modify a consumers username/password
• Issue a manual add
• Issue a manual remove
• Extend a subscription’s rebill date.

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.

• Minimum Price. $2.95
• Maximum Price. $100 (initial AND/OR recurring)
• Minimum Period. 3 days
• Recurring Periods Allowed. 30 Days, 60 Days, 90 Days.

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:

• clientAccnum. An integer value representing the 6-digit merchant account number.
• clientSubacc. An integer value representing the 4-digit merchant subaccount number.
• formName. The name of the form.
• formPrice. A decimal value representing the initial price.
• formPeriod. An integer representing the length, in days, of the initial billing period.
• currencyCode. An integer representing the 3-digit currency code that will be used for the transaction.
• formDigest. An MD5 Hex Digest based on the above values; this is explained further in the next section.

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

• formRecurringPrice. A decimal value representing the recurring billing price.
• formRecurringPeriod. An integer representing the number of days between each rebill.
• formRebills. An integer representing the total times the subscription will rebill. Passing a value of 99 will cause the subscription to rebill indefinitely.

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:

• Contact merchant support and receive the salt value, OR
• Create your own salt value (up to 32 alphanumeric characters) and provide it to merchant support.

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:

• subscriptionId. The unique subscription ID number for the subscription.
• 1. This value is simply the number 1 (one), used to show the transaction was approved.
• salt. The same value for salt mentioned in the Generating the MD5 Hash section above.

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:

• denialId. The unique denial ID number for the subscription.
• 0. This value is simply the number 0 (zero), used to show the transaction was denied.
• salt. The same value for salt mentioned in the Generating the MD5 Hash section above.

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

• Additional Security Layer
• More Control Over Your Transactions
• Automated Chargeback and Refund Protection
• Added Protection Against Affiliate Fraud
• More Transactions That Count

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.