Complement your JavaScript integration

On this page, you can complement and expand on the information in the JavaScript Integration guide. Click on the link to learn how to integrate Addon Payments this way.

Transaction flow

Below is a diagram of the whole JavaScript integration process.

The flow is as follows:

The merchant performs a AuthToken request, passing off some information related to the merchant and the customer. Refer to JS AuthToken request for more information.
AddonPayments returns a unique and single used AuthToken which is linked to the sent data.
At this time, the merchant could send the AuthToken to the customer browser and start renreding the AddonPayments JS cashier.
Using the AuthToken the merchant render the cashier payment form. Refer to Rendering cashier for more information and available use cases.
The customer filled in all the customer or payment information and submit the form.
AddonPayments recollets the payment info and generates an unique prepayToken which is linked to the original AuthToken requested values. Once the token is generated, AddonPayments will perform a call to merchantPrePayCallback method that is set in the step 4. For more information, refer to PrePayToken section.
Send the prepayToken to the merchant backend site.
Build and perform the payment charge request passing off all the required payment information. Remember that it requires to send the prepayToken in the request. Refer to Charge operation for more information.
AddonPayments performs the payment.
AddonPayments gets the Payment Solution response.
AddonPayment returns the charge response to the merchant. Depending the response, it could require some customer redirection.
Payment is completed because it reached a final status. Refer to Response section for more information.
Payment requires a customer redirection, so the merchant has to redirect the customer to the third party url, passed off in the response. Refer to Charge response section for more information.
Customer interacts with the payment solution page.
Payment Solution informs the status of the payment.
AddonPayment sends a notification to the merchant, using the statusUrl field of the request.
Merchant shows the final payment page to the customer.

Environments: Staging and Production

Addon Payments has two (2) separate operating environments:

Staging environment:
- This is the first environment you will use.
- There is a list of cards to use for testing the system, creating transaction simulations of various operations, authentication types (frictionless, challenge) and results (authorized, declined).
- This will allow you to make sure that the different situations are handled properly by your integration.
- Real cards and accounts don’t work.
Production Environment:
- In this environment, transactions are real.
- You can only use real, operational cards and accounts.

This is a table with the endpoints to send the request to, whether authorization or payment, depending on the environment you are using:

Request	Environment	URL
Request /auth	Staging	https://epgjs-mep-stg.addonpayments.com/auth
Request /charge	Staging	https://epgjs-mep-stg.addonpayments.com/charge/v2
Request /auth	Production	https://epgjs-mep.addonpayments.com/auth
Request /charge	Production	https://epgjs-mep.addonpayments.com/charge/v2

Below is a table with the AP library for JavaScript that you need to import and the call to set up the base URL for the payment gateway.

You have to add a <script> HTML element with the route to the AP JS library to your ecommerce platform payment page. This route must include the version of the library to load. We currently recommend using version 4.0.0.

Function	Environment	URL
Import the Addon Payments JS library	Staging	https://epgjs-rendercashier-stg.addonpayments.com/js/public/epgjs-[versión]-min.js
Set the base URL for the payment gateway	Staging	https://epgjs-web-stg.addonpayments.com/
Import the Addon Payments JS library	Production	https://epgjs-rendercashier.addonpayments.com/js/public/epgjs-[versión]-min.js
Set the base URL for the payment gateway	Production	https://epgjs-web.addonpayments.com/

Getting the authToken

The first step in the JavaScript integration is to get the authToken so we can render the cashier. A request must be sent with at least the info shown below:

				
					{   
    "merchantId": "12345",
    "merchantKey": "dd0bc115-6f8f-4e65-9447-e06862eb62ec",
    "productId": "123450001",
    "currency": "EUR",
    "country": "ES",
    "customerId": "customer25879",
    "operationType": "debit"
}

				
					curl --location 'https://epgjs-mep-stg.addonpayments.com/auth' \
--header 'Content-Type: application/json' \
--data '{
    "merchantId": "12345",
    "merchantKey": "dd0bc115-6f8f-4e65-9447-e06862eb62ec",
    "productId": "123450001",
    "currency": "EUR",
    "country": "ES",
    "customerId": "customer25879",
    "operationType": "DEBIT"
}'

If the request is valid, Addon Payments will return an “authToken” for you to render the cashier on the frontend of your page. If the request isn’t valid, you will get a message like you see on the second tab:

				
					{
    "authToken": "50fe7cab-63c4-4197-9484-50f9a0792f8b"
}

				
					{
    "error": true,
    "errorMessage": "Invalid merchant id or merchant key",
    "errorCode": 400
}

Your platform must store this code to continue to the next step. The authorization tokens received have the following characteristics:

Valid for 30 minutes.
It can be used several times to link to the payment gateway.

Parameters of the authToken request

The type shows whether the element is Required (R) or Optional (O).

