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

Sponsor Merchant Functions

getCrossSaleSessionInfo/getCrossSaleTokenInfo

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

chargeCrossSaleBySession/chargeCrossSaleByToken

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

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

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

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.

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

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

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

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

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

---