API Version: 1.0.0.3
Release Date: July 2018
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.
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.
The CCBill Transaction API service is considered to be an Advanced Feature. As such, this document assumes the following:
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.
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.
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 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.
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 |
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 |
Type PassThroughEntry
{
"name": "string",
"value": "string"
}
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
name (required) | string | |
value (required) | string |
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 |
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 |
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 |
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 |
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 |
Type ValidationError
{
"field": "string",
"message": "string"
}
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
field (required) | string | Field in error |
message (required) | string | User-friendly message |
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 |
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/
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.
To successfully create a payment token with payment and customer information by creating $0 subscriptions, you need to:
Your account will need to be configured to allow $0 USD authorizations and to return a subscriptionId that can interact with the chargeByPrevious functionality.
The example below illustrates the parameters necessary to create a token with payment and customer information by creating $0 subscriptions.
{
"clientAccnum": 900003,
"clientSubacc": 1234,
"subscriptionId": 0,
"timeToLive": 30,
"customerInfo": {
"customerFname" : "Charlie",
"customerLname" : "Test",
"address1" : "1501 W 17th St",
"city" : "Tempe",
"state" : "AZ",
"zipcode" : "85281",
"country" : "US",
"phoneNumber" : "602-111-2222",
"email" : "ccbill@email.com",
"ipAddress" : "64.39.194.13"
},
"paymentInfo" : {
"creditCardPaymentInfo" : {
"cardNum" : "5105105105105100",
"nameOnCard" : "Charlie Test",
"expDate" : "122020"
}
}
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"
}
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. |
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 |
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 |
Resource used for creating a payment token.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
Accept (required) | string | API version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json |
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 |
{
"createdDatetime": "datetime-only",
"timeToLive": "integer",
"originalPaymentTokenId": "string",
"validNumberOfUse": "integer",
"clientAccnum": "integer",
"clientSubacc": "integer",
"programParticipationId": "integer",
"paymentTokenId": "string",
"paymentInfoId": "string",
"subscriptionId": "integer"
}
Parameter | Type | Description |
---|---|---|
clientAccnum (required) | integer | Merchant account number |
clientSubacc (required) | integer | Merchant subaccount number |
customerInfo (required) | customerInfo | Customer Information |
customerInfo. email (required) | string | Customer's email address |
customerInfo. browserHttpAcceptLanguage | string | List of acceptable human languages for response |
customerInfo. browserHttpUserAgent | string | The user agent string of the user agent |
customerInfo. city (required) | string | Customer's city |
customerInfo. browserHttpAccept | string | Media type(s) that is(/are) acceptable for the response |
customerInfo. state (required) | string | Customer's state |
customerInfo. zipcode (required) | string | Customer's zip code |
customerInfo. customerFname (required) | string | Customer's first name |
customerInfo. address1 (required) | string | Customer's address |
customerInfo. address2 | string | Customer's address (additional info) |
customerInfo. browserHttpAcceptEncoding | string | List of acceptable encodings |
customerInfo. customerLname (required) | string | Customer's last name |
customerInfo. ipAddress (required) | string | Customer's IP address |
customerInfo. phoneNumber | string | Customer's phone number |
customerInfo. country (required) | string | Customer's country |
paymentInfo (required) | paymentInfo | Payment Information |
paymentInfo. cardNum (required) | string | Card number |
paymentInfo. expDate (required) | string | Card expiration date |
paymentInfo. nameOnCard (required) | string | Name as it appears on card |
subscriptionId | integer | Transaction subscription identification number |
timeToLive | integer | Time for the token to exist |
validNumberOfUse | integer | Total number of times the Payment Token can be used for purchases |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"id": "string",
"url": "string",
"errors": [
{
"field": "string",
"message": "string"
}
],
"generalMessage": "string",
"errorCode": "string",
"timestamp": "datetime"
}
Parameter | Type | Description |
---|---|---|
id (required) | string | Randomly generated GUID. Validation pattern: ^[a-zA-Z0-9-]*$ Example: "62432dd8-97d9-400a-8da8-4a5c1951f935" |
url (required) | string | The RELATIVE URL that has caused this error. Example: "/programs/123" |
errors | ValidationError[object] | Optional, only returned on 400 Bad Request errors for validation errors |
errors. field (required) | string | Field in error |
errors. message (required) | string | Descriptional message |
generalMessage (required) | string | A human-readable message |
errorCode (required) | string | Product defined error code. Validation pattern: ^[0-9-]*$ |
timestamp (required) | datetime | Timestamp of the call |
The 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.
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 |
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 |
{
"createdDatetime": "datetime-only",
"timeToLive": "integer",
"originalPaymentTokenId": "string",
"validNumberOfUse": "integer",
"clientAccnum": "integer",
"clientSubacc": "integer",
"programParticipationId": "integer",
"avsResponse": "string",
"paymentTokenId": "string",
"paymentInfoId": "string",
"cvv2Response": "string",
"subscriptionId": "integer"
}
Parameter | Type | Description |
---|---|---|
createdDatetime (required) | datetime-only | Date and uime of creation of the Payment Token. |
timeToLive (required) | integer | Time for the token to exist (hours) |
originalPaymentTokenId | string | Reference to a previous Token Id |
validNumberOfUse (required) | integer | Total number of times the Payment Token can be used for purchases |
clientAccnum (required) | integer | Merchant account number |
clientSubacc (required) | integer | Merchant subaccount number |
programParticipationId (required) | integer | The Program connected to the Payment Token |
avsResponse (required) | string | The result of AVS verification |
paymentTokenId (required) | string | Complex representation of Payment Token Id |
paymentInfoId | string | Information associated with the payment |
cvv2Response (required) | string | The result of CVV2 verification |
subscriptionId (required) | integer | Identification of the subscription associated with the transaction |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
Use this request to retrieve details of a Payment Token based on its ID.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
paymentTokenId (required) | string |
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
Accept (required) | string | API version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
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.
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.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
payment_token_id (required) | string | The payment token ID. |
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
Accept (required) | string | API version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json |
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 |
[
{
"errorCode": "integer",
"approved": "boolean",
"paymentUniqueId": "string",
"sessionId": "string",
"subscriptionId": "integer",
"newPaymentTokenId": "string"
}
]
Parameter | Type | Description |
---|---|---|
item.errorCode (required) | integer | Error condition value of the transaction |
item. approved (required) | boolean | Approval status of the transaction |
item. paymentUniqueId (required) | string | Unique key connected to payment account |
item. sessionId (required) | string | Unique session ID value for transaction |
item.subscriptionId (required) | integer | Subscription ID to which the transaction belongs |
item.newPaymentTokenId (required) | string | New payment token for subsequent transactions |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
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.
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
payment_token_id (required) | string | The payment token ID. |
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
Accept (required) | string | API version. Example value: application/vnd.com.ccbill.mcn.transaction.service.v1+json |
[
{
"errorCode": "integer",
"approved": "boolean",
"paymentUniqueId": "string",
"sessionId": "string",
"subscriptionId": "integer",
"newPaymentTokenId": "string"
}
]
Parameter | Type | Description |
---|---|---|
item.errorCode (required) | integer | Error condition value of the transaction |
item. approved (required) | boolean | Approval status of the transaction |
item. paymentUniqueId (required) | string | Unique key connected to payment account |
item. sessionId (required) | string | Unique session ID value for transaction |
item.subscriptionId (required) | integer | Subscription ID to which the transaction belongs |
item.newPaymentTokenId (required) | string | New payment token for subsequent transactions |
{
"id": "string",
"url": "string",
"errors": [
{
"field": "string",
"message": "string"
}
],
"generalMessage": "string",
"errorCode": "string",
"timestamp": "datetime"
}
Parameter | Type | Description |
---|---|---|
id (required) | string | Randomly generated GUID. Validation pattern: ^[a-zA-Z0-9-]*$ Example: "62432dd8-97d9-400a-8da8-4a5c1951f935" |
url (required) | string | The RELATIVE URL that has caused this error. Example: "/programs/123" |
errors | ValidationError[object] | Optional, only returned on 400 Bad Request errors for validation errors |
errors. field (required) | string | Field in error |
errors. message (required) | string | Descriptional message |
generalMessage (required) | string | A human-readable message |
errorCode (required) | string | Product defined error code. |
timestamp (required) | datetime | Timestamp of the call |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
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. |
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.
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 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.
Merchant Connect is considered to be an Advanced Feature. As such this document assumes the following:
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.
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.
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.
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.
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.
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.
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.
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.
There are two methods of Merchant Connect implementation:
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.
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.
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 |
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 | 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>
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. |
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>
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>
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>
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 |
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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 |
Address |
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.
All requests to join your program will be sent to the Invitation Queue and require approval before they can begin promoting your program. When an Affiliate requests to join your program you will be notified of a pending invitation via Email. Viewing and managing the invitation queue can be done in a few simple steps.
1. Sign in to the Admin Portal.
2. On the Merchant Connect mega menu, click Invitation Queue to view your pending invitations. This screen will list all your pending invitations.
3. Check the box next to the Affiliates you wish to accept or reject.
4. Click the appropriate button (Accept Selected Invitations or Reject Selected Invitations) at the top of the screen.
Affiliates will be notified via email when they are accepted or denied access to your program.
Webhooks 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.
In general terminology, Webhooks is an API concept of sending real-time push notifications to Webhook endpoints.
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.
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:
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:
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×tamp=2013-01-25 03:22:44
To configure Webhooks:
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.
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 notifications are outlined in the Webhooks Documentation.
Events included are:
If you encounter any issues in setting up Webhooks, please contact Merchant Support and a member of our team will assist you immediately.
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.
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.
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.
This is the username that was setup for authentication on the Data Link Extract system.
This is the password that was setup for authentication on the Data Link Extract system.
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.
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.
Use this parameter if you wish to be authenticated on the main account but not on a specific subaccount. This parameter specifies a subaccount on which a requested operation will be performed.
Note: If clientSubacc
is passed in along with usingSubacc
, they must have the same value for a successful authentication. Different values would cause you to authenticate on a specific subaccount and operate on another.
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.
Reports the status of a customer subscription.
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 |
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"
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>
Reports the discount information of a consumer subscription.
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 |
Note: Discounts can only be setup for recurring subscriptions. Also, to be eligible for a discount, the subscription’s recurring price must be at least $5.00.
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"
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>
Applies a previously set up cancel discount to a given subscription.
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 |
A success or failure code will be returned.
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"
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>
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.
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 |
A success or failure code will be returned.
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"
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>
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.
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 |
A success or failure code will be returned.
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"
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>
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.
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 |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=voidOrRefundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590
Return
"results" "1"
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>
Re-adds or changes the username and/or password for an active subscription.
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 |
A success or failure code will be returned.
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"
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>
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.
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 |
When this option is used, the username and password will be generated randomly and therefore, the parameters username and password are not required.
When these parameters are passed in, the username and password will be set to the respective values and therefore not be generated randomly.
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
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>
Removes a consumer’s ability to access your site.
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 |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&custUsername=quarter&action=manualRemove&usingSubacc=0005&username=ccbill12&clientAccnum=923590
Return
"results" "1"
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>
Extends the length of an existing consumer subscription. The ‘extendLength’
parameter is used to extend the subscription by a number of days.
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 |
A success or failure code will be returned.
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"
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 Codes | |
---|---|
1 | The requested action was a success. |
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 |
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900100&username=myusername&password=mypassword&action=cancelSubscription&subscriptionId=1000000000&returnXML=1
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.
<?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>
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.
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900000&username=myusername&password=mypassword&action=discountSubscription&discountAmount=2.00&subscriptionId=0012946984374168
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.
"startPeriod","amount","discounts","discountInterval","type","startDate" "3","5.00","2","1","LOYALTY","20050222162551"
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.
CCBill API: Cancel Subscription
CCBill API: Advanced Dynamic Upgrades
CCBill API: One Click
CCBill API: Charge by Previous Transaction ID
This document is an Addendum to the CCBill API and discusses Merchant configuration of the CCBill API to implement sales of Subscription Tangibles.
The CCBill API is considered to be an Advanced Feature of CCBill’s system. This document assumes the following:
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.
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.
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.
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 |
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
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 |
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
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. |
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=getFulfillmentStatus&transactionId=12345678987654321&shipmentId=123456
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) |
"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 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>
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. |
Errors can be caused for any number of reasons, the most common being data validation errors. Here is a list of data validation performed by the Subscription Tangibles functions:
An error response will typically contain two parameters:
All possible errors, along with troubleshooting information, are included in this table:
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.
CCBill Background Post is a method of passing data between the merchant’s system and CCBill’s system. Background Post essentially serves two purposes:
These two applications of the Background Post system are mutually exclusive and neither is required to use the other.
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.
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.
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:
$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.<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:
Background Post contains a set of specified system variables that can be used to pull data from CCBill’s system. Two variable sets are used, one for each of the following situations:
In both cases, custom variables will be sent exactly as they were entered.
System variable names must be entered exactly as they appear in this list.
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 |
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 |
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 |
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.
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 |
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.
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:
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 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.
Our standard Subscription Management functions can be found in our CCBill API Guide.
Some examples are:
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.
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.
Dynamic Pricing includes the following default settings. Changes to these settings may be available. Please contact Merchant Support for more information.
The set of variables passed into the form will depend on the type of transaction. The following variables are required for both single and recurring transactions:
The following variables are required for recurring transactions only. Omitting these variables will result in a single billing transaction:
The formDigest value is a hex-encoded MD5 hash, calculated using a combination of the above fields and a salt value. The salt value is used by CCBill to verify the hash and can be obtained in one of two ways:
Using your preferred MD5 hash generation tool and the Hex encoding method, you will need to create an MD5 Hex Digest using certain variable values. Values should be concatenated into one single string with no spaces prior to hashing.
For single billing transactions, use the following values in the order they are listed:
formPrice formPeriod currencyCode salt
For recurring transactions, use the following values in the order they are listed:
formPrice formPeriod formRecurringPrice formRecurringPeriod formRebills currencyCode salt
The resulting MD5 hash will be used as the value for the formDigest variable. This value can be statically hard-coded into a page or generated “on the fly” using a custom script.
Note that the values for clientAccnum, clientSubacc, and formName are not used when creating the MD5 hash for either transaction type.
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>
Dynamic Pricing requests will return the responseDigestvalue using the Background Post system. This value is an MD5 hash of transaction results which can be used to verify that the response was received properly by CCBill.
The value for responseDigest will contain an MD5 hash of the following values for approved transactions, concatenated into a single string:
These values will be sent to the Approval Post URL.
The value for responseDigest will contain an MD5 hash of the following values for denied transactions, concatenated into a single string:
These values will be sent to the Denial Post URL.
For more information on Background Post, including the use of Approval/Denial Post URLs, consult the Background Post User’s Guide.
v.3 12.30.2014
CCBill Velocity Controls 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:
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.
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.