Field	Format	Type	Description	Example
merchantId	Whole number 4~7 digits	R	Your merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments	14983
merchantKey	Alphanumeric UUID Format	R	The JavaScript password. Used to verify the request is legitimate. For the staging environment, it comes in the welcome email. For production environments, recover it from the BackOffice.	67a33d37-64b9-408e-a1b7-cef28ef94970
productId	Whole number 6~11 digits	R	Product ID created on your AP merchant. You’ll find it in the welcome email.	149830
currency	Alphabetical 3 characters ISO-4217.3	R	Currency of the transaction	EUR
country	Alphabetical 2 characters ISO 3166-1 alfa-2	R	Country from which the transaction is sent	ES
customerId	Alphanumeric Max 80 characters	R	Customer ID in your e-commerce platform. – To save the customer’s card token, use the “forceTokenRequest” parameter, with value “true” to save the token and “false” not to. – To show or hide the option to remember the customer’s card, use the “showRememberMe” parameter, with value “true” to show it and “false” to hide it.	A34623
operationType	Alphanumeric Max 45 characters	R	Shows type of operation to carry out. Valores admitidos: – debit (default): Payment transaction. That is, cash travels from the customer’s account to the merchant. – credit: Deposit transaction to the customer’s account. That is, cash travels from the merchant to the customer’s account. For example, in the payment of a prize. Not to be confused with returns. These have their own type of transaction.	debit
showRememberMe	Possible values: – true: Displays the “Remember Me” checkbox, which the customer can select (or not) to save the card token. – false: Does not display the “Remember Me” checkbox. The card token will only be saved if “forceTokenRequest” is set to true.	O	Shows or hides the “Remember Me” checkbox, allowing the customer to choose whether to save the card token.	true
forceTokenRequest	Boolean – true – false	O	Indicates whether to save the customer’s card token. Use “false” if you don’t want to save the card. If this value is “true” but the customer does not check the “Remember Me” box, the token will not be saved.	false

Rendering the cashier on your frontend

After you get the “authToken” you can render the cashier on your frontend. Remember, the cashier can’t be rendered on a localhost and you must authorize the domain from the Addon Payments dashboard.

When you render the cashier, you can choose which payment solutions to show. You can also choose the type of cashier you want to render.

Below is a simple example showing how to render the cashier with all the payment methods available:

				
					<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>JS render cashier</title>
    <style>
        #render-cashier {
            width: 350px;
            margin-top: 100px;
            border: 1px solid #ccc;
            padding: 20px;
            text-align: center;
        }
    </style>
</head>
<body>
    <div id="render-cashier"></div>
    <script src="https://epgjs-rendercashier-stg.addonpayments.com/js/public/epgjs-4.0.0-min.js"></script>
    <script>
        var authtoken = "bdae356b-0236-47db-bbea-24de03168195"; // Add here your authToken
        function prePayCallback(prepayData) {
            // Show prepayToken This is just for example purposes only and should not be shown to your customer
            alert(JSON.stringify(prepayData, null, 2));
        }
        function displayingMessageOnButtonClick() {
            EPGJS_COMM.setEpgBaseUrl('https://epgjs-web-stg.addonpayments.com/');
            EPGJS.renderIntegratedCashier(authtoken, 'render-cashier');
            EPGJS_COMM.setMerchantPrePayCallback(prePayCallback);
        }
        window.onload = displayingMessageOnButtonClick;
    </script>
</body>
</html>

You can check the functions, required or optional, in this section.

This will allow you to render the cashier in the frontend currency so the cashier can make payment, as you see in the picture below.

When the customer clicks on the payment button, Addon Payments will return an object with the “prepayToken” so you can send the payment request.

Function call for different types of cashiers:

Cashier with all the payment solutions:

EPGJS.renderIntegratedCashier(authToken, 'render-cashier');

Cashier with only one payment solution

EPGJS.renderIntegratedCashier(authtoken, 'render-cashier', 'payment solution');

Getting the prepayToken

If the customer enters card or account details, your ecommerce platform will receive a JS object with the token to prepare payment (prepayToken). Here is an example of a “prePayToken”:

"prePayToken": "8862abf9-ca5a-49da-9527-1e3163e64954"

Your platform must store this code to continue to the next step. It is the code that gives the customer authorization to send the charge. The authorization tokens received have the following characteristics:

Valid for 30 minutes.
It can only be used to authorize payment once.

DIY (Do It Yourself)

This allows the cashier elements to be rendered inside the merchant’s HTML elements.

The customized payment form option allows merchants to choose the appearance and design for each element of the cashier.

Here are the steps to create a cashier:

Add a < div > element to your website and define < divs > for each one of the components on the payment form you want to use.
Define a variable that assigns the <div> IDs you created in the corresponding elements on the Addon Payments form.
Call setDIY(string) method and give the variable you created in the previous step.

Below we’ll look at these steps in more detail:

Step one: Define the HTML

Define in the HTML a form with < div > elements with IDs for each of the components on the payment form.

