Create Credit Card Payment Method

📘
Add Credit Card
POSThttps://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 Stax Bill 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. ents.subscriptionplatform.c	Yes
`lastName`	String	This is the last name of the cardholder. ments.subscriptionplatform.	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
`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. api/paymentsv2> 🚧 Not**	Conditional**
`address2`	String	Standard line 2 of an address. This is for the address of the cardholder. api/paymentsv2> 🚧 Not**	Conditional**
`city`	String	This is the city for the address of the cardholder. scriptionplatform.com/api/p	Conditional**
`stateId`	Number	This is the Stax Bill generated state code. Call List Countries) to find the appropriate code. This is for the state of the cardholder	Conditional**
`countryId`	Number	This is the Stax Bill generated country code. Call List Countries 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

Payment Collect Options Object

Property	Type	Description
`collectionAmount`	Decimal	The amount to be collected
payBalanceOwing	Boolean	If true, any balance owing will 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 Stax Bill API endpoints. Your account's private API key should never be visible to your end users.

Sample Request - x-www-form-URL-encoded 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

Stax Bill 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 Stax Bill'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 receive 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.

Stax Bill Environment	reCAPTCHA Public Site Key
Sandbox and Production (payments.subscriptionplatform.com)	6LfVtGwUAAAAALHn9Ycaig9801f6lrPmouzuKF11

(Optional) Use Your Own ReCAPTCHA

Rather than use Stax Bill'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. You can choose invisible reCAPTCHA at this stage if that is your preferred approach. Register. If you don’t want to validate against a domain, 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 Stax Bill account and go to Settings > Integrations > Transparent Redirect
https://admin.fusebill.com/Integrations/TransparentRedirectConfigurations.
Select “use your ReCAPTCHA” and enter the secret key.  Save
On your payment method form, 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>

Add Credit Card

Note

Request Parameters

Not**

Not**

Payment Collect Options Object

Security - Public API Key

Sample Request - x-www-form-URL-encoded and JSON

Sample Response

Google ReCAPTCHA

(Optional) Use Your Own ReCAPTCHA

Sample Code For Testing

What’s Next