Openpay.js
Intro
What is Openpay.js?
Openpay.js is a Javascript library designed to facilitate the creation of tokens based on credit and debit cards' data retrieved from a web page without passing any information through the source server (the server of the business).
Advantages:
- It's safe, the card information does not pass through the source server, but is sent directly to Openpay.
- It's the fastest and easiest way to integrate our charges module on your web page.
First Steps
The first step is to add the Openpay.js library to your page as shown below:
Configuration
To use Openpay.js you must configure both the ID of the business and the public key that were assigned to you when you created your account on the sandbox dashboard. With these data, Openpay can identify your operations and can assign your cards and charges.
To configure both parameters use the methods OpenPay.setId()
and OpenPay.setApiKey()
, respectively:
Note: You can obtain both MERCHANT-ID and the PUBLIC_API_KEY in the dashboard when you log in on your openpay account, in the home page or in your profile page.
Reminder: You should never use your private key with this library, because the key is visible on the client side.
Enable sandbox mode
There is a sandbox environment for you to try on your implementation, which is enabled with the method: OpenPay.setSandboxMode ().
The FLAG
parameter is a true / false flag to enable or disable test mode.
If necessary, you can use the OpenPay.getSandboxMode()
method to determine the status of the sandbox mode at any time:
Note: The sandbox environment has the same features as production, but it only allows the use of certain card numbers, chosen with testing purposes more information on the test section.
Creating tokens without a form.
Once you have installed and you set up the library, you’ll need to call the OpenPay.token.create () method in order to create a token.
The parameters for this method are: * The CREATE_PARAMETERS_OBJECT parameter is a Javascript object containing the card information. * The SUCCESS_CALLBACK parameter defines the function to be called if the operation was successful. * The ERROR_CALLBACK parameter defines the function to be called if the operation failed.
Example of creating a token:
The method returns an object type token with an id which you’ll need later. You’ll find the definition of the token object here.
Creating tokens with a form
The Openpay.js library facilitates the extraction of the card information using a form, so you can send it later through the OpenPay.token.extractFormAndCreate()
method.
The parameters for this method are:
- The CREATE_FORM_OBJECT parameter is a Javascript object containing the card information.
- The SUCCESS_CALLBACK parameter defines the function to be called if the operation was successful.
- The ERROR_CALLBACK parameter defines the function to be called if the operation failed
To start creating tokens, you must have a form like this:
Note: The most important thing is to add the
data-openpay-card
anddata-openpay-card-address
on the inputs of the card information and the card address because that’s how the method knows where to get those values.
Later when generating the token, call the token.extractFormAndCreate()
method as shown below:
The method returns an object type token with an id which you’ll need later. You’ll find the definition of the token object here.
For an example download the sample page from the github site: openpay-js
Handling responses
The response functions are to handle the operations results. They are simple Javascript functions but they receive an object type response as parameter .
The fields of the response object are described below:
|Field |Format |Description |-------|-----------|---------------- |status |Integer |Describes the HTTP status of the operation. If there is an error before sending the request, the status will be zero. If it’s successful is 200. |message|String |Only occurs in case of error. It’s a short description of the error. It can be one of the following values: "Unknown error", "Request error", "Response error (unknown final status)", "Empty or invalid OpenPay ID", "Empty or invalid API Key", "Browser error", "timeout after X milliseconds ". |data |Objeto |It contains an Error object with the error information during the transaction provided by the OpenPay server. In case of success it contains an object type token.
Note: Although the response functions are optional, we recommend you to implement that the outcome of the transaction can be monitored on the website.
In case of success: SuccessCallback
This function is called when the operation was successful from start to finish. Receive a single parameter which is a Javascript object with the token data.
Complete example of implementing a SuccessCallback function:
In case of error: ErrorCallback
This function is executed whenever an operation has failed (for any reason, before or after sending the request). Like SuccessCallback () it receives a single parameter which is a Javascript object with the error details.
Complete example of implementing an errorCallback function:
Types of errors
In addition to the status field that saves the transaction status, it is possible to determine what error happened by using the message field. The message may be one of the following:
Empty or invalid OpenPay ID: occurs when the user ID has not been properly configured with the OpenPay.setId () method
Empty or invalid API Key: Like the above error, it happens when you have not set the API Key with the OpenPay.setApiKey () method
Browser error: This error indicates that there was an error in the Openpay server. It may be due to missing parameters, formats or some other problem that prevents a successful transaction.
Request error: Este error indica que hubo un error en el servidor de Openpay. Puede deberse a parámetros faltantes, formatos u algún otro problema que impide realizar correctamente la transacción.
Response error (Unknown final status): When this error occurs, it means that the transaction request is sent successfully to the Openpay server but no reply was received. This may be due to a problem in Openpay. For more information contact OpenPay.
Timeout after X milliseconds: It happens when the request has taken a long time to run and therefore the response time expires.
Unknown error: This happens when there is an unknown error that prevents to make the request. It may be due to problems in the browser or a connectivity problem.
Validation functions
Besides the functions to process card charges, Openpay.js also includes some functions to validate the main data needed to carry out the transaction, specially regarding card numbers.
The available methods are:
- OpenPay.card.validateCardNumber()
- OpenPay.card.validateCVC()
- OpenPay.card.validateExpiry()
- OpenPay.card.cardType()
Card number validation
To validate a card number you can use the OpenPay.card.validateCardNumber()
method.
This method receives a String as a parameter with the card number which will be validated and will return true / false depending if the card it’s valid and is accepted by Openpay. Example
This method is very useful for determining whether a card number is valid and if it’s able to be used with Openpay, so we recommend that you use it routinely before attempting a card charge.
Examples:
Security Code Validation
To validate the security code use the OpenPay.card.validateCVC()
method.
This method receives a String as a parameter and returns true / false depending if the string is valid.
Examples:
Expiration date Validation
For this purpose use the OpenPay.card.validateExpiry()
method.
This method receives two strings as parameters representing the expiration month and year of the card. It returns true / false depending if the combination of both data, month and year, are a valid expiration date. Example:
Validation of the type of card
It can be determined (most of the time) the type of card that belongs to a card number. For this, use the OpenPay.card.cardType()
method.
The method receives a card number as a parameter and returns a String with the name of the card type.
Examples:
Compatibility and Requirements
To use Openpay.js is necessary to have one of the following browsers:
- Chrome 29.0+
- Firefox 23.0+
- Safari 5.1+
- Opera 17.0+
- iOS Safari 4.0+
- Android Browser 2.1+
- Blackberry Browser 7.0+
- IE Mobile 10.0
It’s required that the browsers have support for the XMLHttpRequest and JSON Parser libraries.