CCBill API: One Click
Introduction
This document is an Addendum to the CCBill API and discusses both Sponsor Merchant and Affiliate Merchant configuration of the CCBill API functions required for implementation of the One-Click Cross Sale feature now supported by the CCBill API. Make sure to read the Best Practices section at the end of this document to minimize the risk of chargebacks and revenue loss.
This document should also be used by merchants using the OneClick Network to assist developers with the API integration methods required to implement that system by both Sponsor Merchants and Affiliate Merchants.
Scope
The CCBill API is considered to be an Advanced Feature. As such this document assumes the following:
- The user has already enabled the CCBill API.
- The user possesses intermediate to advanced programming skills.
- The user possesses the programming skills necessary to create scripts and implement them in the context of this document.
- The user possesses knowledge of SOAP, HTML, XML and other web development technologies.
- The user has already received permission for and enabled Web Marketing Service (WMS), and One-Click Cross Sales on their account (these requirements are described further in the One-Click Cross Sale User’s Manual).
- The user has already set up User Management, if desired.
Terminology
The One-Click Cross Sale feature places Merchants into roles not previously available to CCBill Merchants, requiring the introduction of two new terms as follows:
- Sponsor Merchant. The Sponsor Merchant is a Merchant that wants to have other Merchants refer sales to them using the One-Click Cross Sale feature.
- Affiliate Merchant. The Affiliate Merchant is a Merchant who assumes the role of an Affiliate in order to use One-Click Cross Sales to refer its existing consumers to a Sponsor Merchant in exchange for a portion of the revenue generated by that sale.
Support for CCBill Velocity Controls
CCBill Velocity Controls is an advanced feature of the CCBill API, 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.
Overview
The CCBill API is adding functionality that allows Affiliate Merchants to refer sales to Sponsor Merchants. Proper implementation of the One-Click Cross Sales API will have the result of the Affiliate Merchant being able to refer current consumers through their member’s area, allowing the consumer to make the purchase on the Sponsor Merchant’s site without having to enter in payment or user information in most instances.
Implementation
The implementation of the One-Click Cross Sale API 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.
Methods
There are two basic methods of One-Click Cross Sale implementation:
- Advanced Method. This method is preferred. The Advanced Method requires the Affiliate Merchant’s full integration with both CCBill API and User Management but provides the most seamless experience for consumers.
- Simple Method. The Simple Method is easier to implement for Affiliate Merchants, but may result in more consumer intervention; including ID verification and/or re-entering payment and user information. There are two sub-options available for the Simple Method:
- With Subscription ID requires the least Affiliate Merchant intervention
- With Username requires Affiliate Merchant integration with User Management
Advanced Method
The Advanced Method requires Affiliate Merchants to fully integrate with the CCBill API. The Affiliate then uses the “Get Cross Sale Token” calls in the CCBill API to generate and return an authenticated token via a script that makes these calls every time the consumer is presented with the marketing material for the program. WMS then replaces that token with a modified version that contains the WMS 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.
This method, although more programming-intensive, creates a more seamless experience for the user. It does, however, require more work from your Affiliate Merchants.
Simple Method
The Simple Method requires less programming from Affiliate Merchants to implement, but results in more input from the consumer in order to complete the purchase.
In the Simple Method Affiliate Merchants attach identifying information about the subscription holder to the WMS link code instead of generating a CCBill API token. The consumer is directed through WMS 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 WMS.
API Integration
- The One-Click Cross Sale API is implemented as SOAP Call. The access point is https://bill.ccbill.com/dss.
- Responses are in SOAP format and contain errorCode and errorDesc along with additional information, if applicable.
- All operations include the following parameters for authentication purposes:
| authenticationInfo | ||
|---|---|---|
| MerchantAccnum | Integer | CCBill Merchant Account Number |
| MerchantSubacc | Short | CCBill Merchant Subaccount Number |
| usingMerchantSubacc | Short | CCBill Merchant Subaccount Number (when applicable and MerchantSubacc is null) |
| username | String | CCBill API Username |
| password | String | CCBill API Password |
Sponsor Merchant Functions
getCrossSaleSessionInfo/getCrossSaleTokenInfo
| IN | authenticationInfo | ||
| IN | sessionId/tokeninfo | string | sessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant; tokeninfo is a transient data object that includes information that will be used to either create or lookup a session. |
| OUT | string | Email address on record for the Affiliate Merchant's consumer. | |
| OUT | isAuthLocked | byte | 1 = Consumer has failed too many times to be authen ticated and must try again later; 0 = Consumer has not exhausted their authentication attempts |
| OUT | isAuthenticated | byte | 1 = Consumer Validated their Postal Code or this was an advanced token; 0 = Consumer hasn't validated their Postal Code, their validation window has expired, or an advanced token has expired. |
| OUT | authenticationUrl | string | If isAuthenticated = 0, the user will need to be redirected to this URL to validate their identity; The following parameters can be passed through to this system: *url = URL to redirect to upon successful validation (if not provided will redirect to the HTTP_REFERER) *failureUrl = URL to redirect to upon failed validation (if not provided will redirect to "url" parameter) |
| OUT | isUserCreated | byte | 1 = Sponsor has successfully registered a user for the consumer using the createUserForCrossSale method; 0=Sponsor has not yet registered a user for the consumer using the createUserForCrossSale method. |
| OUT | paymentUniqueId | string | Uniquely identifies a particular payment account (credit card/exp date, ACH account/routing number) utilizing a hashing algorithm. Often used by Sponsor Merchants for fraud purposes. |
| OUT | programParticipationId | integer | The unique identifier that signifies the relationship between an Affiliate Merchant and a Sponsor Merchant's program. |
| OUT | sessionId | string | Same as above. |
| OUT | errorCode | integer | 0 = There was no error; see Appendix A: Error Codes and Descriptions for a list of other possible codes. |
| OUT | errorDesc | string | Description of the returned error; see Appendix A: Error Codes and Descriptions for a list of possible descriptions. |
| OUT | subscriptionId | integer | If this is present the Sponsor Merchant has processed at least one sale with this session. The subscriptionId provided was the first sale processed. |
Example
<soapenv:Envelope> <soapenv:Body> <q0:getCrossSaleTokenInfoRequest> <authenticationInfo> <MerchantAccnum>9000000</MerchantAccnum> <username>user</username> <password>test1234</password> </authenticationInfo> <tokenInfo>4OJ3K6i63IOtc0Czanbz5m2boEiaFf+lE2prv1bPkXQ=</tokenInfo> </q0:getCrossSaleTokenInfoRequest> </soapenv:Body> </soapenv:Envelope>
Response:
<soap:Envelope> <soap:Body> <getCrossSaleTokenInfoResponse> <response> <errorCode>0</errorCode> <email>xxxx@ccbill.com</email> <isAuthLocked>0</isAuthLocked> <isAuthenticated>1</isAuthenticated> <isUserCreated>0</isUserCreated> <paymentUniqueId>/PvvoUQCmc3WoTssCZawbQ</paymentUniqueId> <programParticipationId>4240</programParticipationId> <sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId> <subscriptionId>0106100101000000001</subscriptionId> </response> </getCrossSaleTokenInfoResponse> </soap:Body> </soap:Envelope>
paymentInfo
| IN | authenticationInfo | |||
| IN | sessionId/tokeninfo | string | sessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant; tokeninfo is a transient data object that includes information that will be used to either create or lookup a session. | |
| IN | initialPrice | integer | Amount of the initial charge. Based on two implied decimals. For example, $2.95 should be passed as 295. | |
| IN | initialPeriod | integer | Length of the initial term of the subscription in days. | |
| IN | recurringPrice | integer | Optional | Amount of each recurring charge. Based on two implied decimals. For example, $29.95 should be passed 2995. |
| IN | recurringPeriod | integer | Optional | Length of the recurring term of the subscription in days. |
| IN | rebills | short | Optional | Number of times to rebill the subscription before the subscription ends (99 for unlimited). |
| IN | currencyCode | short | Optional | ISO 4217 Numeric Currency code (i.e., US Dollars = 840); Defaults to 840. |
chargeCrossSaleBySession/chargeCrossSaleByToken
| IN | passThrough pairs | name/value pairs | Optional | Miscellaenous data that the Sponsor can pass in during the signup process that will be provided back to them in the approval/denial background posts. |
| OUT | approved | byte | 0 = Declined, 1 = Approved. | |
| OUT | paymentUniqueId | string | Uniquely identifies a particular payment account (i.e., credit card/exp date, ACH account/routing number) utilizing a hashing algorithm. Some Merchants use this for fraud purposes on their side. | |
| OUT | sessionId | string | sessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant. | |
| OUT | subscriptionId | string | The Subscription ID of the newly processed transaction (assuming it was approved). | |
| OUT | denialId | integer | The unique descriptor of the ID. | |
| OUT | declineCode | integer | The decline code provided by the credit card processor. | |
| OUT | declineText | string | Present if the transaction is declined; provides a description about why the transaction was declined. | |
| OUT | authenticateUrl | string | Present if the token/session is unauthenticated. If isAuthenticated = 0, the user will need to be redirected to this URL to validate their identity; The following parameters can be passed through to this system: * url = URL to redirect to upon successful validation (if not provided will redirect to the HTTP_REFERER) * failureUrl = URL to redirect to upon failed validation (if not provided will redirect to "url" parameter) |
Example
<soapenv:Envelope> <soapenv:Body> <q0:chargeCrossSaleBySessionRequest> <authenticationInfo> <MerchantAccnum>900000</MerchantAccnum> <usingMerchantSubacc>0000</usingMerchantSubacc> <username>testuser</username> <password>test1234</password> </authenticationInfo> <sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId> <paymentInfo> <initialPrice>1000</initialPrice> <initialPeriod>30</initialPeriod> </paymentInfo> <passThroughInfo> <pairs> <name>field1</name> <value>value1</value> </pairs> </passThroughInfo> </q0:chargeCrossSaleBySessionRequest> </soapenv:Body> </soapenv:Envelope>
Response:
<soap:Envelope> <soap:Body> <chargeCrossSaleBySessionResponse> <response> <errorCode>0</errorCode> <approved>1</approved> <paymentUniqueId>/PvvoUQCmc3WoTssCZawbQ</paymentUniqueId> <sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId> <subscriptionId>910089201000000023</subscriptionId> </response> </chargeCrossSaleBySessionResponse> </soap:Body> </soap:Envelope>
createUserForCrossSaleSession/createUserForCrossSaleToken
| IN | authenticationInfo | |||
| IN | sessionId/tokeninfo | string | sessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant; tokeninfo is a transient data object that includes information that will be used to either create or lookup a session. | |
| IN | SponsorMemberUsername | string | Optional | The username the Sponsor Merchant added to their website and provided to us utilizing the createUserForCrossSaleToken or createUserForCrossSaleSession methods. |
| IN | SponsorMemberPassword | string | Optional | Same as SponsorMemberUsername, except for the password. |
| OUT | sessionId | string | sessionId represents a unique identifier for the consumer relationship between the Affiliate Merchant and the Sponsor Merchant. |
Example
<soapenv:Envelope> <soapenv:Body> <q0:createUserForCrossSaleSessionRequest> <authenticationInfo> <MerchantAccnum>900000</MerchantAccnum> <username>testuser</username> <password>test1234</password> </authenticationInfo> <sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId> <SponsorMemberUsername>TEST</SponsorMemberUsername> <SponsorMemberPassword>TEST</SponsorMemberPassword> </q0:createUserForCrossSaleSessionRequest> </soapenv:Body> </soapenv:Envelope>
Response:
<soap:Envelope> <soap:Body> <createUserForCrossSaleSessionResponse> <response> <errorCode>0</errorCode> <sessionId>kmEEyxSst43rIx0Quj4RyA</sessionId> </response> </createUserForCrossSaleSessionResponse> </soap:Body> </soap:Envelope>
Affiliate Merchant Functions
generateSessionForCrossSale
| IN | authenticationInfo | |||
| IN | subscriptionId | integer | Optional | The Subscription ID that the Affiliate Merchant wishes to create the token from. |
| IN | AffiliateMemberUsername | string | Optional | The Username that the Affiliate Merchant wishes to include in the token (will be overriden with what we have on record if they're using our user management). |
| IN | AffiliateMemberPassword | string | Optional | The Password that the Affiliate Merchant wishes to include in the token (will be overriden with what we have on record if they're using our user management). |
| OUT | tokeninfo | string | The authenticated token that's created based on the information above that they will utilize to forward the consumer through WMS to the Sponsor's website. |
Example
<soapenv:Envelope> <soapenv:Body> <q0:generateSessionForCrossSaleByTokenRequest> <authenticationInfo> <MerchantAccnum>900000</MerchantAccnum> <username>testuser</username> <password>test1234</password> </authenticationInfo> <subscriptionId>0910089201000000022</subscriptionId> </q0:generateSessionForCrossSaleByTokenRequest> </soapenv:Body> </soapenv:Envelope>
Response:
<soap:Envelope> <soap:Body> <generateSessionForCrossSaleByTokenResponse> <return> <errorCode>0</errorCode> <tokeninfo>4OJ3K6i63IOtc0Czanbz5thajxTbspyOu7DBqLoLt9w%3D</tokeninfo> </return> </generateSessionForCrossSaleByTokenResponse> </soap:Body> </soap:Envelope>
One-Click Cross Sale API Flow Charts
Simple Method
Advanced Method
Appendix A: Error Codes and Descriptions
| Error Code | Error Description |
|---|---|
| -101 | Invalid Subscription ID |
| -102 | Invalid Program Participation ID |
| -103 | Session not Found |
| -104 | Session is not Authenticated |
| -105 | Subscription ID not Present |
| -106 | System Error |
| -107 | User Already Created |
| -108 | Transaction Declined |
| -109 | Invalid Subscription |
| -110 | Unable to Verify Subscription |
| -111 | Unable to Find Customer Info |
| -112 | Invalid Merchant Subaccount |
| -113 | Invalid Recurring Info |
Best Practices
CCBill’s 1-Click API’s allow merchants to offer their customers with a convenient upgrade billing solution which enables customers from having to re-enter their payment details on subsequent purchases. The API’s are managed by the merchant and transactions are initiated by the consumers within the merchant’s website or member’s area. While these can be very convenient and useful tools, they do not come without added risk. The merchant is required to manage much of the consumer experience, and the API’s are designed to bypass CCBill’s authentication system, V-Scrub.
As a result, it is imperative for the merchant to understand their responsibilities and implement a system of controls designed to manage the consumer experience and minimize the risk of chargebacks and revenue loss.
While each merchant’s business model is inherently unique, and controls they implement may differ, the following best practices act as a guide for merchants who process 1-Click transactions.
- Consumer Disclosure: Increase consumer education and awareness throughout the payment process and website.
- Clear Pricing Descriptions throughout the upgrade process. Prices should include the proper currency, accurate value of credits/tokens, and should display any other terms relevant to the purchase.
- The purchase button should be action oriented to ensure the consumer is aware they are initiating a purchase.
- Clear Approval/Denial Messaging: The consumer should be made aware of the approval/denial immediately within the member’s area, and confirmation emails should be sent.
- 1-Click Environment Education: Consumers need to understand they can initiate charges against their account with the click of a button. In addition to clear messaging, some merchants may want to ensure their customers can opt-in and opt-out of the 1-click environment.
- Refund Policy: The merchant’s refund policy should be easy to locate on the website, and should clearly instruct consumers what issues may result in a refund if they run into issues with their purchase.
- Billing Descriptors should reinforced in the upgrade process and in confirmation emails. The merchant’s support page should also provide reinforcement of the descriptors.
- Support Information should be prevalent throughout the entire website to ensure customers can contact support for any issue with their service.
- Velocity Controls: The 1-click API’s do not limit transaction volume, and the transactions are not scrubbed for risk.
- New Customers vs. Existing: Treat new customers with added scrutiny by limiting their transactions in a given period of time. For example, a new customer should only be allowed to purchase 4 transactions within the initial 30 days.
- Existing Customers who have proven to be low risk can also be asked to revalidate their data after a higher number of transactions. For example, the customer has to opt back into the 1-click agreement after 20 transactions.
- Affiliate/Traffic Source Monitoring: The merchant should report refund and chargeback activity to their traffic sources to ensure they are being appropriately managed from month to month.
- Affiliates/Traffic sources with high chargeback rates should be terminated.
- Delay payouts with new affiliate/traffic sources to ensure transactions can be reviewed prior to paying the affiliate. If high risk patterns are detected, delay the payout to ensure refunds and chargebacks can clear.
Note: This may take up to 120 days
- Model/Cam Studio Monitoring: The merchant should report refund and chargeback activity to their model and cam studio sources to ensure they are being appropriately managed from month to month.
- Model/Cam Studio sources with high chargeback rates should be terminated.
- Delay payouts with new model/cam studio sources to ensure transactions can be reviewed prior to paying the affiliate. If high risk patterns are detected, delay the payout to ensure refunds and chargebacks can clear.
Note: This may take up to 120 days
- Post Transaction Monitoring: The merchant should verify a consumer if higher risk patterns or behavior is detected.
- Review customers' credit/token usage patterns. New customers who do not use tokens or credits upon payment should be considered high risk.
- Review IP’s associated with logins and compare to purchase IP’s. Differences should be considered high risk.
- High dollar amounts spent in shorter periods of time should be reviewed to ensure legitimacy.