CCBill RESTful Transaction API

API Version: 1.0.0.3
Release Date: July 2018

Introduction

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

Scope

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

Requirements & Terminology

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

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

Terminology

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

Data Link API Account

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

Subscription Management System

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

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

Velocity Controls

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

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

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

CCBill Transaction API Objects

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

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

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

CreditCardPaymentInfo

Type CreditCardPaymentInfo

{
  "cardNum": "string",
  "expDate": "string",
  "nameOnCard": "string"
}
PARAMETERTYPEDESCRIPTION
cardNum (required)stringCard number
expDate (required)stringCard expiration date
nameOnCard (required)stringName as it appears on consumer's credit card

CustomerInfo

Type CustomerInfo

{
  "email": "string",
  "browserHttpAcceptLanguage": "string",
  "browserHttpUserAgent": "string",
  "city": "string",
  "browserHttpAccept": "string",
  "state": "string",
  "zipcode": "string",
  "customerFname": "string",
  "address1": "string",
  "address2": "string",
  "browserHttpAcceptEncoding": "string",
  "customerLname": "string",
  "ipAddress": "string",
  "phoneNumber": "string",
  "country": "string"
}
PARAMETERTYPEDESCRIPTION
email (required)stringCustomer's email address
browserHttpAcceptLanguagestringList of acceptable human languages for response
browserHttpUserAgentstringThe user agent string of the user agent
citystringCustomer's city
browserHttpAcceptstringMedia type(s) that is(/are) acceptable for the response
state (required)stringCustomer's state
zipcode (required)stringCustomer's zip code
customerFname (required)stringCustomer's first name
address1stringCustomer's address
address2stringCustomer's address (additional info)
browserHttpAcceptEncodingstringList of acceptable encodings
customerLname (required)stringCustomer's last name
ipAddress (required)stringCustomer's IP address
phoneNumberstringCustomer's phone number
country (required)stringCustomer's country

PassThroughEntry

Type PassThroughEntry

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

PaymentInfo

Type PaymentInfo

{
  "creditCardPaymentInfo": {
    "cardNum": "string",
    "expDate": "string",
    "nameOnCard": "string"
  }
}
PARAMETERTYPEDESCRIPTION
creditCardPaymentInfocreditCardPaymentInfoCredit card payment information
creditCardPaymentInfo. cardNum (required)stringCredit card number
creditCardPaymentInfo. expDate (required)stringCredit card expiration date
creditCardPaymentInfo. nameOnCard (required)stringName as it appears on credit card

PaymentToken

Type PaymentToken

{
  "createdDatetime": "datetime-only",
  "timeToLive": "integer",
  "originalPaymentTokenId": "string",
  "validNumberOfUse": "integer",
  "clientAccnum": "integer",
  "clientSubacc": "integer",
  "programParticipationId": "integer",
  "paymentTokenId": "string",
  "paymentInfoId": "string",
  "subscriptionId": "integer"
}
PARAMETERTYPEDESCRIPTION
createdDatetime (required)datetime-onlyDate and uime of creation of the Payment Token.
timeToLive (required)integerTime for the token to exist expressed in hours
originalPaymentTokenIdstringReference to a previous Token Id
validNumberOfUse (required)integerTotal number of times the Payment Token can be used for purchases
clientAccnum (required)integerMerchant account number
clientSubacc (required)integerMerchant subaccount number
programParticipationId (required)integerThe Program connected to the Payment Token
paymentTokenId (required)stringComplex representation of Payment Token Id
paymentInfoIdstringInformation associated with the payment
subscriptionId (required)integerIdentification of the subscription associated with the transaction

PaymentTokenMerchantOnlyParams