The following example shows the HTML to create a form that accepts credit card details (card number, cardholder’s name, expiry date and CVV):

				
					<div id="diy-container">
    <form id="diy-custom-form" >
      cardNumber:
        <div id="diy-pan"></div>
      Ch Name:
        <div id="diy-chName"></div>
      ExpDate:
        <div id="diy-expdate"></div>
      Cvv:
        <div id="diy-cvnNumber"></div>
        <button id="pay-btn" type="submit">Proceed</button>
    </form>
  </div>

Step two: Create a JavaScript variable

Define in JS a variable with a JSON that assigns the form IDs with the fields created in the previous step:

				
					var json='{
    "epgjs-cashier-quickpay-form":"id_formulario_tarjeta",
    "chName":"campo_nombre_titular",
    "cardNumber":"campo_numero_tarjeta",
    "expDate":"campo_fecha_caducidad",
    "cvnNumber":"campo_cvv",
    "epgjs-cashier-quickpay-form-button-CreditCards":"boton_pago"
}';

Step three: Call the function

Call the JS library function “setDiy()” with the JSON we created as the parameter:

				
					EPGJS_DIY.setDiy(JSON.parse(json));

Step four: Rendering the cashier

Call the JS library function “renderQuickDepositByPaymentSolution()” with the following parameters:

The authToken received from AP.
The form ID created in point 1.
The card payment solution set up on your merchant.

				
					EPGJS.renderQuickDepositByPaymentSolution(authToken,'id_formulario_tarjeta','creditcards');

Charge call

With the “prepayToken”, you can send the payment/charge request. Below is a sample request and response with the basic fields.

Remember that the parameters change depending on the payment method and use cases.

This is a basic example of a card payment:

				
					{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "amount": "10.00",
    "apiVersion: "5",
    "currency": "EUR",
    "country": "ES",
    "customerId": "000001",
    "paymentSolution": "creditcards",
    "productId": "123450001",
    "statusURL": "https://micomercio.com/recepcion_notificacion.php?tipo=redireccion",
    "successURL": "https:// micomercio.com/url-ok.php",
    "errorURL": "https:// micomercio.com/url-ko.php",
    "cancelURL": "https:// micomercio.com/url-cancelacion.php"
}

				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 8862abf9-ca5a-49da-9527-1e3163e64954' \
--data-raw '{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "amount": "10.00",
    "apiVersion: "5",
    "currency": "EUR",
    "country": "ES",
    "customerId": "000001",
    "paymentSolution": "creditcards",
    "productId": "123450001",
    "statusURL": "https://micomercio.com/recepcion_notificacion.php",
    "successURL": "https://micomercio.com/url-ok.php",
    "errorURL": "https://micomercio.com/url-ko.php",
    "cancelURL": "https://micomercio.com/url-cancelacion.php"
}'

Below you have the charge parameters. Plus, we recommend you visit our 3DSecure section to add additional fields to the payment process. These optional data fields enrich the payment request and can facilitate the authentication process.

