Integrate with Fusebill's API to Automate Invoices, Payments and Collections

Dive into our comprehensive Documentation, API Reference and Tutorials to start working with the Fusebill Subscription Billing platform. Connect easily with Fusebill support to help get your integrations to market as quickly and as seamlessly as possible.

Get Started

Create Credit Card Payment Method

This endpoint is for creating a credit card via AJAX transparent redirect. Unlike the basic version, this endpoint will not return any HTML and does not take a success/failure URL. This grants more flexibility for handling the response to the call.

In order to succeed, this call must be made from a whitelisted domain. Please contact Fusebill support to add or remove a domain from this whitelist. You can view the whitelisted domains for your account under Settings > Integrations > Transparent Redirect

📘

Add Credit Card

POST https://payments.subscriptionplatform.com/api/paymentsv2

🚧

Note

If you are adding the first payment method on a customer, it will be set to the default payment method automatically. This is true even if makeDefault is set to false.

Request Parameters

Property

Type

Description

Required

customerID

Number

This is the Fusebill generated customer ID of the customer you wish to add the card to.

Yes

publicApiKey

String

This is your public API key. It can be found under Settings > Integrations > Transparent Redirect

Yes

cardNumber

String

This is the credit card number

Yes

firstName

String

This is the first name of the cardholder.
[Max Length: 50 characters]

Yes

lastName

String

This is the last name of the cardholder.
[Max Length: 50 characters]

Yes

expirationMonth

Number (1-12)

This is the month the credit card expires.

Yes

expirationYear

Number

This is the year the credit card expires. format: YY

Yes

cvv

String

The card verification number. It is a common mistake to take this in as integer and convert it to a string. This will drop leading zeros and can cause validation to fail.

Yes

email

String

Mandatory when using Fusebill Payments*

Yes, if using Fusebill Payments*

clientIP

String

Mandatory when using Fusebill Payments*

Yes, if using Fusebill Payments*

riskToken

String

Mandatory when using Fusebill Payments*

Yes, if using Fusebill Payments*

makeDefault

Boolean

If true, forces this payment method to become the customer's default.

Optional. False by default

recaptcha

String

The recaptcha token response.

Yes

address1

String

Standard line 1 of an address. This is for the address of the cardholder. [Max Length: 50 characters]

Conditional**

address2

String

Standard line 2 of an address. This is for the address of the cardholder. [Max Length: 50 characters]

Conditional**

city

String

This is the city for the address of the cardholder. [Max Length: 50 characters]

Conditional**

stateId

Number

This is the Fusebill generated state code. Call Read Country ID to find the appropriate code. This is for the state of the cardholder

Conditional**

countryId

Number

This is the Fusebill generated country code. Call Read Country ID to find the appropriate code. This is for the country of the cardholder.

Conditional**

postalZip

String

The postal code or zip code of the cardholder.

Conditional**

paymentCollectOptions

Object. Defined Below

If the card is validated successfully, this object is used to collect a specified amount

Optional

*For a full explanation, see Fusebill Payments API Risk Fields
**These fields are required if Address Verification Services (AVS) are being used. They may also be required depending on your account's credit card gateway.

Payment Collect Options Object

Property

Type

Description

collectionAmount

Decimal

The amount to be collected

🚧

Security - Public API Key

As the name implies, the public API key does not need to be hidden from your end users, and is not for security. This is in contrast to your private API key which is used as authentication for virtually all other Fusebill API endpoints. Your account's private API key should never be visible to your end users.

Sample Request - x-www-form-urlencoded and JSON

POST https://payments.subscriptionplatform.com/api/paymentsv2/?CustomerId=12345678&PublicApiKey=123-abc-456-def&CardNumber=4242424242424242&FirstName=Karen&LastName=Wood&ExpirationMonth=12&ExpirationYear=23&Cvv=123&Address1=10+Dodge+St&Address2=Unit+B&City=Columbia&CountryId=124&StateId=1&PostalZip=V9C9V9&MakeDefault=true&Recaptcha=abc123def456&PaymentCollectOptions.collectionAmount=0.50
POST https://payments.subscriptionplatform.com/api/paymentsv2
{
  "customerId": 12345678,
  "PublicApiKey":"123-abc-456-def",
  "cardNumber": "4242424242424242",
  "firstName": "Karen",
  "lastName": "Wood",
  "expirationMonth": 2,
  "expirationYear": 23,
  "cvv": "123",
  "makeDefault": true,
  "recaptcha": "abc123def456",
  "address1": "10 Dodge St",
  "address2": "Unit B",
  "city": "Columbia",
  "stateId": 1,
  "countryId": 124,
  "postalZip": "V9V 9V9",
  "paymentCollectOptions":{
    "collectionAmount":0.50
  }
}

