Drop-in Form Documentation

This document describes the Drop-in Form, which provides everything you need to quickly start processing payments
on your website.

Quick Start

Create a webpage which will display the payment form.
We will use the following Bootstrap template as an example:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Example Merchant Page</title>
    <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootswatch/3.2.0/sandstone/bootstrap.min.css">
</head>

<body>   
    <nav class="navbar navbar-default" role="navigation">
        <div class="container">
            <div class="navbar-header">
                <a class="navbar-brand" href="#">Example Merchant</a>
            </div>
        </div>
    </nav>

    <div class="container">
        <h3>Welcome to the checkout page</h3>

        <form id="MyForm" action="/checkout" method="post">
            <input type="hidden" name="orderid" value="ABC123">
        </form>
    </div> 
</body>
</html>

As you can see, there is a form named MyForm which will call /checkout once submitted.
The form can contain any input-field.

Note: The form does not contain a "submit"-button. The script will insert one for you.

The easiest way to include the payment form is to include a script-tag, like so:

<h3>Welcome to the checkout page</h3>

<form id="MyForm" action="/checkout" method="post">
    <input type="hidden" name="orderid" value="ABC123">

    <script src="http://api.spryngpayments.com/cdn/inject.js"></script>
</form>

The final html will look like this:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Example Merchant Page</title>
    <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootswatch/3.2.0/sandstone/bootstrap.min.css">
</head>

<body>   
    <nav class="navbar navbar-default" role="navigation">
        <div class="container">
            <div class="navbar-header">
                <a class="navbar-brand" href="#">Example Merchant</a>
            </div>
        </div>
    </nav>

    <div class="container">

        <h3>Welcome to the checkout page</h3>

        <form id="MyForm" action="/checkout" method="post">
            <input type="hidden" name="orderid" value="ABC123">

            <script src="http://api.spryngpayments.com/cdn/inject.js"></script>
        </form>
    </div> 
</body>
</html>

Server Side

If you've got the form setup correctly, it's time to move on to the server side.

When the customer submits the form, the payment information is replaced by a card token, and submitted to the endpoint
of the form. So if your form's action is /checkout and you method is post, on the server side you should create an
endpoint that listens for http POST request at /checkout that contain the following request body:

"card": "563ff2c8f0103bb04be177ab"

When the request from the customer is received, you will have to submit the payment to Spryng.
This is done by sending an http POST request to /v1/transaction with at least the following parameters:

  • account – The account id that was provided to you. Make sure you use the account with the correct currency.
  • amount – The amount is charged without a decimal place e.g. $1.5 = 150.
  • card – The card token that was submitted to you using the payment form.
  • customer_ip – The IP address of the customer that made the payment
  • dynamic_descriptor – A description of the purchased goods or services that will show up on the customers bill.
  • payment_product – The payment product to use. In this case 'card'.
  • user_agent – The customers user agent. This can be found in the HTTP request header under User-Agent.

The payment request has to be authenticated by providing your API key in the X-APIKEY request header.

Here is an example of data to send to the payment API:

{
    "account": "54884a22e1e6573d1d1ee001", 
    "amount": 1250, 
    "card": "563ff2c8f0103bb04be177ab",  
    "customer_ip": "194.66.82.11",
    "dynamic_descriptor": "This is the dynamic descriptor. It will show up on your bank account.",
    "payment_product": "card", 
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 ..."
}

If the payment was successful, the server replies with status 200 and returns the created transaction object.
If the server replies with any other status, the payment has failed. You will be provided with an error message in the
request body.

Note: We advise to have a minimal time-out of 20 seconds on the Payment Request.

JSclient API

Want more flexibility?

You can use the JSclient library. JSclient is a Javascript
library which provides a more traditional function.

<form id="MyForm" action="/checkout" method="post">
    <input type="hidden" name="orderid" value="ABC123">
</form>

<script src="http://api.spryngpayments.com/cdn/jsclient.js"></script>
<script>

    jsclient.injectForm(
        document.getElementById('payment_fieldset')
    )

</script>

You can also use Asynchronous Module Definition to load the
JSclient library. Here is an example using RequireJS:

<script src="//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.15/require.js"></script>
<script>

    require(['http://api.spryngpayments.com/cdn/jsclient.js'], function (jsclient) {
        jsclient.injectForm(
            document.getElementById('payment_fieldset')
        )
    })

</script>

Here is the full API of jsclient.

jsclient

Javascript client module

Version: 1.0.0

jsclient.injectForm(form, [options])

Inject the payment form into an HTML page

Kind: static method of jsclient

Param Type Default Description
form HTMLElement The HTML element to inject the form into.
[options] Object An object containing the options you want to provide.
[options.ideal_redirect_url] String The url to where to redirect iDeal transaction too. Required for iDeal transactions.
[options.cvv_placeholder3] String "A 3 digit security code on your creditcard" The placeholder for the CVV input element when a 3-digit CVV is required.
[options.cvv_placeholder4] String "A 4 digit security code on your creditcard" The placeholder for the CVV input element when a 4-digit CVV is required.
[options.card_number_placeholder] String "Your creditcard number" The placeholder for the card number input element.
[options.expiry_placeholder] String "MM/YY" The placeholder for the expiry date input element.
[options.submit_title] String "Submit" The placeholder for the expiry date input element.
[options.nr_not_valid] String "Not a valid credit card number" The placeholder for the expiry date input element.
[options.length_not_valid] String "Card number length should be between 13 and 16 digits" The placeholder for the expiry date input element.
[options.month_not_valid] String "Expiry month must be a value between 1 and 12" The placeholder for the expiry date input element.
[options.year_not_valid] String "Expiry year must be a value between 16 and 26" The placeholder for the expiry date input element.
[options.cvv_not_valid] String "CVV number should contain 3 or 4 digits" The placeholder for the expiry date input element.
[options.payment_products] Array ["card"] A list of payment products you want to offer your customer. Can be "card" pr "iDeal".
[options.cardstore_url] String Adjusts the path to the appropriate card store. Allows switching between different environments.
[options.no_style] Boolean Whatever to apply the default style. Set to true if you want to do your own styling.