Field	Format	Type	Description	Example
prepayToken	Alphanumeric UUID Format	R	It is sent in the request header. AP returns this reference after the customer enters their details in the JS payment form. It is the reference that links to the customer’s card or account details for JavaScript integration.	97fe3726-adb1-4e24-9fb8-92593a75ae74
merchantId	Whole number 4~7 digits	R	Your merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments	14983
productId	Whole number 6~11 digits	R	Product ID created on your AP merchant. You’ll find it in the welcome email.	149830
apiVersion	Numerical Accepted value: 5	R	Version of the Addon Payments gateway API through which the transaction is to be processed.	5
paymentSolution	Alphanumeric Max 45 characters	R	Name of the payment solution to process the transaction. IMPORTANT: If you don’t want all the payment solutions you have available to be shown, do NOT send this parameter.	creditcards
operationType	Alphanumeric Max 45 characters	R	Shows type of operation to carry out. Eligible values: – DEBIT(default): Payment transaction. That is, cash travels from the customer’s account to the merchant. – CREDIT: Deposit transaction to the customer’s account. That is, cash travels from the merchant to the customer’s account. For example, in the payment of a prize. Not to be confused with returns. These have their own type of transaction.	debit
merchantTransactionId	Alphanumeric Max 45 characters	R	This is the unique identifier of the merchant’s transaction. It is used by your platform to link the notifications received with the customer’s order.	order_91684
amount	Numerical with decimals 0~1000000.00	R	Amount of the transaction. If the amount has decimals, the separator is a dot (.). The separator cannot be included in the thousands.	127.5
currency	Alphabetical 3 characters ISO-4217.3	R	Currency of the transaction	EUR
country	Alphabetical 2 characters ISO 3166-1 alfa-2	R	Country from which the transaction is sent	ES
customerId	Alphanumeric Max 80 characters	R	Customer ID in your e-commerce platform. – To save the customer’s card, use the “forceTokenRequest” parameter, with value “true” to save the token and “false” not to. – To show or hide the option to remember the customer’s card, use the “showRememberMe” parameter, with value “true” to show it and “false” to hide it.	A34623
statusURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your e-commerce platform where AP will send the notification with the status of the transaction. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/status
successURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your platform to which the customer is redirected if the transaction is authorized. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/success
errorURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your platform to which the customer is redirected if the transaction is declined. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/error
cancelURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your platform to which the customer is redirected if the transaction is cancelled during the payment process. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/cancel
awaitingURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your platform to which the customer is redirected if the transaction is pending processing. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/awaiting
customerEmail	Alphanumeric Max 100 characters	R*	Cardholder’s email. European merchants: required for SCA *customerEmail or telephone must be sent. Only 1 of those paramaters is mandatory	correo@ejemplo.com
telephone	Alphanumeric Max 45 characters	R*	International prefix + Cardholder’s phone number. Can be mobile, work or home phone number. European merchants: required for SCA *customerEmail or telephone must be sent. Only 1 of those paramaters is mandatory	34600600600
language	ISO 639-1 code	O	Language to be displayed on the customer checkout. Currently, it is only available in Spanish (ES) and English (EN).	EN
referenceId	Alphanumeric 12 characters	O	Variable reference for merchants requiring FB500 reconciliation files.	SM1258X795WW
merchantParams	Key1:Value1;Key2:Value2;KeyN:ValueN Max 500 characters	O	Parameters that are sent to modify the mechant configuration or the processing of a transaction. They are received back within the tag. Does not support special characters	name:pablo;surname:ferrer;clientid:12345
printReceipt	Boolean	O	Show the end customer a receipt in the redirection process optional type.	True
autoCapture	Boolean	O	Establishes whether the transaction will be an authorization or pre-authorization. In the latter case, it requires a subsequent capture or release by the merchant.	True
type	Alphanumeric: MOTO ECOM	O	Sets whether the payment request is e-commerce or MO/TO type. If not included, it is e-commerce type by default.	ECOM
description	Alphanumeric Max 1000 characters	O	Description of the transaction.	Product description
city	Alphanumeric Max 100 characters	O	City of cardholder. European merchants: optional for SCA	Barcelona
chCountry	2 characters ISO 3166-1 alfa-2	O	ISO 3166-1 alfa-2 code of cardholder’s country. European merchants: optional for SCA	ES
addressLine1	Alphanumeric Max 250 characters	O	First line of cardholder’s address. European merchants: optional for SCA	Calle Romero 123
addressLine2	Alphanumeric Max 50 characters	O	Cradholder’s zip code. European merchants: optional for SCA	08001
state	Alphanumeric Max 45 characters	O	State or province of the cardholder. European merchants: optional for SCA	Barcelona

Response

This is the response to the payment request in the previous example:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7711867</message>
	<operations>
		<operation sorted-order="1">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Exemptions has been removed</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7711867</payFrexTransactionId>
			<service>TRA</service>
			<status>SUCCESS</status>
		</operation>
		<operation sorted-order="2">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>3dsv2 - processed</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7711867</payFrexTransactionId>
			<paymentDetails>
				<cardNumberToken>5774655584592227</cardNumberToken>
				<extraDetails/>
			</paymentDetails>
			<service>3DSv2</service>
			<status>SUCCESS3DS</status>
		</operation>
		<operation sorted-order="3">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfRTS":"355534686 790190 845433 231030160823","rfContactlessLogo":"false","rfOperationType":"Settle","rfAuthMode":"On","rfDataEntryMode":"Manual","rfCardHolderVerificationMode":"No","rfFuc":"355534686","rfTerminalID":"00000500","rfProcessor":"Redsys","rfMerchantName":"Pruebas Addon 25","rfMerchantCity":"BARCELONA","rfMerchantPostalCode":"08014","rfMerchantAddress":"GRAN VIA DE LES CORTS CATALANE, 159 PLANTA 7","rfMaskedPan":"************2227","rfOperationDateTime":"30/10/23 16:08:23","rfTerminalOperationNumber":"1197","rfAuthNumber":"150515","rfTransactionAmountCurrency":"10,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1197","posTransactionToken":"{\"pucIdMsg\":\"1200\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000001000\",\"pucP11TransactionNumber\":\"845433\",\"pucP12LocalDateTime\":\"231030160823\",\"pucP22ServicePointData\":\"1U00506K3000\",\"pucP38AuthNumber\":\"150515\",\"pucP39ActionCode\":\"000\",\"pucP53SecurityControlInfo\":\"0102000001000000\",\"pinpadId\":\"1440\",\"pinpadAcquirerId\":\"00000500\",\"pinpadManufacturer\":null,\"pinpadModel\":null,\"pinpadSerialNumber\":null,\"pinpadSoftwareName\":null,\"pinpadSoftwareVersion\":null,\"pinpadKernelEmv\":null,\"pinpadVccStrip\":null,\"pinpadVerPup\":null,\"pinpadPciStage\":null,\"pinpadVerEmvParams\":null,\"pinpadEmvType\":null,\"pinpadCapabilities\":null,\"pinpadLanguage\":null,\"transactionType\":\"O\",\"transactionContactless\":\"0\",\"transactionDcc\":\"0\",\"transactionDccComission\":null,\"transactionDccExchangeRate\":null,\"transactionDccMarkUp\":null,\"transactionDccEntity\":null,\"transactionDccBceExchangeRate\":null,\"transactionDccBceMarkUp\":null,\"transactionPanSequenceNumber\":null,\"transactionTerminalOperationNumber\":\"1197\",\"transactionResponseCode\":null,\"transactionCurrency\":\"978\",\"transactionFuc\":\"355534686\",\"cardMaskedPan\":\"************2227\",\"cardAid\":null,\"cardDdfName\":null,\"cardApplicationLabel\":null,\"cardCypherData\":null}","OperationResult":"000"},"threeDsProtocolVersion":"2.2.0"}</details>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Success 'Settle' operation</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<payFrexTransactionId>7711867</payFrexTransactionId>
			<paySolTransactionId>355534686 790190 845433 231030160823</paySolTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Frictioless</cardHolderName>
				<cardNumber>490727****2227</cardNumber>
				<cardNumberToken>5774655584592227</cardNumberToken>
				<cardType>VISA/CREDIT</cardType>
				<expDate>1234</expDate>
				<extraDetails>
					<entry>
						<key>cardCategory</key>
						<value>Not Available</value>
					</entry>
					<entry>
						<key>rememberMe</key>
						<value>true</value>
					</entry>
				</extraDetails>
				<issuerBank>SERVIRED MASTERCARD INTERNACIONAL</issuerBank>
				<issuerCountry>ES</issuerCountry>
			</paymentDetails>
			<paymentMethod>19900</paymentMethod>
			<paymentSolution>caixapucpuce</paymentSolution>
			<status>SUCCESS</status>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</payfrex-response>