Type

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

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"customerInfo": {
		"customerFname": "Tyler",
		"customerLname": "Thomas",
		"address1": "Woodland Drive",
		"address2": "Apt 21",
		"city": "Tempe",
		"state": "AZ",
		"zipcode": "85281",
		"country": "US",
		"phoneNumber": "5555555555",
		"email": "tthomas@xyz.com",
		"ipAddress": "10.70.60.14'",
		"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
		"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
		"browserHttpAcceptLanguage": "en-US,en;q=0.5",
		"browserHttpAcceptEncoding": "gzip, deflate, br"
	},
	"paymentInfo": {
		"creditCardPaymentInfo": {
			"cardNum": "4473707989493598",
			"nameOnCard": "Tyler Thomas",
			"expDate": "201904"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}
PARAMETERTYPEDESCRIPTION
clientAccnum (required)integerMerchant account number
clientSubacc (required)integerMerchant subaccount number
customerInfocustomerInfoCustomer Information
customerInfo. email (required)stringCustomer's email address
customerInfo. browserHttpAcceptLanguagestringList of acceptable human languages for response
customerInfo. browserHttpUserAgentstringThe user agent string of the user agent
customerInfo. citystringCustomer's city
customerInfo. browserHttpAcceptstringMedia type(s) that is(/are) acceptable for the response
customerInfo. state(required)stringCustomer's state
customerInfo. zipcode (required)stringCustomer's zip code
customerInfo. customerFname (required)stringCustomer's first name
customerInfo. address1stringCustomer's address
customerInfo. address2stringCustomer's address (additional info)
customerInfo. browserHttpAcceptEncodingstringList of acceptable encodings
customerInfo. customerLname (required)stringCustomer's last name
customerInfo. ipAddress (required)stringCustomer's IP address
customerInfo. phoneNumberstringCustomer's phone number
customerInfo. country (required)stringCustomer's country
paymentInfopaymentInfoPayment Information
paymentInfo. cardNum (required)stringCard number
paymentInfo. expDate (required)stringCard expiration date
paymentInfo. nameOnCard (required)stringName as it appears on card
subscriptionIdintegerTransaction subscription identification number
timeToLiveintegerTime for the token to exist expressed in hours
validNumberOfUseintegerTotal number of times the Payment Token can be used for purchases

TransactionInfo

Type TransactionInfo

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

Example

{
  "errorCode": 200,
  "approved": true, 
  "paymentUniqueId": "53104f5a54d3d43254def41c29aedba8",
  "sessionId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
  "subscriptionId": 900000000000000001
}
PARAMETERTYPEDESCRIPTION
errorCode (required)integerError condition value of the transaction
approved (required)booleanApproval status of the transaction
paymentUniqueId (required)stringUnique key connected to a payment account
sessionId (required)stringUnique session ID value for transaction
subscriptionId (required)integersubscription ID to which the transaction belongs
newPaymentTokenId (required)stringNew payment token for subsequent transactions

TransactionRequest

Type TransactionRequest

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

Example

{
    "clientAccnum":900123,
    "clientSubacc":10,
    "initialPrice": 9.99,
	"initialPeriod": 10,
	"recurringPrice": 15.00,
	"recurringPeriod": 30,
	"rebills": 99,
	"currencyCode": 840,
	"lifeTimeSubscription": false,
    "createNewPaymentToken": false,
	"passThroughInfo": [
		{
			"name": "val1",
			"value": "val2"
		}
	]
}
PARAMETERTYPEDESCRIPTION
CreateNewPaymentTokenbooleanReturn a new payment token for subsequent transactions or not
initialPrice (required)numberPrice of the initial transaction
clientAccnum (required)integerClient account of the merchant
clientSubacc (required)integerClient subaccount of the merchant
lifeTimeSubscriptionbooleanA continual subscription with no end date or not
initialPeriod (required)integerTime period of the initial transaction
recurringPeriodintegerTime period of recurring transactions
currencyCodeintegerA numerical representation of the currency used in transaction
rebillsintegerThe number of times recurrent transactions can occur
recurringPricenumberPrice of recurrent transactions
passThroughInfoArray[any]Paired Information Passed Through to the Transaction Service

ValidationError

Type ValidationError

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

Error

Type Error

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

API Endpoints

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

HEADER NAMECONTENT-TYPE
Content-Typeapplication/json

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

Authentication and Authorization

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

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

See curl example below:

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

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

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

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

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

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

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

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

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

CVV2 and AVS Verification

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

Below is the paymentTokenVerify example:

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

CVV2 Responses

VALUEDESCRIPTION
MCVV2/CVC2/CID Match
NCVV2/CVC2/CID No Match
PNot Processed
SThe CVV2/CVC2/CID should be on the card, but the merchant indicates it is not.
UThe Issuer is not certified or has not provided Visa with encryption keys.

AVS Responses

VALUEDESCRIPTION
AThe street addresses matches but the postal/ZIP code does not, or the request does not include the postal/ZIP code.
BStreet addresses match. Postal code is not verified due to incompatible formats (both street address and postal code were sent.)
CStreet address and postal code not verified due to incompatible formats. (both street address and postal code were sent)
DStreet addresses and postal codes match
FStreet address and postal code match. (U.K.- issued cards)
GIssuer is not an AVS participant, or AVS data was present in the request but issuer did not return an AVS result, or Visa performs AVS on behalf of the issuer and there was no address record on file for this account.
OAddress information is not verified.
MStreet address and postal code match.
NNo match.Transaction contained Postal/ZIP code only, or street address only, or postal code and street address. Also used when transaction requests AVS but sends no AVS data.
PPostal codes match. Postal code and street address were sent, but street address not verified due to incompatible formats.
RRetry; System unavailable or timed out.
SAVS currently not supported
UNo data from Issuer/Authorization platform
VNine character postal code matches; address does not match
XNine character postal code and address match
YStreet address and postal code match
ZPostal/ZIP matches, street address does not match, or street address not included in request.
1Cardholder name and ZIP match
2Cardholder name, address, and ZIP match
3Cardholder name and address match
4Cardholder name matches
5Cardholder name incorrect, ZIP matches
6Cardholder name incorrect; address and ZIP match
7Cardholder name incorrect, address matches
8Cardholder name, address, and ZIP do not match

/payment-tokens Endpoint

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

SUB-RESOURCESMETHODSDESCRIPTION
/payment-tokens/merchant-onlyPOSTResource used for creating payment tokens that are not tied to a specific Merchant Connect Program
/payment-tokens/merchant-only-verifyPOSTResource used for creating payment tokens with CVV2 and AVS verification

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

Resource used for creating a payment token.

Headers

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

Body

Type PaymentTokenMerchantOnlyParams

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

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"customerInfo": {
		"customerFname": "Tyler",
		"customerLname": "Thomas",
		"address1": "Woodland Drive",
		"address2": "Apt 21",
		"city": "Tempe",
		"state": "AZ",
		"zipcode": "85281",
		"country": "US",
		"phoneNumber": "5555555555",
		"email": "tthomas@xyz.com",
		"ipAddress": "10.70.60.14'",
		"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
		"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
		"browserHttpAcceptLanguage": "en-US,en;q=0.5",
		"browserHttpAcceptEncoding": "gzip, deflate, br"
	},
	"paymentInfo": {
		"creditCardPaymentInfo": {
			"cardNum": "4473707989493598",
			"nameOnCard": "Tyler Thomas",
			"expDate": "201904"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}
PARAMETERTYPEDESCRIPTION
programId (required)integerThe ID of the program. Example value: 123
participantAccount (required)stringThe account number of the participant/affiliate merchant. The value is comprised of the account and subaccount separated by a dash. Example value: 900000-1234

Result Format


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

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

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

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

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

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

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

The response failed to complete due to authorization problem.

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

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

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

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

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

The response failed to complete due to an invalid resource.

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

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

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

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

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

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

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

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

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

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

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

The response failed to complete in some way.

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

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

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

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

Headers

PARAMETERTYPEDESCRIPTION
Accept (required)stringAPI version. Example value: application/vnd.mcn.transaction-service.api.v.1+json, application/vnd.mcn.transaction-service.api.v.2+json

Body

Type PaymentTokenMerchantOnlyVerifyParams

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

Example

{
	"clientAccnum": 900000,
	"clientSubacc": 0,
	"customerInfo": {
		"customerFname": "Tyler",
		"customerLname": "Thomas",
		"address1": "Woodland Drive",
		"address2": "Apt 21",
		"city": "Tempe",
		"state": "AZ",
		"zipcode": "85281",
		"country": "US",
		"phoneNumber": "5555555555",
		"email": "tthomas@xyz.com",
		"ipAddress": "10.70.60.14'",
		"browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
		"browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
		"browserHttpAcceptLanguage": "en-US,en;q=0.5",
		"browserHttpAcceptEncoding": "gzip, deflate, br"
	},
	"paymentInfo": {
		"creditCardPaymentInfo": {
			"cardNum": "4473707989493598",
			"nameOnCard": "Tyler Thomas",
			"expMonth": "04",
			"expYear": "2019",
			"cvv2": "123"
		}
	},
	"subscriptionId":900000000000000001,
	"timeToLive": 30,
	"validNumberOfUse": 3
}
PARAMETERTYPEDESCRIPTION
programId (required)integerThe ID of the program. Example value: 123
participantAccount (required)stringThe account number of the participant/affiliate merchant. The value is comprised of the account and subaccount separated by a dash. Example value: 900000-1234

Result Format


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

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

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

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

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

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

The response failed to complete due to authorization problem.

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

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

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

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

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

The response failed to complete due to an invalid resource.

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

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

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

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

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

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

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

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

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

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

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

The response failed to complete in some way.

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

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

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

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

Parameters

PARAMETERTYPEDESCRIPTION
paymentTokenId (required)string

Headers

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

Result Format


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

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

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

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

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

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

The response failed to complete due to authorization problem.

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

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

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

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

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

The response failed to complete due to an invalid resource.

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

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

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

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

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

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

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

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

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

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

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

The response failed to complete in some way.

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

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

/transactions Endpoint

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

SUB-RESOURCESMETHODSDESCRIPTION
/transactions/payment-tokens/{payment_token_id}GET & POSTSubresource used to bill a client, or retrieve details about a charge.

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

Post Method CCBill RestFul API. /transactions/payment-tokens/{payment_token_id}

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

Supply the payment token ID as a URI parameter.

Parameters

PARAMETERTYPEDESCRIPTION
payment_token_id (required)stringThe payment token ID.

Header

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

Body

Type TransactionRequest

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

Example

{
    "clientAccnum":900123,
    "clientSubacc":10,
    "initialPrice": 9.99,
	"initialPeriod": 10,
	"recurringPrice": 15.00,
	"recurringPeriod": 30,
	"rebills": 99,
	"currencyCode": 840,
	"lifeTimeSubscription": false,
    "createNewPaymentToken": false,
	"passThroughInfo": [
		{
			"name": "val1",
			"value": "val2"
		}
	]
}
PARAMETERTYPEDESCRIPTION
createNewPaymentTokenbooleanreturn new payment token for subsequent transactions or not
initialPrice (required)numberprice of initial transaction
clientAccnum (required)integerclientAccnum of the merchant
clientSubacc(required)integerclientSubacc of the merchant
lifeTimeSubscriptionbooleansubscription is eternal or not.
initialPeriod(required)integertime period of initial transaction
recurringPeriodintegertime period of recurrent transactions
currencyCodeintegernumerical representation of the currency used in a transaction
rebillsintegernumber of times recurrent transactions can occur
recurringPricenumberprice of recurrent transactions
passThroughInfoArray[any]Paired Information Passed Through to the Transaction Service

Result Format


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

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

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

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

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

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

The response failed to complete due to authorization problem.

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

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

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

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

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

The response failed to complete due to an invalid resource.

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

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

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

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

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

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

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

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

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

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

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

The response failed to complete in some way.

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

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

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

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

Supply the payment token ID as a URI parameter.

Parameters

PARAMETERTYPEDESCRIPTION
payment_token_id (required)stringThe payment token ID.

Headers

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

Result Value


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

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

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

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

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

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

The response failed to complete due to authorization problem.

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

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

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

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

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

The response failed to complete due to an invalid resource.

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

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

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

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

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

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

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

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

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

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

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

The response failed to complete in some way.

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

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