Loading...
 

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:

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 email 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

SimpleMethodFlow.png

Advanced Method

AdvancedMethodFlow.png

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.

  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.