JavaScript integration functions

In the JavaScript library, you have several functions you can call. The most important functions (required) have already been covered in previous sections. Below you will find more detailed information:

Define the base URL for the payment gateway (required)

To define it: EPGJS_COMM.setEpgBaseUrl(‘[base URL]’) Set up the AP URL the linked form will send the customer’s data to, with [URL base] being one of the following URLs, depending on the environment you are using:

Staging: https://epgjs-web-stg.addonpayments.com/
Production: https://epgjs-web.addonpayments.com/

This is an example of the function call for the Staging environment:

EPGJS_COMM.setEpgBaseUrl('https://epgjs-web-stg.addonpayments.com/');

Call the form link function (required)

To define it: EPGJS.renderIntegratedCashier(authToken, ‘id. div’, ‘payment solution’);

With all the previous parameters defined, we proceed to call the JS library function to load the form on your platform’s payment page. The parameters for the function “renderIntegratedCashier()” are:

authToken: Authorization token received.
id. div: ID for the <div> element on the payment page of your platform.
payment solution (optional): Payment solution the form will be limited to.
- Only if you have opted for the single payment solution cashier.

If all the parameters in this point and the previous ones are correct, AP will show the payment form in the <div> element sent in the function call.

Once the customer has entered their card or account details, AP will generate a pre-pay token (prepayToken).

Object { prepayToken: "e686282e-fad0-45d7-84b6-eff5bf0c126d", action: "quickpay" }

Define the function to receive the pre-payment token (required)

To define it: EPGJS_COMM.setMerchantPrePayCallback([receive function]) It is used to tell the AP form which function it should call, with the parameter being a JS object that contains the pre-pay token (prepayToken). Your ecommerce platform must have a function programmed on the site to link to the payment form that collects and saves the token to proceed to authorization and settlement of payment. The function can have any name you want, as the name is sent as a parameter [receive function] in the call to the AP JS library. For example, you can set a function “receive_prepayToken” on your platform programmed to receive the object with the pre-pay token and send it to your platform server to be used later. The following example defines the function to receive and show on screen the pre-pay token received in a JS object from AP (this example is for reference only. The customer shouldn’t be able to see the token received):

function receive_prepayToken(object){
alert(object.prepayToken);
return true;
};

With this function defined previously, the function call to the JS library will be as follows:

EPGJS_COMM.setMerchantPrePayCallback(receive_prepayToken);

Define the form limitation to saved accounts (optional)

To define it: EPGJS_COMM.setOnlyRegisteredAccounts([boolean value]) Indicating with [boolean value] if the form should accept new cards and payment accounts (default) or limit customer operations to the cards and/or accounts already saved in the customer ID.

false (default): The payment form allows you to use both cards the customer has saved previously and enter, use and save new cards or accounts.
true: The payment form limits use to the cards and accounts already saved for the customer ID. The customer can’t use or save any new cards or accounts.

Sample function call to limit customer operations to saved cards and accounts:

EPGJS_COMM.setOnlyRegisteredAccounts(true);

Functions related to the CSS style (optional)

Below we have the auxiliary functions related to the CSS style for the payment gateway. 1. Get the CSS class Returns the class(es) for the current CSS theme that apply to the key sent

Function: EPGJS_STYLE.getClass(object)
Parameter: Object to search for.
Use: Getting the classes associated with the class of the object to customize the JS cashier.

2. Get the active CSS theme Returns the keys for the active CSS theme.

