Apruve.js Reference

Apruve.js is a JavaScript library that merchants use to give shoppers on their web store the ability to pay with Apruve.
See the Merchant Integration Tutorial for examples.

The Script Tag

Apruve TEST Environment

<script src="https://test.apruve.com/js/v4/apruve.js" type="text/javascript"></script>

Apruve PRODUCTION Environment

<script src="https://app.apruve.com/js/v4/apruve.js" type="text/javascript"></script>

ProTip: We recommend you use environment variables to set the appropriate URL for the Apruve script, depending on whether you are operating in your test/development environment, or running live transactions.

Alternate Buttons

apruve.js can be configured to use any of the following buttons, allowing you to customize your experience. They are configured via the "display" query parameter, per the example shown.

?display=What you'll seeExample use of query parameter
(default)default buttonsrc="(...)apruve.com/js/v4/apruve.js"
compactcompact buttonsrc="(...)apruve.com/js/v4/apruve.js?display=compact"
educationeducation buttonsrc="(...)apruve.com/js/v4/apruve.js?display=education"

The DIV Tag

Place this tag on your page where you want the Apruve button to appear:

<div id="apruveDiv"></div>

The apruve Object

Initialization

The apruve object is automatically instantiated on page load. There are some methods you must call to initialize it, as described below.

Methods

-apruve.setOrder

The setOrder method is used to initialize the Apruve checkout with information about your customer's order - if you have registered an APRUVE_ACCEPTED_EVENT callback, you will be notified when the order message has been received by our system. Your checkout must call this method prior to APRUVE_LAUNCHED_EVENT firing for the Apruve checkout to work correctly!

Parameters

NameDescription
orderObjectThe order in JSON format. See the Orders API for specifics on fields and options. Read the Merchant Integration Tutorial for complete examples.
secureHashStrA SHA256 hash (digital signature) of the order that you create on your server with your API-Key. Apruve uses this to verify that your Payment Request data is intact and has not been manipulated by the shopper, which prevents fraud. How to create this hash is covered in the Merchant Integration Tutorial.

Example:

order_json = { "amount_cents": 10000, "merchant_id":... }; // Note: this is an object, *not* a String!
secure_hash = "5c22feda3dcde817e9a1f53c88ad0f09d972641";
apruve.setOrder(order_json, secure_hash);

-apruve.setShopper

The setShopper method allows you to initialize the Apruve modal with the name and/or email address of the shopper. Use of this method isn't required, but it does simplify the Apruve checkout process for your shoppers.

Parameters

NameDescription
shopperEmailThe shopper's email address as collected by the merchant. This allows Apruve to provide a more customized experience for a merchant's shoppers.
shopperNameThe shopper's name as collected by the merchant. This allows Apruve to provide a more customized experience for a merchant's shoppers.

Example:

apruve.setShopper('[email protected]', 'Sharon Shopper');

-apruve.registerApruveCallback

The registerApruveCallback method lets you provide callbacks for certain events during checkout.

Parameters

NameDescription
eventThe event type for which you want to register a callback. See the Events table below for details.
functionThe callback function to register

Events

Event ConstantDescription
apruve.APRUVE_LAUNCHED_EVENTThe Apruve lightbox has been launched.
apruve.APRUVE_COMPLETE_EVENTThe Apruve checkout process has been completed. The Apruve order ID is passed as an argument to the callback function.
apruve.APRUVE_CLOSED_EVENTThe Apruve lightbox has been closed without completing the checkout.
apruve.APRUVE_ACCEPTED_EVENTApruve has received the purchase order message.

Example:

apruve.registerApruveCallback(apruve.APRUVE_COMPLETE_EVENT, function (orderId) {
  // do something with the order ID
});

Troubleshooting

"This merchant is experiencing technical difficulties"

If you see this message during testing, it means that Apruve was unable to process the order using the information that was set on apruve.js.

To help manage this situation, apruve.js will provide the errors in the apruve.errors variable. You can use a browser debugger console such as Chrome.

chrome debugger example

"Validation failed for secure_hash"

Apruve uses the secure hash value you pass into apruve.setOrder to ensure that the order data you set has not been altered by the shopper before transmission to Apruve during the payment process. If you receive this error, it means that the secure hash value was invalid.

Ensure the following are correct while creating your hash:

  • The fields are in the correct order per the Merchant Integration Tutorial
  • All the fields specified on the order have been included in the hash
  • There is no variation in whitespace between the order and the string used to compute the hash.