NAV
curl

How it works

Welcome to the reepay.js how-to guide and documentation. The reepay.js sends customer payment information directly from the customer browser to Reepay to be encrypted and stored. In return you get a token you can use for recurring or one-time payments. Using a token instead of actual card holder information allows use of our API without handling sensitive information. The token can be used for the following API operations:

More about our powerful API can be found here.

We will start by showing you how to make a simple Reepay integration and explain how you can make a integration fitting your needs.

Notice that for a simpler integration with lower PCI DSS requirements, see the Reepay Token solution.

PCI DSS

Processing, transmission, or storage of card data must comply with the Payment Card Industry Data Security Standards (PCI DSS). Reepay is certified as a PCI Level 1 Service Provider. This is the most stringent level of certification available in the payments industry.

PCI compliance for your business is a shared responsibility between Reepay and you. Anybody accepting payments must do so in a PCI compliant manner. The Reepay JS library sends data directly from the user browser to Reepay. To use this solution you are required to do a SAQ_A-EP self-assessment.

For a simpler solution only requiring a SAQ-A self-assessment see the Reepay Token solution.

When developing payment or sign-up pages always remeber the following best practices in regards to PCI compliance.

Tutorial

Including reepay.js

To use reepay.js you need to include our hosted reepay.js script in your webpage

<script src="https://js.reepay.com/v1/reepay.js"></script>

This will expose a single global object called reepay.

Configuration

Include the reepay configuration using your public key and optionally recurring flag

reepay.configure('pub_826e677def6b720185721ebb711a7e46');
- or -
reepay.configure({
    publicKey : 'pub_826e677def6b720185721ebb711a7e46',
    recurring : false
});

You need to configure the reepay.js library with your public key to identify your site to the Reepay server. You can find and manage your public keys in the Developer section of the Reepay administration. Optionally it can be configured whether the token generated is to be used for recurring payments (the default) or for a one-time payment. If the token is to be used for one-time payment an object with public key and recurring parameter set to false must be provided (see example on the right).

Build a form

Create a form using the data-reepay attributes

<form>
  <input type="text" data-reepay="number">
  <input type="text" data-reepay="month">
  <input type="text" data-reepay="year">
  <input type="text" data-reepay="cvv">
  <input type="hidden" name="reepay-token" data-reepay="token">
  <button>submit</button>
</form>

The reepay-token input field will be filled out with a one time card token after the card has been validated.

You need to create a form on your page to collect your customers payment information. This can be done using the data-reepay attribute on the input fields. When these attributes are added, the reepay.js library will gather the sensitive card informations and use it to generate a token. The table below demonstrates all possible input fields.

CARD DATA

field example Description
number 4111 1111 1111 1111 card number REQUIRED
month 4 or 04 card expiration month REQUIRED
year 24 card expiration year REQUIRED
cvv 999 card security code RECOMMENDED

Other billing information can be submitted as well.

Getting the reepay-token

You need to interrupt the form submit and send the billing information to Reepay. This will either result in an error or a returned token.

$('form').on('submit', function (event) {
    var form = this;
    event.preventDefault();
    reepay.token(form, function (err, token) {
        if (err) {
            console.log(err);
            // handle error using err.code and err.fields
        } else {
            // The reepay-token field has automatically been filled with the token
            form.submit();
        }
    });
});

The form needs to be interrupted when your billing form is submitted, and you need to ask reepay.js to create a token from the form. If you look into the form from last step you will notice an additional hidden field in the form named reepay-token. When you ask reepay.js for a token during submit, it will automatically populate this field with data-reepay="token". After the field is populated it should be submitted to your server and you can use it to e.g. assign a payment method to a subscription.

Use of the reepay-token

Create a new customer and subscription providing payment method with a card token source. See our API documentation.

curl -X POST \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "plan": "gold",
  "signup_method": "source",
  "create_customer": {
    "email": "carl@leone.com",
    "handle": "cust_001"
  },
  "generate_handle": true,
  "soruce": "ct_e4926c46be444fcbbc809be06abfd706"
}' \
https://api.reepay.com/v1/subscription

Create a one-time payment for customer. See our API documentation.

curl -X POST \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "handle": "order-132",
  "amount": 10000,
  "customer_handle": "cust-003",
  "source": "ct_e4926c46be444fcbbc809be06abfd706",
  "settle": false
}' \
https://api.reepay.com/v1/charge

Once reepay.js has stored the sensitive payment information the returned token must be used within 20 minutes. On the right two examples of the use of the token is shown:

  1. Creating a subscription using the entered payment information
  2. Create a one-time payment

These API endpoints accepts a card token

Tokens

You need to handle sensitive card information when you want to assign a credit card to one of your customers. We have developed a token service handling the card information for you. This enables you to limit the PCI requirements for your site.

A token is a secure and temporary storage for your customers sensitive billing informations which you can use to assign a payment method to one of your customers.

reepay.token

Sends card informations to Reepay for secure storage and returns a token back. It is possible to call reepay.token: with a form or with an object.

The easiest way to call reepay.token is to passing a form element containing input fields containing data-reepay attributes.

reepay.token needs to be called with a form element

reepay.token(document.querySelector('form'), tokenHandler);

Form Arguments

Param Type Description
form HTMLFormElement The form element containing data-reepay fields
callback Function Callback function to accept the returned token

It is also possible to call reepay.token with a normal JavaScript object.This allows a more direct interface to the payment flow.

Or with an Object

var cardInfo = {
  number: '4111-1111-1111-1111',
  month: '1',
  year: '18',
};

reepay.token(cardInfo, tokenHandler);

Object Arguments