Function: EPGJS_STYLE.getCssTheme()
Parameters: None.
Use: Returns the transformation of keys if a theme is applied to the rendering.
Values returned: JSON with the mapping between AP classes and those of the theme chosen by the merchant using the EPGJS_STYLE.setCssTheme(Theme) function.

3. Apply CSS theme Applies one of the two themes sent as a parameter to the payment gateway. If this function isn’t called, the AP form will use the JS default theme.

Function: EPGJS_STYLE.setCssTheme(theme)
Parameters:
- EPGJS_STYLE.DEFAULT_THEME (JS default theme)
- EPGJS_STYLE.DEFAULT_BOOTSTRAP_THEME (JS Bootstrap theme)
Use: Applies one of the two available themes to the payment gateway.
Values returned: None.

You can get a list of the classes in the theme by executing the following JavaScript command:

console.log(theme);
— List the classes of the theme EPGJS_STYLE.DEFAULT_THEME —console.log(EPGJS_STYLE.DEFAULT_THEME);
— List the classes of the theme EPGJS_STYLE.DEFAULT_BOOTSTRAP_THEME —
console.log(EPGJS_STYLE.DEFAULT_BOOTSTRAP_THEME);

Validate PAN

To define it: EPGJS.getValidPan() Notify if the PAN for the card entered is valid. Meaning, whether it passes the Luhn algorithm.

Parameters: None.
Use: If the card isn’t valid, the payment transaction isn’t sent for authorization.
Values returned:
- true: The card PAN is valid.
- false: The card PAN isn’t valid.

Get card brand

To define it: EPGJS.getCardType()

Notifies the brand of the card entered by the customer.

Parameters: None.
Use: Send it in the “cardType” parameter in the payment transaction.
Values returned:
- amex
- astropay
- dankort
- diners_club_carte_blanche
- diners_club_international
- discover
- jcb
- laser
- maestro
- mastercard
- mir
- visa
- visa_electron

Customization

Addon Payments offers several ways to customize the look and content of the cashier. These sections explain how to customize the look, design and language on the form.

In this section you’ll find how to:

Customize the cashier with different styles.
Set a theme with CSS styles for buttons, text and images.

Customized style

The easiest way to customize the look of the payment form is to create a CSS file that defines the colours, fonts and logos for the elements on the payment form. The following steps link your CSS classes to the elements on the Addon Payments form and tell it to use your styles:

Define a JSON object theme that links the names of the CSS classes to the elements on the Addon Payments form.
Create a CSS file using the class names established in the theme.
Call the method “EPGJS_STYLE.setCssTheme” and send your theme as the parameter.

Step one

Create a JSON variable linking the elements on the Addon Payments payment form to the names of your CSS classes. Addon Payments offers set themes linking the payment form to the CSS class names:

DEFAULT_THEME: Links the elements on the payment form to the names of generic CSS classes.
DEFAULT_BOOTSTRAP_THEME: Links the elements on the payment form to the existing elements on the initial theme.

These themes are constants you can switch to the method “EPGJS_STYLE.setCssTheme(string)”. See the section JS Themes in this guide for more information on default themes and defining elements that can be customized.

Step two

Create a CSS file that uses the class names specified in the theme to assign styles to the elements on the payment form. This is an example of how to make the expiry date red using the default theme:

				
					<style>
    .cashier-form-field-expdate {
      color: red;
    }
  </style>

Step three

Call the method “EPGJS_STYLE.setCssTheme” before calling the method “renderCashier”. The method “EPGJS_STYLE.setCssTheme” takes a JSON theme object as the parameter.

This example shows the method call using the default theme:

				
					EPGJS_STYLE.setCssTheme(EPGJS_STYLE.DEFAULT_THEME);

This is an example showing the method call using the initial default theme:

				
					EPGJS_STYLE.setCssTheme(EPGJS_STYLE.DEFAULT_BOOTSTRAP_THEME);

The method “EPGJS_STYLE.setCssTheme” tells the Addon Payments backend which styles to use for the elements on the form and where to apply them. When you call the method “renderCashier”, the payment form is rendered using your styles.

JavaScript themes

The JavaScript themes define the CSS class that controls the look of each element on the payment form. This section defines the customizable parameters and includes the JSON object for the default theme and the initial theme.

Theme elements and classes

This table shows the components that can be customized on the Addon Payments payment form.

Clase Addon Payments	Description
epgjs-cashier-container	EPGJS cashier main DIV container.
epgjs-cashier	EPGJS Cashier. Child of the merchant DIV container.
cashier-edit-row	Account editor row container.
cashier-edit-activate-panel	Account editor panel when the account is active.
cashier-edit-deactivate-panel	Account editor panel when the account is disabled.
cashier-account-row	Account container.
cashier-account-row-heading	Account header.
cashier-register-row	Registered Account container.
cashier-register-row-heading	Registered Account header.
cashier-quickpay-row	QuickPay container.
cashier-quickpay-row-heading	QuickPay header.
cashier-paysol-panel	Payment solution panel.
cashier-form-row-remove	Remove account container for the account editor section.
cashier-form-panel	Cashier form panel.
cashier-form-field	Form field component.
cashier-form-field-label	Form field label.
cashier-form-field-text	Form field text.
cashier-form-field-expdate	Expiry date form field.
cashier-form-field-password	Password form field.
cashier-form-field-cvv	CVV form field.
cashier-form-field-dropdown	Select or Dropdown menu form field.
cashier-form-row-selected	Selected cashier form component.
submit-button	Submit button.