Sample Response

{
    "maskedCardNumber": "************4242",
    "cardType": "Visa",
    "expirationMonth": 2,
    "expirationYear": 23,
    "customerId": 2563146,
    "firstName": "Karen",
    "lastName": "Wood",
    "address1": "10 Dodge St",
    "address2": "Unit B",
    "countryId": 124,
    "country": "CAN",
    "stateId": 1,
    "state": "Alberta",
    "city": "Columbia",
    "postalZip": "V9V 9V9",
    "isDefault": true,
    "externalCustomerId": null,
    "externalCardId": null,
    "storedInFusebillVault": true,
    "email": null,
    "modifiedDate": "2020-05-22T04:50:27.211012Z",
    "originalPaymentMethodId": null,
    "id": 469910,
    "uri": null
}
{
    "ErrorId": 0,
    "HttpStatusCode": 400,
    "Errors": [
        {
            "Key": "Api Error",
            "Value": "There was an error validating the payment method: Failed validation"
        }
    ]
}

Google ReCAPTCHA

Fusebill leverages reCAPTCHA technology to ensure payment method data captured is provided by a human and to protect against bots and scripting.

We use Google reCAPTCHA V2 in order to accomplish this.
https://developers.google.com/recaptcha/intro

The basic workflow for how this is accomplished is as follows:
Using Fusebill's public site key, the client is presented with a captcha widget.
The user then verifies that they are human, starting with a check box. The user may be presented with additional verification steps such as an image recognition task.
The captcha widget then verifies with Google that the user is human, and returns a response token.
That response token is then sent to Fusebill with the payment method data for our system to validate and verify.

Fusebill Environment

reCAPTCHA Public Site Key

Staging (stg-payments.subscriptionplatform.com)

6LcI_GwUAAAAAJZu0VvB68DdxNxb5ZcBIwAX7RVj

Sandbox and Production (payments.subscriptionplatform.com)

6LfVtGwUAAAAALHn9Ycaig9801f6lrPmouzuKF11

(Optional) Use Your Own ReCAPTCHA

Rather than use Fusebill's public site key, you can configure your own.

  • Go to https://www.google.com/recaptcha and create an account. In the register a new site area, add a reCaptcha v2. At this stage you can choose invisible reCAPTCHA if that is your preferred approach. Register. If you don’t want to validate against a domain, you’ll need to open the advanced settings and uncheck the domain name validation.

  • In the Keys section you should have a site key and secret key, you’ll need both.

  • Login to your Fusebill account and go to Settings > Integrations > Transparent Redirect
    https://admin.fusebill.com/Integrations/TransparentRedirectConfigurations.

  • Select the “use your ReCAPTCHA” and enter the secret key.  Save

  • On your payment method form, just update the site key with your new one.