Param Type Description
options Object An object with billing informations as shown in the example
callback Function Callback function to accept the returned token

A callback Function is always required

Callback Arguments

Param Type Description
err ReepayError or null A ReepayError if an error occurred.
token Object An object containing a token id
token.id String A token id

tokenHandler

function tokenHandler (err, token) {
  if (err) {
    // handle error using err.code and err.fields
  } else {
    // handle success using token.id
  }
}

Validation

We have implemented a few helpful methods to validate and format your input. It is free to use and if you develop some useful methods feel free to submit them to us on Github and we will share them with everyone.

reepay.validate.cardNumber

reepay.validate.cardNumber('4111111111111111');
// > true

reepay.validate.cardNumber('4111-1111-1111-1111');
// > true

reepay.validate.cardNumber('4111-1111-1111-1112');
// > false

Determines whether a given credit card number appears to be valid. Card numbers can include spaces or dashes.

Arguments

Param Type Description
number String Credit card number. Dashes and spaces are allowed

Returns

Boolean. Whether or not the card number is valid.

reepay.validate.cardType

reepay.validate.cardType('4111-1111-1111-1111');
// > 'visa'

reepay.validate.cardType('372546612345678');
// > 'american_express'

reepay.validate.cardType('867-5309-jenny');
// > 'unknown'

Returns a card type for the provided card number, or unknown, This is useful if you want to show the card type or display custom CVV location hints.

Arguments

Param Type Description
number String Credit card number.

Returns

String. One of our supported card types or unknown.

reepay.validate.expiry

reepay.validate.expiry(1, 2020);
// > true

reepay.validate.expiry('01', '16');
// > true

reepay.validate.expiry('12', '2013');
// > false

Verify if a given expiry month and year is valid. Card set to expire in the current month are considered valid.

Arguments

Param Type Description
month String or Number Month as one or two digits: 06,6
year String or Number Year as two digits: 24

Returns

Boolean. Whether or not the expiry date is valid.

reepay.validate.cvv

Determines whether the given card security code appears to be valid

Arguments

Param Type Description
cvv String or Number Card security code

Returns

Boolean. Whether or not the cvv is valid.

reepay.validate.formatCardNumber

We have created this function for easy validation and format of the card number in the input field. When this is enabled on the card number input field it will automatically format the card number to have a more professional look. Additionally you will receive callbacks containing the card type so that custom styling of your payment form is possible.

Normal cardnumber field

Alt text

Formatted cardnumber field

Alt text



reepay.validate.formatCardNumber("input[data-reepay=cardnumber]", function (card) {
            if ((card.type == 'default') || (card.type == 'unknown')) {
                // The cardnumber is invalid or unknown
            } else {
               // The cardnumber is valid and has a known cardType

            }
        });

Arguments

Param Type Description
cardnumber String or Object css selector for input element or the DOM element
callback Function A function to handle the returned card information

Callback arguments

This is the card element returned to the cardHandler this can be of the form described below or null.

Param Type Description
card.type String card type Identifier
card.pattern Regex Regex for the card pattern
card.format Regex Regex for the card format
card.length array Array containing the allowed card number lengths
card.cvcLength array Array containing the allowed CVC number lengths

Errors

{
    name: 'validation',
    code: 'validation',
    message: 'There was an error validating your request.',
    fields: [
        'number',
        'year'
    ]
}

Errors are encapsulated by a ReepayError which contains some messages to help you diagnose error cases and inform your customers accordingly.

Errors will be thrown if the exception will prevent proper execution. If an error can be recovered, it will be passed to the proper error handling event listener or callback.

It is not recommended for you to show the error messages directly to your customers, while they can be a bit technical. It is better for you to show your own error messages.

Code Description
Configuration
not-configured Remember to call reepay.configure.
missing-public-key When you call reepay.configure, you must call with a public key as parameter.
invalid-public-key When you call reepay.configure, you must call with a valid public key as parameter.
already-configured reepay.configure has been called multiple times. Doing so mare than once is excessive.
Tokenization
validation A request validation error has occured. Please check the fields property to determine which fields causing the error.
invalid-parameter A parameter validation error has occured. Please check the fields property to determine which fields causing the error.
invalid-request The request made to Reepay is invalid. Please check the fields property to determine which fields causing the error.
api-error An error has occured at Reepay API. Please check message and fields properties for more information.
card-type-not-supported Card type of the entered card is not supported be the payment gateway agreement(s) defined for your account.
credit_card_expired The given card has expired.
insufficient_funds Insufficient funds on card.
declined_by_acquirer Card declined by acquirer.
credit_card_lost_or_stolen Declined because card reported lost or stolen.
credit_card_suspected_fraud Declined due to suspected fraud.
acquirer_communication_error Communication error between Reepay and acquirer.
acquirer_error Error at the acquirer.
acquirer_authentication_error Acquirer authentication error. Check your authentication credentials in the payment gateway settings.
acquirer_configuration_error Acquirer configuration error. Check settings at your acquirer and the payment gateway settings in Reepay.
acquirer_rejected_error Acquirer rejected error. The acquirer is rejecting the attempt to register card. Check settings at your acquirer and the payment gateway settings in Reepay.

Testing

Testing can be done using a combination of test cards and specific cvv codes that can be found here.

Example

Examples demonstrating the use of the Reepay Javascript Library and API can be found here: https://github.com/reepay/reepay-examples.

Support

Reepay.js supports Chrome, Firefox, Safari, iOS 6+, and IE 9+.

If you need help with your Reepay.js integration feel free reaching out to us.

Also feel free to modify or add functionality to reepay.js. Clone the repo on Github.

For all other issues feel free to reach out to us at support@reepay.com.