Internationalization

The Addon Payments JavaScript cashier comes in English by default. It can also be shown in Spanish. You can change the language any time, even with the cashier rendered.

You can include any language or customize any tag as long as you define the corresponding literals. If the translation or customization is incomplete, the tags without defined literals will be shown in English.

If you want to render the cashier in a language other than English or Spanish, or customize any of the field literals, get the list of literals for the cashier.

Get the list of literals for the cashier

The function “getI18n()”, in the JavaScript library returns a JSON with the cashier literals in the language supported.

To get the JSON with the cashier literals, assign the output of that function call to a variable and show its content on the console.

Here is an example of the JS code to get and show the JSON with the cashier literals:

var languages= EPGJS_I18N.getI18n();
console.log (languages);

This is an object with the JSON shown on the console:

This is an example with the structure of the JSON you get:

				
					{
  "etiqueta_idioma_1": {
    "id_literal_1": "texto_literal_1",
    "id_literal_2": "texto_literal_2",
    "id_literal_n": "texto_literal_n",
    "objeto_1": {
      "id_literal_1_1": "texto_literal_1_1",
      "id_literal_1_2": "texto_literal_1_2",
      "id_literal_1_n": "texto_literal_1_n",
      "objeto_1_1": {
        "id_literal_objeto_1_1_1": "texto_literal_objeto_1_1_1",
        "id_literal_objeto_1_1_2": "texto_literal_objeto_1_1_2"
      }
    }
  },
  "etiqueta_idioma_2": { … },
  "etiqueta_idioma_n": { … }
}

Creating and loading the JSON with the cashier literals

After downloading the cashier literals, you can translate them and assign them a language tag (English and Spanish are included, so you don’t have to translate them).