Sample Code For Testing

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>AJAX Transparent Redirect</title>
        <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
        
        <script>
      var verifyCallback = function(response) {
        document.getElementById("mySubmit").disabled = false;
        $('input#recaptcha_token').val(response);
      };
      var expCallback = function () {
        document.getElementById("mySubmit").disabled = true;
        grecaptcha.reset();
      };
      var onloadCallback = function() {
        grecaptcha.render('exampleWithCallback', {
          'sitekey': '<Public Site Key>', //replace with fusebill google public key
          'callback': verifyCallback,
          'expired-callback': expCallback
        });
      };
      
            function AJAXTransparentRedirect() {                                 
                var dataString = 'CustomerId='+ $('input#CustomerId').val() + 
                        '&PublicApiKey=' + $('input#PublicApiKey').val() + 
                        '&CardNumber='+$('input#CardNumber').val() + 
                        '&FirstName='+$('input#FirstName').val() + 
                        '&LastName='+$('input#LastName').val() + 
                        '&ExpirationMonth='+$('input#ExpirationMonth').val() + 
                        '&ExpirationYear='+$('input#ExpirationYear').val() + 
                        '&makeDefault='+$('input#MakeDefault').val() + 
                        '&Cvv='+$('input#Cvv').val() +
                        '&recaptcha=' + $('input#recaptcha_token').val();
                alert(dataString);

                //Set up the request
                var request = $.ajax({
                    type: "POST",
                    url: "https://payments.subscriptionplatform.com/api/paymentsv2/",                   
                    data: dataString 
                });

                //Set up the callback functions
                request.done(function (msg) {
                    //$('#response').append("<br><p>success </p>");
                    alert("success");
                    //document.location.replace = '';
                });

                request.fail(function (jqXHR) {
                    // $('#response').append("<br><p>failure</p>");
                    alert(parseAndBuildErrorMessage(jqXHR));
                    //document.location.replace = '';
                    expCallback();
                });
            }

            function htmlEscape(msg) {
            return document.createElement('span')
                .appendChild(document.createTextNode(msg))
                .parentNode
                .innerHTML;
            }

            function buildErrorMessage (errors) {
                if (errors.length == 0) {
                    return "";
                }

                var message;
                    if (errors.length > 1) {
                        message = "<ul>";

                        for (var i = 0; i < errors.length; i++) {
                            if (errors[i].Value != "") {
                                message += "<li>" + htmlEscape(errors[i].Value) + "</li>";
                            }
                        }

                        message += "</ul>";
                    } else {
                    var internalErrors = errors[0].Value;
                    internalErrors = internalErrors.split("\r\n");

                    if (internalErrors.length > 1) {
                        message = "<ul>";
                        for (var i = 0; i < internalErrors.length; i++) {
                            if (internalErrors[i].Value != "") {
                                message += "<li>" + htmlEscape(internalErrors[i]) + "</li>";
                            }

                            message += "</ul>";
                        }
                    } else {
                        message = htmlEscape(errors[0].Value);
                    }
                }

                return message;
            }                             

            function parseAndBuildErrorMessage (xhr) {
                if (xhr.status >= 500)
                    return "An error occurred, please try again";
                else
                    return buildErrorMessage(xhr.responseJSON.Errors);
            }

        </script>
    </head>
    
    <body>
        <form id="allfields">
            <fieldset>
                <div>
                <label for="CustomerId">Customer Id</label>
                <input autofocus="autofocus" id="CustomerId" name="CustomerId" type="text" value="your customer id here" />
                </div>

                <div>
                <label for="PublicApiKey">Public Api Key</label>
                <input id="PublicApiKey" name="PublicApiKey" type="text" value="your key here" />
                </div>

                <div>
                <label for="CardNumber">Card number</label>
                <input id="CardNumber" name="CardNumber" type="text" value="4111111111111111" />
                </div>

                <div>
                <label for="FirstName">First name</label>
                <input id="FirstName" name="FirstName" type="text" value="John" />
                </div>

                <div>
                <label for="LastName">Last name</label>
                <input id="LastName" name="LastName" type="text" value="Doe" />
                </div>

                <div>
                <label for="ExpirationMonth">Expiry month</label>
                <input id="ExpirationMonth" name="ExpirationMonth" type="text" value="12" />
                </div>

                <div>
                <label for="ExpirationYear">Expiry year</label>
                <input id="ExpirationYear" name="ExpirationYear" type="text" value="23" />
                </div>

                <div>
                <label for="Cvv">CVV</label>
                <input id="Cvv" name="Cvv" type="text" value="123" />
                </div>

                <div>
                <label for="MakeDefault">MakeDefault</label>
                <input id="MakeDefault" name="MakeDefault" type="text" value="true" />
                </div>
       
       <div class="g-recaptcha" id="exampleWithCallback"></div>
        <input id="recaptcha_token" name="recaptcha_token" type="hidden" />
            <fieldset>
        </form>
        
        <input type="button" onCLick="AJAXTransparentRedirect();" value="Submit Card" id="mySubmit" disabled />
        <div id="response"/>
    </body>
</html>
    
<script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit" async defer>
        </script>

Updated 10 months ago


What's Next

Update Credit Card - AJAX Transparent Redirect

Update Credit Card Payment Method

Create Credit Card Payment Method


This endpoint is for creating a credit card via AJAX transparent redirect. Unlike the basic version, this endpoint will not return any HTML and does not take a success/failure URL. This grants more flexibility for handling the response to the call.

In order to succeed, this call must be made from a whitelisted domain. Please contact Fusebill support to add or remove a domain from this whitelist. You can view the whitelisted domains for your account under Settings > Integrations > Transparent Redirect

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.