Loading...
 

CCBill API: Advanced Affiliate Options


Introduction

This document is provided as a technical resource for CCBill clients, discussing advanced affiliate options for CCBill API. This document is written for programmers, technicians, and others with advanced programming skills.

Overview

The CCBill API offers programming APIs to be used in conjunction with the Traffic Manager cascade functionality. The options described in this document are used to facilitate transaction events when a billing provider unsupported by CCBill’s cascade system processes a transaction for a sale referred by a CCBill affiliate, for which the payout was made by CCBill. For example, if a CCBill affiliate refers a sale to a CCBill client but the transaction was processed by another processor through the Traffic Manager cascade process, the affiliate can still be credited for the sale. CCBill would pay out to the affiliate even though the transaction was not processed through CCBill.

NOTE: These features are not intended to be used for transactions through processors supported by CCBill’s cascade system. Processors supported by the cascade system would typically handle the events described in this document; however, for situations where affiliate referral payouts were made by CCBill when CCBill did not process the transaction, these programming APIs are offered to manually initiate the events.

Implementation

Each of the options described in this guide require variables passed into the CCBill API CGI script. Two sets of variables must be included in each string request: the main parameters required for all CCBill API requests and the parameters. A list of variables and sample code follows.

Required (X) and Optional (O) Parameters

clientAccnum
userName
Password
clientSubacc
usingSubacc
returnXML
action
Main Account
X
X
X
O
O
O
X
Main Account w/XML
X
X
X
O
O
X
X
Sub Account
X
X
X
X
O
O
X
Sub Account w/XML
X
X
X
X
O
X
X

These parameters will be used in conjunction with each individual action below. Note that only one action can be performed at a time.

Actions

This section describes each advanced affiliate option in detail. The title of each of the following subsections will be used as the action parameter as shown in the sample code.
Return values are described later in this document.

addAffiliatePayout

This action allows clients to add a payout to an affiliate for a referred transaction that will not be processed by CCBill. Use the parameters below in addition to the main CCBill API parameters above.

Note that the usingSubacc parameter is required only for users authenticating using the main account. The clientSubacc parameter is required only for users authenticating under a specific subaccount. The two parameters below are required regardless of user
Parameter
Description
Example Value
affiliateId The affiliate ID number to which the rebill will be applied.
123456
amount The total amount of the sale in US dollars.
14.95

Sample code:

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=999999&clientSubacc=0000&username=user123&password=pass123&action=addAffiliateRebill&affiliateId=123456& originalSubId =1234567891&amount=14.95

addAffiliateRefund

This action issues a refund on the specified transaction. Use the following parameters in addition to the main CCBill API parameters above:
Parameter
Description
Example Value
affiliateId The affiliate ID number to which the rebill will be applied.
123456
subscriptionId The subscription ID for an already-existing cascaded transaction. This is the transaction that will be refunded.
1234567890
originalSubId The subscription ID of the original billing transaction. If you are refunding the original transaction, this value will be the same as subscriptionId above.
1234567891
transType The type of transaction being charged back.
SINGLE, RECURRING, or REBILL

Sample code:

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=999999&clientSubacc=0000&username=user123&password=pass123&action=addAffiliateChargeback&affiliateId=12345

Return Values

Each of the above functions returns a result value indicating success or failure. Results will be returned in either CSV or XML format, depending on whether or not the returnXML parameter is passed. CSV data is returned by default; for more information on the returnXML parameter, consult the CCBill API User Guide.

Regardless of the return method, a value of “1” will be returned for successful actions. Any other return value indicates an error. For a full list of error codes, consult the CCBill API User Guide.

CSV Return Example

"results" "1"

XML Return Example

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