The following example shows fragments of the JSON with the JS cashier literals. The first tab has the originals in English and the second, the Catalan translation.

				
					{
  "en": {
    "account": "Account",
    "CreditCards": "Credit Cards",
    "Neteller": "Neteller",
    "Skrill": "Skrill",
    "astropay": {
      "bankAccount": {
        "clabe": "CLABE",
        "debitCard": "Debit Card"
      },
      "cardholdername": "AstroCard Holder Name",
      "cardnumber": "AstroCard Number",
      "cvv": "CVV / CVN",
      "expirationdate": "AstroCard Expiration Date",
      "mail": "By email",
      "mobile": "By mobile"
    },
    "astropayCards": "AstroPay Cards",
    "creditcards": {
      "cardholdername": "Card Holder",
      "cardnumber": "Card Number",
      "cardtype": "Card Type",
      "cvv": "CVV / CVN",
      "expirationdate": "Exp. Date",
      "invalidCVV": "Invalid CVV",
      "invalidChName": "Invalid Card Holder Name",
      "invalidExpDate": "Invalid Expiry Date",
      "invalidPAN": "Invalid Card Number",
      "placeholderdate": "MM/YY",
      "placeholdercvv": "CVV"
    },
    "customer": {
      "firstName": "Customer first name",
      "lastName": "Customer last name",
      "addressLine1": "Customer address",
      "city": "Customer city",
      "postCode": "Customer post code",
      "state": "Customer state",
      "telephone": "Customer telephone"
      "companyName": "Customer company",
      "customerEmail": "Customer email",
      "customerNatIdRadioCC": "CC",
      "customerNatIdRadioCE": "CE",
      "customerNatIdRadioDNI": "DNI",
      "customerNatIdRadioNIT": "NIT",
      "customerNatIdRadioPASS": "PASS",
      "customerNatIdRadioRUC": "RUC",
      "customerNationalId": "Customer national ID",
      "customerNationalIdType": "Customer national ID type",
    }, …

				
					{
  "ca": {
    "account": "Compte d'usuari",
    "CreditCards": "Targetes de crèdit",
    "Neteller": "Neteller",
    "Skrill": "Skrill",
    "astropay": {
      "bankAccount": {
        "clabe": "CLABE",
        "debitCard": "Targeta de dèbit"
      },
      "cardholdername": "Nom del titular",
      "cardnumber": "Número de targeta",
      "cvv": "CVV / CVN",
      "expirationdate": "Data d'expiració",
      "mail": "Via correu electrònic",
      "mobile": "Via mòbil"
    },
    "astropayCards": "AstroPay Cards",
    "creditcards": {
      "cardholdername": "Nom del titular",
      "cardnumber": "Número de targeta",
      "cardtype": "Tipus de targeta",
      "cvv": "CVV / CVN",
      "expirationdate": "Data d'expiració",
      "invalidCVV": "El CCV no és vàlid",
      "invalidChName": "El nom del titular no és vàlid",
      "invalidExpDate": "La data de caducitat no és vàlida",
      "invalidPAN": "El número de la targeta no és vàlid",
      "placeholderdate": "MM/YY",
      "placeholdercvv": "CVV"
    },
    "customer": {
      "firstName": "Nom",
      "lastName": "Cognoms",
      "addressLine1": "Direcció",
      "city": "Ciutat",
      "postCode": "Codi postal",
      "state": "Província/estat",
      "telephone": "Núm. de telèfon",
      "companyName": "Nom de l'empresa",
      "customerEmail": "Correu electrònic",
      "customerNatIdRadioCC": "CC",
      "customerNatIdRadioCE": "CE",
      "customerNatIdRadioDNI": "DNI",
      "customerNatIdRadioNIT": "NIT",
      "customerNatIdRadioPASS": "PASS",
      "customerNatIdRadioRUC": "RUC",
      "customerNationalId": "Número d'identificació nacional",
      "customerNationalIdType": "Tipus de document d'identificació"
    }, …

The next step is a variable declaration that contains the JSON created with the translation or customization.

In the next fragment of the JS example, we declare the constant “translations” with the JSON with the Catalan translation of the cashier literals. One unique variable or constant can contain many translations. So, it is important to assign a field at the beginning that identifies the language:

				
					const traducciones = {
  "ca": {
    "account": "Compte d'usuari",
    "astropay": {
      "bankAccount": {
        "clabe": "CLABE",
        "debitCard": "Targeta de dèbit"
      },
      "cardholdername": "Nom del titular",
      "cardnumber": "Número de targeta",
      "cvv": "CVV / CVN",
      "expirationdate": "Data d'expiració",
      "mail": "Via correu electrònic",
      "mobile": "Via mòbil"
    },
    "astropayCards": "AstroPay Cards",
    "bank": {
      "accTypeRadioCM": "Compte Mestre",
      "accTypeRadioCheckings": "Pagaments",
      "accTypeRadioSavings": "Estalvis",
      "accTypeRadioVista": "Vista",
      "accountNum": "Número de compte bancària",
      "accountType": "Tipus de compte bancari",
      "bankAccountDetails": "Detalls del compte bancari",
      "bankBranchCode": "Codi de la sucursal",
      "bankBranchName": "Nom de la sucursal",
      "bankCity": "Ciutat del banc",
      "bankCode": "Codi del banc",
      "bankName": "Nom del banc",
      "bankProvinceCode": "Província del banc",
      "firstName": "Nom",
      "lastName": "Cognoms"
    },
    "bankAccountNum": "Número del compte bancari",
    "bankBic": "SWIFT / BIC",
    "bankBranchCode": "Codi de sucursal",
    "breakoutgaming": {
      "account": "Clau d'autorització de compte",
      "accountPassword": "Clau de cartera digital"
    },
...

Finally, to load the language, launch the function setI18n(constant):

EPGJS_I18N.setI18n(translations);

Changing cashier language

To change the cashier language, you just need to call the function “setLang(language)”, sending the text for the field that identifies the cashier or language you want to apply as the parameter.

Sample JS code to change the JS cashier literals to Spanish (included with the cashier, no additional programming required):

EPGJS_I18N.setLang('es');

Sample JS code to change the JS cashier literals to Catalan (after declaration and loading from the examples in the points above):

EPGJS_I18N.setLang('ca');

This function can be called at any time, even if the cashier is already rendered and it will change the literals to the language or customization indicated.

Complement your JavaScript integration

Transaction flow

Environments: Staging and Production

Getting the authToken

Parameters of the authToken request

Rendering the cashier on your frontend

Getting the prepayToken

DIY (Do It Yourself)

Step one: Define the HTML

Step two: Create a JavaScript variable

Step three: Call the function

Step four: Rendering the cashier

Charge call

Response

JavaScript integration functions

Customization

Customized style

Step one

Step two

Step three

JavaScript themes

Theme elements and classes

Internationalization

Get the list of literals for the cashier

Creating and loading the JSON with the cashier literals

Changing cashier language

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Complement your JavaScript integration

Transaction flow

Environments: Staging and Production

Getting the authToken

Parameters of the authToken request

Rendering the cashier on your frontend

Getting the prepayToken

DIY (Do It Yourself)

Step one: Define the HTML

Step two: Create a JavaScript variable

Step three: Call the function

Step four: Rendering the cashier

Charge call

Response

JavaScript integration functions

Customization

Customized style

Step one

Step two

Step three

JavaScript themes

Theme elements and classes

Internationalization

Get the list of literals for the cashier

Creating and loading the JSON with the cashier literals

Changing cashier language

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Consulta la documentación de las distintas secciones de integraciones:

Addon Payments

Cyberpac

POS integrated Payments

Addon Payments

Consult the documentation of the different integrations sections:​

Consult the documentation of the different integrations sections: