JavaScript Integration

Introduction

This section outlines the steps to follow to perform the JavaScript integration. In this integration, the Addon Payments cashier is rendered on the front end of your e-commerce and is hosted on the gateway. This reduces the PCI DSS requirements on your merchant side.

Attached is sample code to complete steps, requests formed and responses received from the gateway. Parameters, operations and procedures may vary between payment solutions or services. In this guide we indicate the most common ones for most payment solutions.

The following links will help you during your integration:

Glossary, to familiarize you with the concepts we will use throughout the documentation.
Postman, to test the operations of this integration.
SDKs, complete tool to integrate Addon Payments in a fast, flexible and easy way.
Complement your JavaScript integration.

Finally, at the end of this guide you will find links to other documents of interest.

We hope you find this guide useful.

Integration workflow

Summary:

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 Charge 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 offers 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 where to send the request, charge or authToken, according to the environment where you operate:

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, you have a table with the JavaScript AP library that you must import and the call to define the base URL of the payment gateway.

You must add, on the checkout page of your e-commerce platform, an HTML <script> element with the path to the AP JS library. This path must include the version of the library to load. We currently recommend 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 to get the authToken so we can render the cashier. This step is common to all integration.

Obtaining the authToken is common to all JavaScript integration, regardless of the operation you are going to perform (authorisation, pre-authorisation, etc.).

This is an example of a request to obtain the authToken, the first as a string and the second as cURL.

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

				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId":"12345",
    "merchantKey":"356a8a53-b188-404d-b6c1-5bd44f48066a",
    "productId":"123450001",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "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": "23ed4dda-79f5-4a60-bcc0-52fe2f27b26e"
}

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

The authorization tokens received have the following characteristics:

Valid for 30 minutes.
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. For more rendering options, see our complement JavaScript guide. Below is a simple example showing how to render the card payment method:

				
					<!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', 'creditcards');
            EPGJS_COMM.setMerchantPrePayCallback(prePayCallback);
        }
        window.onload = displayingMessageOnButtonClick;
    </script>
</body>
</html>

In this example code there are 3 mandatory functions for the correct functioning of the JavaScript cashier. These are:

1. EPGJS_COMM.setEpgBaseUrl(‘base URL’): Sets the URL to which the form will send the customer data. It changes according to the environment where you are operating. You can see the URLs in this section.

2. EPGJS.renderIntegratedCashier: It is the render function of the cashier. It establishes how it will look like. In this example, the cashier renders only credit cards. If you want to load all the payment solutions you have available, delete ‘creditcards’ from “EPGJS.renderIntegratedCashier”. It would look like this:

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

3. EPGJS_COMM.setMerchantPrePayCallback(receive function): Sets the capture of the response, which we must create previously.

This will allow you to render the cashier in the front-end div so that the customer can proceed with the payment, as you see in the image below. When the customer proceeds with the payment button, Addon Payments will return an object with the prepayToken, which will allow you to send the payment request.

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. The authorization tokens received have the following characteristics:

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

Required and optional parameters charge JavaScript

These are the common parameters for the different operations of the charge JavaScript in card payments: authorization, pre-authorization, card validation, card storage, subscription plan registration and payouts.

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.

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

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

Card payments

Your platform must send several parameters and their respective values to generate a valid request to send to AP. For each request and use case, you will have a sample request, a table with the required and optional parameters and a sample response.

Authorization

Below we’ll look at the steps for processing a card payment via JavaScript in more detail.

Getting the authToken and rendering frontend cashier

You can learn how to obtain the authToken and how to render the frontend cashier in the previous sections.

Charge

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

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.

These are some examples of requests for authorization of card payments, the first as a string and the second as cURL.

				
					{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "apiVersion": "5",
    "amount": "10.00",
    "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",
    "awaitingURL": "https:// micomercio.com/url-espera.php",
    "operationType"= "debit"
}

				
					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",
    "apiVersion": "5",
    "amount": "10.00",
    "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"
}'

To learn more about when to redirect the client, visit the Redirecting customer section.

You may have to redirect the customer to another URL to complete payment. For example, for card payments so the customer can authenticate they are the account holder.

This is a sample request to redirect to the issuer’s SCA for authentication, the URL to redirect to is in the field “redirectionResponse”

				
					<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
<payfrex-response operation-size=\"2\">
	<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>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>cbf23a6a_70a8_402d_a27d_c7ae2e61e121</uuid>
			</respCode>
			<service>TRA</service>
			<status>SUCCESS</status>
		</operation>
		<operation sorted-order=\"2\">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Starting 3DSecure 2.0 process.</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<originalPayFrexTransactionId>7711867</originalPayFrexTransactionId>
			<payFrexTransactionId>1004146</payFrexTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Frictioless</cardHolderName>
				<extraDetails>
					<entry>
						<key>threeDSMethodData</key>
						<value>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVlMDRiZjZjLTk0NWItNDg0ZC1hMzE0LTk1NjhjYTk1NmY4YiIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjogImh0dHBzOi8vY2hlY2tvdXQuc3RnLWV1LXdlc3QzLmVwZ2ludC5jb20vRVBHQ2hlY2tvdXQvY2FsbGJhY2svZ2F0aGVyRGV2aWNlTm90aWZpY2F0aW9uL3BheXNvbC8zZHN2Mi8xMDA0MTQ2In0=</value>
					</entry>
					<entry>
						<key>threeDSv2Token</key>
						<value>ee04bf6c-945b-484d-a314-9568ca956f8b</value>
					</entry>
				</extraDetails>
			</paymentDetails>
			<redirectionResponse>redirect:https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/3dsv2/redirect?action=gatherdevice&amp;params=eyJ0aHJlZURTdjJUb2tlbiI6ImVlMDRiZjZjLTk0NWItNDg0ZC1hMzE0LTk1NjhjYTk1NmY4YiIsInRocmVlRFNNZXRob2RVcmwiOiJodHRwczovL21vY2stZHMuc3RnLWV1LXdlc3QzLmVwZ2ludC5jb20vcHVibGljL21ldGhvZC1kYXRhLyIsInRocmVlRFNNZXRob2REYXRhIjoiZXlKMGFISmxaVVJUVTJWeWRtVnlWSEpoYm5OSlJDSTZJbVZsTURSaVpqWmpMVGswTldJdE5EZzBaQzFoTXpFMExUazFOamhqWVRrMU5tWTRZaUlzSUNKMGFISmxaVVJUVFdWMGFHOWtUbTkwYVdacFkyRjBhVzl1VlZKTUlqb2dJbWgwZEhCek9pOHZZMmhsWTJ0dmRYUXVjM1JuTFdWMUxYZGxjM1F6TG1Wd1oybHVkQzVqYjIwdlJWQkhRMmhsWTJ0dmRYUXZZMkZzYkdKaFkyc3ZaMkYwYUdWeVJHVjJhV05sVG05MGFXWnBZMkYwYVc5dUwzQmhlWE52YkM4elpITjJNaTh4TURBME1UUTJJbjA9IiwiYnJhbmQiOiJWSVNBIiwicmVzdW1lQXV0aGVudGljYXRpb24iOiJodHRwczovL2NoZWNrb3V0LnN0Zy1ldS13ZXN0My5lcGdpbnQuY29tL0VQR0NoZWNrb3V0L3JldHVybnVybC9mcmljdGlvbmxlc3MvcGF5c29sLzNkc3YyLzEwMDQxNDY/dGhyZWVEU3YyVG9rZW49ZWUwNGJmNmMtOTQ1Yi00ODRkLWEzMTQtOTU2OGNhOTU2ZjhiIiwicmVuZGVyQ2FzaGllckxvY2F0aW9uIjoiaHR0cHM6Ly9lcGdqcy1yZW5kZXJjYXNoaWVyLXN0Zy5lYXN5cGF5bWVudGdhdGV3YXkuY29tIiwiY2hhbGxlbmdlV2luZG93c1NpemUiOiIwNSJ9</redirectionResponse>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>cbf23a6a_70a8_402d_a27d_c7ae2e61e121</uuid>
			</respCode>
			<service>3DSv2</service>
			<status>REDIRECTED</status>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</payfrex-response>

Parameters of charge request

The required/mandatory and optional parameters for a charge authorization Request are listed in this table.

Response

Visit our section on Managing notifications to learn more about its structure.

Once the customer has completed payment, they will be redirected to the success or error URL depending on the transaction result. Additionally, the merchant statusURL will be notified of the payment result.

				
					<?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>

Pre-authorization

Pre-authorizations are a two-step payment method. After the customer authorizes the transaction, the funds are put on hold in their account or card balance. The merchant has 30 days to confirm or decline the pre-authorization. However, payment is not ensured after 7 days. It is important to note that the merchant doesn’t receive the funds from the pre-authorization until it is confirmed.

Pre-authorizations, if the transaction is authorized, will show a “Pending” status. You can manually capture these transactions in the Addon Payments BackOffice Portal or with an H2H request to capture the amount.

Getting the authToken and rendering frontend cashier

You can learn how to obtain the authToken and how to render the frontend cashier in the previous sections.

Charge

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

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.

These are some examples of requests for pre-authorization of card payments, the first as a string and the second as cURL.

				
					{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "apiVersion": "5",
    "amount": "10.00",
    "currency": "EUR",
    "country": "ES",
    "customerId": "000001",
    "paymentSolution": "creditcards",
    "productId": "123450001",
    "autoCapture": false,
    "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",
    "awaitingURL": "https:// micomercio.com/url-espera.php",
    "operationType":"debit"
}

				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 839dabca-217d-4851-a426-ff3ccf0fa872' \
--data-raw '{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "apiVersion": "5",
    "amount": "10.00",
    "currency": "EUR",
    "country": "ES",
    "customerId": "000001",
    "paymentSolution": "creditcards",
    "productId": "123450001",
    "autoCapture": false,
    "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",
    "operationType": "debit"
}'

To learn more about when to redirect the client, visit the Redirecting customer section.

You may have to redirect the customer to another URL to complete payment. For example, for card payments so the customer can authenticate they are the account holder.

This is a sample request to redirect to the issuer’s SCA for authentication, the URL to redirect to is in the field “redirectionResponse”

				
					<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
<payfrex-response operation-size=\"2\">
	<message>WorkFlow has finished successfully, for transaction Id: 7711906</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>7711906</payFrexTransactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>fc69c0fc_57c9_42f5_899b_495da1e4539d</uuid>
			</respCode>
			<service>TRA</service>
			<status>SUCCESS</status>
		</operation>
		<operation sorted-order=\"2\">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Starting 3DSecure 2.0 process.</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<originalPayFrexTransactionId>7711906</originalPayFrexTransactionId>
			<payFrexTransactionId>1004158</payFrexTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Frictioless</cardHolderName>
				<extraDetails>
					<entry>
						<key>threeDSMethodData</key>
						<value>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjM2MGQ3MDVmLWM0ZmUtNGU5NC1hMjg2LTcxMTBkZDA4MDQ1NCIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjogImh0dHBzOi8vY2hlY2tvdXQzMy5zdGctZXUtd2VzdDMuZXBnaW50LmNvbS9FUEdDaGVja291dC9jYWxsYmFjay9nYXRoZXJEZXZpY2VOb3RpZmljYXRpb24vcGF5c29sLzNkc3YyLzEwMDQxNTgifQ==</value>
					</entry>
					<entry>
						<key>threeDSv2Token</key>
						<value>360d705f-c4fe-4e94-a286-7110dd080454</value>
					</entry>
				</extraDetails>
			</paymentDetails>
			<redirectionResponse>redirect:https://checkout33.stg-eu-west3.epgint.com/EPGCheckout/rest/online/3dsv2/redirect?action=gatherdevice&amp;params=eyJ0aHJlZURTdjJUb2tlbiI6IjM2MGQ3MDVmLWM0ZmUtNGU5NC1hMjg2LTcxMTBkZDA4MDQ1NCIsInRocmVlRFNNZXRob2RVcmwiOiJodHRwczovL21vY2stZHMuc3RnLWV1LXdlc3QzLmVwZ2ludC5jb20vcHVibGljL21ldGhvZC1kYXRhLyIsInRocmVlRFNNZXRob2REYXRhIjoiZXlKMGFISmxaVVJUVTJWeWRtVnlWSEpoYm5OSlJDSTZJak0yTUdRM01EVm1MV00wWm1VdE5HVTVOQzFoTWpnMkxUY3hNVEJrWkRBNE1EUTFOQ0lzSUNKMGFISmxaVVJUVFdWMGFHOWtUbTkwYVdacFkyRjBhVzl1VlZKTUlqb2dJbWgwZEhCek9pOHZZMmhsWTJ0dmRYUXpNeTV6ZEdjdFpYVXRkMlZ6ZERNdVpYQm5hVzUwTG1OdmJTOUZVRWREYUdWamEyOTFkQzlqWVd4c1ltRmpheTluWVhSb1pYSkVaWFpwWTJWT2IzUnBabWxqWVhScGIyNHZjR0Y1YzI5c0x6TmtjM1l5THpFd01EUXhOVGdpZlE9PSIsImJyYW5kIjoiVklTQSIsInJlc3VtZUF1dGhlbnRpY2F0aW9uIjoiaHR0cHM6Ly9jaGVja291dDMzLnN0Zy1ldS13ZXN0My5lcGdpbnQuY29tL0VQR0NoZWNrb3V0L3JldHVybnVybC9mcmljdGlvbmxlc3MvcGF5c29sLzNkc3YyLzEwMDQxNTg/dGhyZWVEU3YyVG9rZW49MzYwZDcwNWYtYzRmZS00ZTk0LWEyODYtNzExMGRkMDgwNDU0IiwicmVuZGVyQ2FzaGllckxvY2F0aW9uIjoiaHR0cHM6Ly9lcGdqcy1yZW5kZXJjYXNoaWVyLXN0Zy5lYXN5cGF5bWVudGdhdGV3YXkuY29tIiwiY2hhbGxlbmdlV2luZG93c1NpemUiOiIwNSJ9</redirectionResponse>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>fc69c0fc_57c9_42f5_899b_495da1e4539d</uuid>
			</respCode>
			<service>3DSv2</service>
			<status>REDIRECTED</status>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</payfrex-response>

Charge request parameters

The required/mandatory and optional parameters for a charge pre-authorization Request are listed in this table.

In addition to those parameters, for a pre-authorization you must also include:

autoCapture: false

Response

Visit our section on Managing notifications to learn more about its structure.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7711906</message>
	<operations>
		<operation sorted-order="1">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Invalid threeDSv2Token.</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7711906</payFrexTransactionId>
			<service>3DSv2</service>
			<status>ERROR3DS</status>
		</operation>
		<operation sorted-order="2">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>3dsv2 - processed</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7711906</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 845454 231030163255","rfContactlessLogo":"false","rfOperationType":"Auth","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:32:55","rfTerminalOperationNumber":"1198","rfAuthNumber":"965487","rfTransactionAmountCurrency":"10,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1198","posTransactionToken":"{\"pucIdMsg\":\"1100\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000001000\",\"pucP11TransactionNumber\":\"845454\",\"pucP12LocalDateTime\":\"231030163255\",\"pucP22ServicePointData\":\"1U00506K3000\",\"pucP38AuthNumber\":\"965487\",\"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\":\"1198\",\"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 'Auth' operation</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<payFrexTransactionId>7711906</payFrexTransactionId>
			<paySolTransactionId>355534686 790190 845454 231030163255</paySolTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Frictioless</cardHolderName>
				<cardNumber>490727****2227</cardNumber>
				<cardNumberToken>5774655584592227</cardNumberToken>
				<cardType>VISA/CREDIT OR DEBIT</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>PENDING</status>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</payfrex-response>

Card validation

You can validate a customer’s card for future operations by generating Addon Payments tokens. This operation is also known as Open To Buy (OTB).

Normally, these card validations for an amount of 0 are used to save the customer’s card for future payments. In this case, we recommend you also use the following parameters:

amount: 0
paymentRecurringType: newCof
challengeInd: 04 (recommended to force SCA for the transaction so the issuer doesn’t decline future requests)

This operation validates that the card is operational when the request is made, although it can’t guarantee future payments will be authorized.

Getting the authToken and rendering frontend cashier

You can learn how to obtain the authToken and how to render the frontend cashier in the previous sections.

Charge

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

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.

These are some examples of requests for a card validation, the first as a string and the second as cURL.

				
					{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "apiVersion": "5",
    "amount": "0.00",
    "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",
    "awaitingURL": "https:// micomercio.com/url-espera.php",
    "operationType":"debit"
}

				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 96d2fc44-0ad8-492d-96f8-b733d82eefbd' \
--data-raw '{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "apiVersion": "5",
    "amount": "0.00",
    "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",
    "operationType":"debit"
}'

To learn more about when to redirect the client, visit the Redirecting customer section.

You may have to redirect the customer to another URL to complete payment. For example, for card payments so the customer can authenticate they are the account holder.

This is a sample request to redirect to the issuer’s SCA for authentication, the URL to redirect to is in the field “redirectionResponse”

				
					<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
<payfrex-response operation-size=\"2\">
	<message>WorkFlow has finished successfully, for transaction Id: 7711936</message>
	<operations>
		<operation sorted-order=\"1\">
			<amount>0.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Exemptions has been removed</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7711936</payFrexTransactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>cbf23a6a_70a8_402d_a27d_c7ae2e61e121</uuid>
			</respCode>
			<service>TRA</service>
			<status>SUCCESS</status>
		</operation>
		<operation sorted-order=\"2\">
			<amount>0.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Starting 3DSecure 2.0 process.</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<originalPayFrexTransactionId>7711936</originalPayFrexTransactionId>
			<payFrexTransactionId>1004167</payFrexTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Frictioless</cardHolderName>
				<extraDetails>
					<entry>
						<key>threeDSMethodData</key>
						<value>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjJjMDk3OWQyLWQyNTctNDVhMS05YmI0LTk2ODAyMmVlYjZkNyIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjogImh0dHBzOi8vY2hlY2tvdXQuc3RnLWV1LXdlc3QzLmVwZ2ludC5jb20vRVBHQ2hlY2tvdXQvY2FsbGJhY2svZ2F0aGVyRGV2aWNlTm90aWZpY2F0aW9uL3BheXNvbC8zZHN2Mi8xMDA0MTY3In0=</value>
					</entry>
					<entry>
						<key>threeDSv2Token</key>
						<value>2c0979d2-d257-45a1-9bb4-968022eeb6d7</value>
					</entry>
				</extraDetails>
			</paymentDetails>
			<redirectionResponse>redirect:https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/3dsv2/redirect?action=gatherdevice&amp;params=eyJ0aHJlZURTdjJUb2tlbiI6IjJjMDk3OWQyLWQyNTctNDVhMS05YmI0LTk2ODAyMmVlYjZkNyIsInRocmVlRFNNZXRob2RVcmwiOiJodHRwczovL21vY2stZHMuc3RnLWV1LXdlc3QzLmVwZ2ludC5jb20vcHVibGljL21ldGhvZC1kYXRhLyIsInRocmVlRFNNZXRob2REYXRhIjoiZXlKMGFISmxaVVJUVTJWeWRtVnlWSEpoYm5OSlJDSTZJakpqTURrM09XUXlMV1F5TlRjdE5EVmhNUzA1WW1JMExUazJPREF5TW1WbFlqWmtOeUlzSUNKMGFISmxaVVJUVFdWMGFHOWtUbTkwYVdacFkyRjBhVzl1VlZKTUlqb2dJbWgwZEhCek9pOHZZMmhsWTJ0dmRYUXVjM1JuTFdWMUxYZGxjM1F6TG1Wd1oybHVkQzVqYjIwdlJWQkhRMmhsWTJ0dmRYUXZZMkZzYkdKaFkyc3ZaMkYwYUdWeVJHVjJhV05sVG05MGFXWnBZMkYwYVc5dUwzQmhlWE52YkM4elpITjJNaTh4TURBME1UWTNJbjA9IiwiYnJhbmQiOiJWSVNBIiwicmVzdW1lQXV0aGVudGljYXRpb24iOiJodHRwczovL2NoZWNrb3V0LnN0Zy1ldS13ZXN0My5lcGdpbnQuY29tL0VQR0NoZWNrb3V0L3JldHVybnVybC9mcmljdGlvbmxlc3MvcGF5c29sLzNkc3YyLzEwMDQxNjc/dGhyZWVEU3YyVG9rZW49MmMwOTc5ZDItZDI1Ny00NWExLTliYjQtOTY4MDIyZWViNmQ3IiwicmVuZGVyQ2FzaGllckxvY2F0aW9uIjoiaHR0cHM6Ly9lcGdqcy1yZW5kZXJjYXNoaWVyLXN0Zy5lYXN5cGF5bWVudGdhdGV3YXkuY29tIiwiY2hhbGxlbmdlV2luZG93c1NpemUiOiIwNSJ9</redirectionResponse>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>cbf23a6a_70a8_402d_a27d_c7ae2e61e121</uuid>
			</respCode>
			<service>3DSv2</service>
			<status>REDIRECTED</status>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</payfrex-response>

Charge request parameters

The required/mandatory and optional parameters for a charge card validation Request are listed in this table.

In addition to those parameters, you must also include the ones on the table below. The type shows whether the element is Required (R) or Optional (O):

Field	Format	Type	Description	Example
amount	Numerical with decimal 0~1000000.00	R	Transaction amount. If the total has decimal places, the separator is a point (.). No separator can be used for thousands. For card validations, it must be “0”.	0
paymentRecurringType	– newCof: One-off payments, without a fixed amount or periodicity. – newSubscription: Recurring payments with fixed amount and periodicity. – newInstallment: Postponed payment limited to individual purchase with fixed amount and periodicity.	O	Recurring or successive payment type. Note if the COF transaction is initial or successive, and the reason or purpose for payment.	newCof
challengeInd	Accepted values: – 01: no preference (default value if this parameter is not sent) – 02: avoid challenge – 03: require challenge (trade preference) – 04: require challenge (mandatory) – 05: avoid challenge (performed transaction risk analysis) – 06: avoid challenge (only in data sharing) – 07: avoid challenge (SCA already done) – 08: avoid challenge (use whitelist exemption) – 09: avoid challenge (request whitelist)	O	Indicates the preference set by the merchant for an authentication process. The issuer can modify the preference specified in this field.	04

Response

Visit our section on Managing notifications to learn more about its structure.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7711936</message>
	<operations>
		<operation sorted-order="1">
			<amount>0.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Invalid threeDSv2Token.</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7711936</payFrexTransactionId>
			<service>3DSv2</service>
			<status>ERROR3DS</status>
		</operation>
		<operation sorted-order="2">
			<amount>0.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>3dsv2 - processed</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7711936</payFrexTransactionId>
			<paymentDetails>
				<cardNumberToken>5774655584592227</cardNumberToken>
				<extraDetails/>
			</paymentDetails>
			<service>3DSv2</service>
			<status>SUCCESS3DS</status>
		</operation>
		<operation sorted-order="3">
			<amount>0.00</amount>
			<currency>EUR</currency>
			<details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfRTS":"355534686 790190 845464 231030164630","rfContactlessLogo":"false","rfOperationType":"Auth","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:46:30","rfTerminalOperationNumber":"1199","rfAuthNumber":"313990","rfTransactionAmountCurrency":"0,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1199","posTransactionToken":"{\"pucIdMsg\":\"1100\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000000000\",\"pucP11TransactionNumber\":\"845464\",\"pucP12LocalDateTime\":\"231030164630\",\"pucP22ServicePointData\":\"1U00506K3000\",\"pucP38AuthNumber\":\"313990\",\"pucP39ActionCode\":\"085\",\"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\":\"1199\",\"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 'Auth' operation</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<payFrexTransactionId>7711936</payFrexTransactionId>
			<paySolTransactionId>355534686 790190 845464 231030164630</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>

Saving cards

You can save cards on Addon Payments by generating tokens. This operation has several use cases, which we will look at below.

Storing cards

Card storage is controlled using the parameters sent in the request. If the customer completes the transaction successfully, you will receive the “cardNumberToken”, which is the token for the customer’s card. This field is directly related to the “customerId” sent in the payment request. Plus, remember that one “customerId” can be associated with several card tokens.

Use cases and parameters

The table below shows use cases for saving cards and the parameters required. These parameters are optional:

Objective	Parameter	Type	Value	Description
Card saving	forceTokenRequest	Boolean	true	If you force token saving you will receive the card token and the card will be saved for later use. You must inform the customer that you will be storing their card information. Note: Even if you force token saving, if you show the “Remember me” checkbox and the customer does NOT check it, the token will not be saved. To force token saving, do not send the “showRememberMe” parameter or send it to “false”.
Do not save card	showRememberMe	Boolean	false	The checkbox in our form that allows the customer to choose whether or not to save the card will be hidden. You will not have the “cardNumberToken” in the response and it will not appear in subsequent payments from the same customer (customerId). Note: To make sure it is NOT saved, additionally send “forceTokenRequest=false”, this way, even if the “Remember Me” checkbox is displayed and checked, the token will not be saved.
Allow customer to save card	showRememberMe	Boolean	true	It will show the “Remember me” card save check. If the customer chooses to save the card and the transaction is authorized, it will be saved for this customerId and you will get the token in the response. If the customer does not check “Remember me”, the card token will not be saved.
Do not send any of the above parameters	N/A	N/A	N/A	If none of the above parameters are sent, the “Remember me” card save check will be displayed. If the customer checks it, the card will be saved for later use. If the customer does not check it, the token will be generated but you will not be able to use it for further payments. Note: In the notification you will receive the “rememberMe” with value “false”, so you will know that the token cannot be used.

Getting the authToken

The first step is to get the authToken so we can render the cashier. A request must be sent with at least the info shown below. In this case, “showRememberMe:true” has been added to allow the customer to store their card.

				
					{
    "merchantId":"12345",
    "merchantKey":"356a8a53-b188-404d-b6c1-5bd44f48066a",
    "productId":"123450001",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "showRememberMe":true
}

				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId":"12345",
    "merchantKey":"356a8a53-b188-404d-b6c1-5bd44f48066a",
    "productId":"123450001",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "showRememberMe":true
}'

				
					{
    "authToken": "32041b38-fdcd-43f2-b7f6-26b5d73b28e4"
}

				
					{
    "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.

Rendering cashier

The next step is rendering the cashier. See the corresponding section in this guide.

Charge

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

				
					{
    "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"
}

				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 0966178f-e1f7-4d47-9a66-7a77bc8d692b' \
--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"
}'

This is a sample response you would receive to redirect the customer for authentication:

				
					<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
<payfrex-response operation-size=\"2\">
	<message>WorkFlow has finished successfully, for transaction Id: 7712092</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>7712092</payFrexTransactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>cbf23a6a_70a8_402d_a27d_c7ae2e61e121</uuid>
			</respCode>
			<service>TRA</service>
			<status>SUCCESS</status>
		</operation>
		<operation sorted-order=\"2\">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Starting 3DSecure 2.0 process.</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<originalPayFrexTransactionId>7712092</originalPayFrexTransactionId>
			<payFrexTransactionId>1004197</payFrexTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Frictioless</cardHolderName>
				<extraDetails>
					<entry>
						<key>threeDSMethodData</key>
						<value>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImJjNzIwNzZjLTI5MzktNDQ1Zi05MzMwLTg5OWM5Nzk1Y2VjMSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjogImh0dHBzOi8vY2hlY2tvdXQuc3RnLWV1LXdlc3QzLmVwZ2ludC5jb20vRVBHQ2hlY2tvdXQvY2FsbGJhY2svZ2F0aGVyRGV2aWNlTm90aWZpY2F0aW9uL3BheXNvbC8zZHN2Mi8xMDA0MTk3In0=</value>
					</entry>
					<entry>
						<key>threeDSv2Token</key>
						<value>bc72076c-2939-445f-9330-899c9795cec1</value>
					</entry>
				</extraDetails>
			</paymentDetails>
			<redirectionResponse>redirect:https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/3dsv2/redirect?action=gatherdevice&amp;params=eyJ0aHJlZURTdjJUb2tlbiI6ImJjNzIwNzZjLTI5MzktNDQ1Zi05MzMwLTg5OWM5Nzk1Y2VjMSIsInRocmVlRFNNZXRob2RVcmwiOiJodHRwczovL21vY2stZHMuc3RnLWV1LXdlc3QzLmVwZ2ludC5jb20vcHVibGljL21ldGhvZC1kYXRhLyIsInRocmVlRFNNZXRob2REYXRhIjoiZXlKMGFISmxaVVJUVTJWeWRtVnlWSEpoYm5OSlJDSTZJbUpqTnpJd056WmpMVEk1TXprdE5EUTFaaTA1TXpNd0xUZzVPV001TnprMVkyVmpNU0lzSUNKMGFISmxaVVJUVFdWMGFHOWtUbTkwYVdacFkyRjBhVzl1VlZKTUlqb2dJbWgwZEhCek9pOHZZMmhsWTJ0dmRYUXVjM1JuTFdWMUxYZGxjM1F6TG1Wd1oybHVkQzVqYjIwdlJWQkhRMmhsWTJ0dmRYUXZZMkZzYkdKaFkyc3ZaMkYwYUdWeVJHVjJhV05sVG05MGFXWnBZMkYwYVc5dUwzQmhlWE52YkM4elpITjJNaTh4TURBME1UazNJbjA9IiwiYnJhbmQiOiJWSVNBIiwicmVzdW1lQXV0aGVudGljYXRpb24iOiJodHRwczovL2NoZWNrb3V0LnN0Zy1ldS13ZXN0My5lcGdpbnQuY29tL0VQR0NoZWNrb3V0L3JldHVybnVybC9mcmljdGlvbmxlc3MvcGF5c29sLzNkc3YyLzEwMDQxOTc/dGhyZWVEU3YyVG9rZW49YmM3MjA3NmMtMjkzOS00NDVmLTkzMzAtODk5Yzk3OTVjZWMxIiwicmVuZGVyQ2FzaGllckxvY2F0aW9uIjoiaHR0cHM6Ly9lcGdqcy1yZW5kZXJjYXNoaWVyLXN0Zy5lYXN5cGF5bWVudGdhdGV3YXkuY29tIiwiY2hhbGxlbmdlV2luZG93c1NpemUiOiIwNSJ9</redirectionResponse>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>cbf23a6a_70a8_402d_a27d_c7ae2e61e121</uuid>
			</respCode>
			<service>3DSv2</service>
			<status>REDIRECTED</status>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</payfrex-response>

Response

This is the response with the token of the card to save:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7712092</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>7712092</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>7712092</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 845525 231030180016","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 18:00:16","rfTerminalOperationNumber":"1200","rfAuthNumber":"372125","rfTransactionAmountCurrency":"10,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1200","posTransactionToken":"{\"pucIdMsg\":\"1200\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000001000\",\"pucP11TransactionNumber\":\"845525\",\"pucP12LocalDateTime\":\"231030180016\",\"pucP22ServicePointData\":\"1U00506K3000\",\"pucP38AuthNumber\":\"372125\",\"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\":\"1200\",\"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>7712092</payFrexTransactionId>
			<paySolTransactionId>355534686 790190 845525 231030180016</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>

Show cards

In Addon Payments you can decide whether to show the saved cards to the customer. This operation is related to the saved cards and the customer’s identifier.

To show the saved cards to a customer these requirements must be met:

You have forced card saving as shown in the previous section or the customer has decided to save their card by checking the “Remember me” checkbox. The card token that is saved is associated with a customer identifier (customerId).
In the following transactions, the customerId must be the same as the one used to save the card. So these are displayed in the payment cashier.

For example, the customer with customerId “01” makes a purchase in your e-commerce and decides to check the “remember me” box, so his card is saved. Later, the same customer (with “customerId” “01”) makes another purchase and has his card available at the cashier.

If the customer enters your platform as a guest, he will have another “customerId”, so he will not see his cards saved.

Get authtToken, render cashier and charge

The request to show the cards to a customer is the same as the rest of the operations. However, you must send the same “customerId” that has been used to store cards.

You can see how to get the authToken, render the cashier and make the charge in the corresponding sections.

A customer can have several saved cards. If the same customer logs in as a guest (different customerId) he will not see any of his cards.

Cashier display

Recurring payments

In this section, you will find out how to save customer cards for later payments without customer interaction or CIT (Customer Initiated Transaction).

In these use cases, the customer must make an initial payment authenticated with 3DS2 and SCA, which will allow them to save their card details and consent for future payments. This type of transaction is called COF (Credential On File).

For the following payments without customer interaction or M.I.T (Merchant Initiated Transaction), visit the Host2Host guide.

Subscription

With this integration, you can allow customers to subscribe to your plans, saving their card for later payments. In the request, you must include the COF parameters and force SCA to prevent the issuer from declining future transactions. In the response, you will get the “subscriptionPlan”, which is the ID for future operations and is directly linked to the response “cardNumberToken” and the “customerId” you sent with the payment request. We will see all this below.

In the first transaction, you have to notify the type of transactions that will be processed in the future based on your needs. Here is a table with the parameters to include in “paymentRecurringType” and their function:

Initial payment	Successive payment	Description	Example
newCof	cof	One-off payments without fixed amount or periodicity.	Purchase when customer chooses to save the card for future transactions.
newSubscription	subscription	Recurring payment with fixed amount and periodicity.	Fees or subscriptions.
newInstallment	installment	Postponed payment limited to individual purchase with fixed amount and periodicity.	Payment in instalments.

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.

Getting the authToken and rendering frontend cashier

You can learn how to obtain the authToken and how to render the frontend cashier in the previous sections.

Note: Remember to add the parameter “forceTokenRequest=true” to save the customer card token.

Charge

This is a sample request for a subscription plan, as a string and as cURL:

				
					{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "amount": "0.00",
    "paymentRecurringType":"newSubscription",
    "challengeInd":"04",
    "currency": "EUR",
    "country": "ES",
    "apiVersion": "5",
    "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"
}

				
					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",
    "currency": "EUR",
    "country": "ES",
    "apiVersion": "5",
    "customerId": "000001",
    "paymentSolution": "creditcards",
    "productId": "123450001",
    "challengeInd": "04",
    "paymentRecurringType": "newSubscription",
    "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"}'

Charge request parameters

The required/mandatory and optional parameters for a charge subscription Request are listed in this table.

In addition to those parameters, to start a subscription plan, you have to add the following parameters. The type shows whether the element is Required (R) or Optional (O):

Field	Format	Type	Description	Example
paymentRecurringType	– newCof: One-off payments, without a fixed amount or periodicity. – newSubscription: Recurring payments with fixed amount and periodicity. – newInstallment: Postponed payment limited to individual purchase with fixed amount and periodicity.	R	Recurring or successive payment type. Note if the COF transaction is initial or successive, and the reason or purpose for payment.	newSubscription
challengeInd	Accepted values: – 01: no preference (default value if this parameter is not sent) – 02: avoid challenge – 03: require challenge (trade preference) – 04: require challenge (mandatory) – 05: avoid challenge (performed transaction risk analysis) – 06: avoid challenge (only in data sharing) – 07: avoid challenge (SCA already done) – 08: avoid challenge (use whitelist exemption) – 09: avoid challenge (request whitelist)	R	Indicates the preference set by the merchant for an authentication process. The issuer can modify the preference specified in this field.	04

Response

Visit our section on Managing notifications to learn more about its structure.

This is a sample notification received after starting a subscription plan:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7712668</message>
	<operations>
		<operation sorted-order="1">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Invalid threeDSv2Token.</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7712668</payFrexTransactionId>
			<service>3DSv2</service>
			<status>ERROR3DS</status>
		</operation>
		<operation sorted-order="2">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>3dsv2 - processed</message>
			<operationType>DEBIT</operationType>
			<payFrexTransactionId>7712668</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 846363 231031084720","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":"31/10/23 08:47:20","rfTerminalOperationNumber":"1202","rfAuthNumber":"246289","rfTransactionAmountCurrency":"10,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1202","posTransactionToken":"{\"pucIdMsg\":\"1200\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000001000\",\"pucP11TransactionNumber\":\"846363\",\"pucP12LocalDateTime\":\"231031084720\",\"pucP22ServicePointData\":\"1U00506K3000\",\"pucP38AuthNumber\":\"246289\",\"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\":\"1202\",\"transactionResponseCode\":null,\"transactionCurrency\":\"978\",\"transactionFuc\":\"355534686\",\"cardMaskedPan\":\"************2227\",\"cardAid\":null,\"cardDdfName\":null,\"cardApplicationLabel\":null,\"cardCypherData\":null}","OperationResult":"000","cofAdditionalInformation":"RS675003676677589"},"threeDsProtocolVersion":"2.2.0"}</details>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Success 'Settle' operation</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<payFrexTransactionId>7712668</payFrexTransactionId>
			<paySolTransactionId>355534686 790190 846363 231031084720</paySolTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Frictioless</cardHolderName>
				<cardNumber>490727****2227</cardNumber>
				<cardNumberToken>5774655584592227</cardNumberToken>
				<cardType>VISA/CREDIT OR DEBIT</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>
			<paymentMessage>Operación finalizada con éxito</paymentMessage>
         <subscriptionPlan>708120533554282</subscriptionPlan>
      </operation>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</payfrex-response>

For the following payments without customer interaction or M.I.T (Merchant Initiated Transaction), visit the Host2Host guide.

Payouts

Payouts are a payment transaction from the merchant to the customer’s account. Not to be confused with refunds. The purpose of this operation is the payment of prizes, for example. You must request this operation to Support for its activation.

The request is very similar to a standard authorization, but it includes “operationType: credit”. The type of Payout depends on the flow that your merchant has active, you can not choose the type of Payout (direct or in two steps) with the parameters of the request. There are two types of Payouts:

Direct Payout: The customer receives the amount when the request is successfully completed.
Payout in two steps: The customer initiates the Payout process but the Payout is pending approval or rejection by the merchant.

In addition, for security reasons, to perform a Payout there must be a previous authorized payment (from the customer to the merchant). The Payout will be made with the same payment solution and to the same card with which the previous payment was made. However, there are exceptions where a Payout can be made without prior deposit, depending on the nature of the merchant.

You must request the Payout operation to Support for its activation.

Getting the authToken and rendering the front-end cashier

You can learn how to get the authToken and how to render the front-end cashier in the previous sections.

Charge

Your e-commerce platform sends the Payout charge to the established endpoint. Here you have an example in string and cURL. Remember that the string must pass the encryption process.

				
					{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "amount": "10.00",
    "currency": "EUR",
    "country": "ES",
    "apiVersion": "5",
    "customerId": "000001",
    "paymentSolution": "creditcards",
    "productId": "123450001",
    "cardNumberToken": "4535954006730084",
    "operationType"= "credit",
    "statusURL": "https://micomercio.com/recepcion_notificacion.php",
    "successURL": "https:// micomercio.com/url-ok.php",
    "errorURL": "https:// micomercio.com/url-ko.php",
    "awaitingURL": "https:// micomercio.com/url-espera.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",
    "currency": "EUR",
    "country": "ES",
    "apiVersion": "5",
    "customerId": "000001",
    "paymentSolution": "creditcards",
    "productId": "123450001",
    "cardNumberToken": "4535954006730084",
    "operationType"= "credit",
    "statusURL": "https://micomercio.com/recepcion_notificacion.php?tipo=redireccion",
    "successURL": "https:// micomercio.com/url-ok.php",
    "errorURL": "https:// micomercio.com/url-ko.php",
    "awaitingURL": "https:// micomercio.com/url-espera.php",
    "cancelURL": "https:// micomercio.com/url-cancelacion.php"}'

JavaScript Payout Parameters

The required parameters for a JavaScript Payout are those in this table.

In addition, you must add or modify the following data:

Field	Format	Type	Description	Example
operationType	Alphanumeric Max. 45 characters	R	Shows type of operation to carry out. Eligible values: – 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 price.	credit
cardNumberToken	Alphanumeric 16~20 characters	R	Addon Payments token of the customer’s card number. The last 4 digits match the original card number.	4535954006730084
cardNumber	Numeric. Maximum 19 digits.	O (R if cardNumberToken is not sent)	PAN of the card. It must pass the Luhn Check algorithm.	4907270002222227
expDate	Numeric 4 digits MMAA format, months are MM and YY is the year.	O (R if cardNumberToken is not sent)	Card expiration date.	0623
cvnNumber	Numeric 3 to 4 digits.	O (R if cardNumberToken is not sent)	Card CVC.	123
chName	Alphanumeric Max. 100 characters	O (R if cardNumberToken is not sent)	Full name of cardholder. First and last names are separated with spaces. Supports UTF-8.	Pablo Ferrer

Response

This is an example of the notification you get from a Payout transaction:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <payfrex-response operation-size="1">
      <message>WorkFlow has finished successfully, for transaction Id: 199007517</message>
      <operations>
          <operation sorted-order="1">
              <amount>3.00</amount>
              <currency>EUR</currency>
              <details>{"resultCode":"00000","resultDescri ... ypherData\":null}","OperationResult":"000"}}</details>
              <merchantTransactionId>test-0305-014</merchantTransactionId>
              <message>A description - Success 'Payout' operation with status 'SUCCESS'</message>
              <operationType>CREDIT</operationType>
              <optionalTransactionParams/>
              <payFrexTransactionId>197517</payFrexTransactionId>
              <paySolTransactionId>008000853 790190 596484 210503172504</paySolTransactionId>
              <paymentDetails>
                  <cardNumber>466203****7594</cardNumber>
                  <cardNumberToken>3049400010087594</cardNumberToken>
                  <cardType>VISA/CREDIT</cardType>
                  <expDate>0425</expDate>
                  <extraDetails>
                      <entry>
                          <key>cardCategory</key>
                          <value>CLASSIC</value>
                      </entry>
                      <entry>
                          <key>rememberMe</key>
                          <value>true</value>
                      </entry>
                  </extraDetails>
                  <issuerBank>BANCO, S.A.U.</issuerBank>
                  <issuerCountry>ES</issuerCountry>
              </paymentDetails>
              <paymentSolution>caixapucpuce</paymentSolution>
              <status>SUCCESS</status>
              <respCode>
                  <code>0000</code>
                  <message>Successful</message>
                  <uuid>f82e5b47_bfa9_4135_a1b9_25202571208b</uuid>
              </respCode>
          </operation>
      </operations>
      <optionalTransactionParams/>
      <status>SUCCESS</status>
      <workFlowResponse>
          <id>12215</id>
          <name>Caixa Creditcards credit </name>
          <version>2</version>
      </workFlowResponse>
  </payfrex-response>

Approve and reject Payout

If your merchant flow indicates so, Payouts will remain in “PENDING” to “CREDIT” status until they are approved or rejected. Please refer to Host2Host documentation to perform this operation.

Next steps

Having reached this point, we hope you have successfully completed your JavaScript integration. Check out the other guides for a full integration:

JavaScript Integration

Introduction

Integration workflow

Environments: staging and production

Getting the authToken

Parameters of the authToken request

Rendering the cashier on your frontend

Required and optional parameters charge JavaScript

Card payments

Authorization

Getting the authToken and rendering frontend cashier

Charge

Parameters of charge request

Response

Pre-authorization

Getting the authToken and rendering frontend cashier

Charge

Charge request parameters

Response

Card validation

Getting the authToken and rendering frontend cashier

Charge

Charge request parameters

Response

Saving cards

Storing cards

Use cases and parameters

Getting the authToken

Rendering cashier

Charge

Response

Show cards

Get authtToken, render cashier and charge

Cashier display

Recurring payments

Subscription

Getting the authToken and rendering frontend cashier

Charge

Charge request parameters

Response

Payouts

Getting the authToken and rendering the front-end cashier

Charge

JavaScript Payout Parameters

Response

Approve and reject Payout

Next steps

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: