Apple Pay

Introduction

Apple Pay is a mobile payment system available on Apple devices, such as: iPhone, iPad, Mac or Apple Watch. It allows users to store their cards and pay without having to re-enter their data.

Apple displays the option to Pay with Apple Pay on websites where the system has been integrated and whenever accessed with a compatible device, such as iPhone.

In this guide we will see how to integrate Apple Pay in your business. This way, customers who meet these requirements will be able to use it:

Have a device compatible with Apple Pay: iPhone, iPad, Mac or Apple Watch.
Access with a compatible browser (Safari).
Have Apple Pay activated on your device with at least one saved card.

Payment type	Wallet
Countries available	All
Currencies available	All
Need redirect?	No
Two-step payment allowed?	No
Refunds allowed?	Yes, total and partial through the BackOffice or by H2H request.
SCA Exencions	No
DCC	No

On the merchant side, you must meet these requirements to use Apple Pay on your platform:

Contact the Addon Payments support team to request the activation and configuration of Apple Pay in your Virtual POS.
To perform Staging tests or work in a Production environment, you must:
- Have a compatible Apple device, as the Apple Pay button is only shown to these devices.
- Have Apple Pay activated on your device with at least one saved card.

As a requirement for the merchant in JavaScript integration:

Apple validation of your e-commerce platform domain. More information in the Pre-configuration by the merchant section.

You can check if your device is compatible with Apple Pay with this Apple tool. If your device and browser are compatible, the Apple Pay button will be displayed at the bottom.

Finally, you have a Postman collection where you can test the different Apple Pay operations:

Postman.

Operations supported

The Apple Pay integration allows your merchant the following operations:

Authorization: A regular payment from the customer to your merchant. The capture of the amount is automatic.
Refunds: Total and partial. Through the BackOffice portal or via endpoint.

Data for Apple Pay testing

In addition to the requirements we have already mentioned (having Apple device with active Apple Pay) you must take this into consideration for testing:

The card you use in Apple Pay must be a real card. Transactions in the Staging environment will not be charged to that card.
If the transaction is processed by Redsys (by default is so), the order number must comply with the format of:
- Alphanumeric (a-z A-Z 0-9 without special characters).
- Max. 12 characters Min. 4 characters.
- Duplicate orders are not allowed.

In the Staging environment, the result of the transaction depends on the amount sent. That is:

Amount	Transaction outcome
1 €	Error (wrong amount)
10 €	Error (issuer denial)
30 €	Error (duplicate order number)
50 €	Authorized

Environments and endpoints: Staging and Production

Addon Payments has two (2) independent operating environments:

Staging environment:

It is the first environment with which you will come into contact.
You can test with the credentials from the previous section.
This allows you to check the correct management of the different cases by your integration.

Production Environment:

It is the environment in which transactions have accounting effects.
Transactions can only be made with real and operative cards and accounts.

Below are the endpoints according to the type of integration:

Environment	URL
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize
Production	https://checkout.addonpayments.com/EPGCheckout/rest/online/tokenize

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

Hosted Integration

With Addon Payments you can use the Apple Pay payment solution in Hosted integrations. In the payment cashier, you can choose whether the customer sees all the payment solutions you have activated (Apple Pay, Bizum, credit card…), or if it is limited only to Apple Pay.

To limit the cashier to Apple Pay only, you must indicate this with the field “paymentSolution: applepaydecryptservice”.

Required and optional data via Hosted

These are the required/mandatory (R) and optional (O) parameters to perform a transaction with Apple Pay via Hosted:

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
merchantTransactionId	Alphanumeric Max 12 characters Min 4 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.	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
paymentSolution	Alphanumeric Max 45 characters	O	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.	applepaydecryptservice

Authorization

Here is how to make a payment with Apple Pay. The capture of the amount after authorization is automatic. Send the request to the corresponding endpoint.

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our section on Encryption, signature and sending the request for more information.

Here are some examples of payment request using Apple Pay by Hosted. Remember that the chain request must pass the encryption process.

				
					merchantId=12345&merchantTransactionId=00000001&amount=50.00&currency=EUR&country=ES&customerId=000001&statusURL
=https://micomercio.com/recepcion_notificacion.php-tipo-redireccion&successURL=https://micomercio
.com/url-ok.php&errorURL=https://micomercio.com/url-ko.php

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: mx3rdwlpuDA1vM14SFT5bw==' \
--form 'merchantId="12345"' \
--form 'encrypted="/kJtS1WhS33iGLIvOuv7QrAj7RCJXYgaiLpTFzNe9VDkGEYMCF5CI6z2eZmPQBFMsVJtroV3mvgBhRdK6j64utR' \
--form 'integrityCheck="e55c1dae947b376645b8fbd7f3612f0cf63045236c80b643f8335d3c4050ec70"'

Once the POST is sent to Addon Payments, you will receive the URL to redirect the customer to:

				
					https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize?token
=2166f73d-6412-48d3-b440-6da9a961594b&apiVersion=5

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

Request parameters

The basic parameters for sending an Apple Pay authorization request via Hosted are the Required/Mandatory (R) from the Required and Optional table.

Response

Visit our section on Reception and management of notifications to learn more about its structure.

Below is an example of the notification you receive in the “statusURL” you have indicated informing you of the status of the transaction.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
	<message>WorkFlow has finished successfully, for transaction Id: 7798313</message>
	<operations>
		<operation sorted-order="1">
			<amount>50</amount>
			<currency>EUR</currency>
			<merchantTransactionId>27516260</merchantTransactionId>
			<message>Applepay decryption finished successfully</message>
			<operationType>DEBIT</operationType>
			<originalTransactionId>7798313</originalTransactionId>
			<paySolTransactionId>7798313</paySolTransactionId>
			<paymentDetails>
				<extraDetails>
					<entry>
						<key>stAp</key>
						<value>AWAITING_PAYSOL</value>
					</entry>
				</extraDetails>
			</paymentDetails>
			<service>ApplepayDecryptService</service>
			<status>SUCCESS</status>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>11b65f6d_5ee0_4192_bdb9_93ae168cd6b3</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>50</amount>
			<currency>EUR</currency>
 <details>{"Ds_Card_Brand":"1","Ds_Response":"0000","Ds_ProcessedPayMethod":"72","Ds_TransactionType":"0","Ds_Language":"1","Ds_Currency":"978","Ds_Card_Country":"724","Ds_MerchantCode":"008043853","Ds_SecurePayment":"0","Ds_Amount":"5000","Ds_Card_Type":"C","Ds_MerchantData":"","Ds_AuthorisationCode":"782076","Ds_Terminal":"50","Ds_Order":"2704003"}</details>
			<merchantTransactionId>27516260</merchantTransactionId>
			<message>Operation SUCCESS, with Authorization code :782076</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>2704003</paySolTransactionId>
			<paymentDetails>
				<extraDetails>
					<entry>
						<key>stAp</key>
						<value>SUCCESS</value>
					</entry>
				</extraDetails>
			</paymentDetails>
			<paymentSolution>redsysrest-applepay</paymentSolution>
			<status>SUCCESS</status>
			<transactionId>7798313</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>fc022bbe_e456_440b_8498_cf3ac389880b</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>51594</id>
		<name>Applepay</name>
		<version>3</version>
	</workFlowResponse>
</response>

JavaScript Integration

With Addon Payments you can use the Apple Pay payment solution in JavaScript integrations.

The Apple Pay option can be displayed along with the other payment options you have in your store. On the other hand, you can choose to show only Apple Pay. This depends on the function you use to render the cashier in your platform, as we will see in the Rendering section.

This is an overview of Apple Pay integration using JavaScript. You can get more general information in the Complement your JavaScript integration guide:

You request a unique, one-time authToken to be able to link the cashier on your website.
Your e-commerce platform links the AP cashier in a “div” element of your website using the chosen upload function (full cashier or limited cashier).
AP compiles the selected cashier in the “div” of your website given as a parameter to the load function.
The customer selects the Apple Pay payment method and presses the “Pay” button.
AP returns a “prepayToken” to your website, which you will have to capture through a JavaScript listener.
Your e-commerce platform collects the prepayToken and sends a charge request to AP containing it.
AP sends a notification with the result of the transaction to the URL of your platform indicated in the “statusURL” parameter sent in the charge request.
Your e-commerce platform communicates the result of the transaction to Apple Pay for them to update and reflect the status on the customer’s device.

Pre-configuration by the merchant

In order for the Pay with Apple Pay button to display in the cashier JavaScript, Apple requires that the domains of your e-commerce platform from which the cashier is invoked be registered as authorized.

Addon Payments has an automated process using Apple’s API that allows merchant domains to be registered as authorized. However, Apple performs a validation of each domain added and, if not validated, rejects the inclusion of the domain as secure.

To get Apple validation, you must make the following configurations on the domains where you want to integrate the Apple Pay payment solution:

1. Get the apple-developer-merchantid-domain-association file. Request it from support.

Request the file “apple-developer-merchantid-domain-association” from the support team.

2. Unzip the downloaded file.
Note: This validation file is valid for both Staging and Production environments, so we recommend keeping it handy until you move to the production environment.

3. Host the attachment “apple-developer-merchantid-domain-association” in the following path for each of the domains to be validated: https://dominio.com/.well-known/apple-developer-merchantid-domain-association
– The file must be uncompressed and publicly accessible on the Internet.

– The domains to be validated must have a valid TLS encryption certificate installed.

4. If you have a firewall enabled on your web server, you must open access to the following Apple validation IPs:

17.32.139.128/27
17.32.139.160/27
17.140.126.0/27
17.140.126.32/27
17.179.144.128/27
17.179.144.160/27
17.179.144.192/27
17.179.144.224/27
17.253.0.0/16

5. Both of these points are detailed in the Apple documentation available at this website.

6. To check if you have successfully hosted the file you can enter the path with the domain of your e-commerce platform, if possible from a device that is not on the same network as the web server.

7. Once you have verified the correct access to the validation file, contact Support and indicate the domain(s) that can validate and activate in Apple Pay.

8. After confirmation from Support that the domains have been successfully validated, you will be able to perform integration testing with Apple Pay with the JavaScript integration.

Obtaining the authToken and rendering the cashier

The first step is to obtain the “authToken” that will allow us to render the cashier. A request must be sent with the required minimum data as shown below. Send the request to the corresponding endpoint.

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

				
					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",
    "currency":"EUR",
    "productId":"123450001",
    "country":"ES",
    "customerId":"000001"
}'

If the request is valid, Addon Payments will return an “authToken” with which you can render the cashier on the front end of your page. If the request is not valid, a message like the one you see in the second tab will be returned:

				
					{
    "authToken": "23ed4dda-79f5-4a60-bcc0-52fe2f27b26e"
}

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

The authorization references received have the following characteristics:

Validity of 30 minutes.
Can be used several times to link the payment gateway.

Parameters of the authToken request

The type indicates whether the parameter is required/mandatory (R) or optional (O):

Campo	Formato	Tipo	Descripción	Ejemplo
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.	A34623

Rendering of the cashier on the front-end

Once you have obtained the authToken you will be able to render the cashier on the front end. Remember that it is not possible to render the cashier on a localhost and you must authorize the domain from the Addon Payments control panel. More rendering options can be found in our extended JavaScript guide.

Here is a simple example showing how to render the Apple Pay 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 = "39c1cd83-fca9-4073-b056-7fbfe95c9e69"; // 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', 'applepayDecryptService');
            EPGJS.setInitPaysolParam({'amount':50, 'currency':'EUR', 'country':'ES', 'language':'ES'});
            EPGJS_COMM.setMerchantPrePayCallback(prePayCallback);
            // EPGJS.getContainerDiv().dispatchEvent(new CustomEvent('retrievePaymentResponse', {'detail': estado_pago}));
        }
        window.onload = displayingMessageOnButtonClick;
    </script>
</body>
</html>

In this example code there are several mandatory functions for the correct functioning of the JavaScript cashier with Apple Pay. These are:

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

2. EPGJS.renderIntegratedCashier: This is the rendering function of the cashier. It sets how the ATM will look like. In this example, the cashier renders only Apple Pay. If you want to load all the payment solutions you have available, delete ‘applepayDecryptService’ from “EPGJS.renderIntegratedCashier”. It would look like this:

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

3. EPGJS.SetInitPaysolParam: Initializes the Apple Pay payment solution with parameters set. They must match those set in the authToken and Charge request. These are:

Field	Format	Description	Example
amount	Numerical with decimals 0~1000000.00	Amount of the transaction. If the amount has decimals, the separator is a dot (.). The separator cannot be included in the thousands.	50
currency	Alphabetical 3 characters ISO-4217.3	Currency of the transaction	EUR
country	Alphabetical 2 characters ISO 3166-1 alfa-2	Country from which the transaction is sent.	ES
language	Alphabetical ISO 639-1	Language in which the Apple Pay payment button will be displayed.	ES

Note: If you want the button language to load according to the browser language, follow these steps:

Contact Support, who will make the appropriate changes in the BackOffice.
Do not send the “language” field in the “EPGJS.SetInitPaysolParam” function.
The “lang” tag must not exist in the HTML document where the Apple Pay button will be loaded.

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

5. EPGJS.getContainerDiv(): Function that sends the result of the transaction to the Apple Pay App on the customer’s device. You must create it previously. More details in the Response.

This will allow you to render the cashier in the front-end div so that the customer can proceed with the payment. 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.

Obtaining the prepayToken

When the customer selects to pay with Apple Pay, Addon Payments will return a “prepayToken”, which you must use when sending the charge request, as you will see in the following operations. Here is an example:

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

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

Validity of 30 minutes.
It can be used only once to authorize the payment.

Required and optional data charge JS

These are the required/mandatory (R) and optional (O) parameters for charging with Apple Pay via JavaScript:

Field	Fomat	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
merchantTransactionId	Alphanumeric Max 12 characters Min 4 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
language	Alphabetical ISO 639-1	R	Language in which the payment was made	ES
paymentSolution	Alphanumeric Máx. 45 characteres	R	Name of the payment solution to process the transaction	redsysrest-applepay
customerId	Alphanumeric Máx. 80 caracteres	R	Customer ID in your e-commerce platform	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

Charge

After obtaining the prepayToken, you will be able to send the payment/charge request. Below is an example of a request and response with the basic fields for a charge in Apple Pay. Send the request to the corresponing endpoint.

Below is an example of authorization, the first as a string and the second as a cURL.

				
					{
    "merchantId":"12345",
    "merchantTransactionId":"pedido_011",
    "amount":"50",
    "paymentSolution":"redsysrest-applepay",
    "currency":"EUR",
    "country":"ES",
    "language":"ES",
    "customerId":"A3434",
    "statusURL":"https://www.example.com/status",
    "successURL":"https://www.example.com/success",
    "errorURL":"https://www.example.com/error",
    "cancelURL":"https://www.example.com/cancel"
}

				
					curl --location --request POST 'http://epgjs-mep-stg.easypaymentgateway.com/charge/v2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'prepayToken: e686282e-fad0-45d7-84b6-eff5bf0c126d' \
--data-raw '{
    "merchantId":"12345",
    "merchantTransactionId":"pedido_011",
    "amount":"50",
    "paymentSolution":"redsysrest-applepay",
    "currency":"EUR",
    "country":"ES",
    "language":"ES",
    "customerId":"A3434",
    "statusURL":"https://www.example.com/status",
    "successURL":"https://www.example.com/success",
    "errorURL":"https://www.example.com/error",
    "cancelURL":"https://www.example.com/cancel"
    }'

Response

When the Charge request is sent you will receive a notification with the status of the transaction.

In Apple Pay, you must send the result of the transaction to the application on the customer’s device, so that it updates the status and informs the customer of the result. You can see the rest of the functions in the Rendering section.

This is done with the following function:

EPGJS.getContainerDiv().dispatchEvent(new CustomEvent('retrievePaymentResponse', {'detail': estado_pago}));

The result of the request (SUCCESS, ERROR, etc.) must be sent in the “detail” value.

Important: For Apple Pay to mark the payment as completed, this function must be executed with the following conditions:

Before 30 seconds after customer authentication on your device.
It must have the status value “SUCCESS”.

If it does not meet these requirements, the payment will be “Not completed”.

Refunds with Apple Pay

You can make full and partial refunds on Apple Pay transactions as long as:

The transaction is authorized and captured (“success” status).

You have two ways to make returns:

Through the BackOffice portal, as you can see in the Secondary Transactions section.
By sending a return request, as you will see below.

Remember that for the return via endpoint you must use the “transactionId” of the original transaction, returned in the previous answer, and the “paymentSolution” must be “redsysrest-applepay”.

Refund by request

You must send a request to this endpoint:

Entorno	URL
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/rebate
Production	https://checkout.addonpayments.com/EPGCheckout/rest/online/rebate

These are the required/mandatory (R) and optional (O) parameters for making a refund in Apple Pay:

Campo	Formato	Tipo	Descripción	Ejemplo
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
transactionId	Whole number Max 100 digits	R	ID for the original transaction the secondary operation applies to, such as capture, release or refund	76543210
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.	30.5
paymentSolution	Alphanumeric Max. 45 characters	R	Name of the payment solution to process the original transaction. It is indicated in the response of the original transaction.	redsysrest-applepay
merchantTransactionId	Alphanumeric Max 12 characters Min 4 characters	R	Transaction identifier on your e-commerce platform. It is used for your platform to link the notifications received with the customer’s order. It cannot be repeated between transactions.	order_91684
description	Max. 1000 characters Code page Latin-1 (ISO-8859-1)	O	Description of the transaction. It is saved in the transaction details and returned in the notification. It does not affect the transaction, it is used so that you can make a better identification.	Refund after customer return

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our section on Encryption, signature and sending the request for more information.

Here are some examples of refund request for an Apple Pay transaction by H2H. For a partial refund, send an amount less than the total amount.

Remember that the string request must undergo the encryption process.

				
					merchantId=12345&merchantTransactionId=00000001&amount=50.00
&paymentSolution=redsysrest-applepay&transactionId=7860068

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/rebate' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: mx3rdwlpuDA1vM14SFT5bw==' \
--form 'merchantId="12345"' \
--form 'encrypted="/kJtS1WhS33iGLIvOuv7QrAj7RCJXYgaiLpTFzNe9VDkGEYMCF5CI6z2eZmPQBFMsVJtroV3mvgBhRdK6j64utR' \
--form 'integrityCheck="e55c1dae947b376645b8fbd7f3612f0cf63045236c80b643f8335d3c4050ec70"'

Response

Visit our section on Receiving and managing notifications to learn more about its structure.

Here are some examples of the notifications you receive for a full and partial refund request from Apple Pay. In the partial refund, the amount remaining to be refunded is indicated.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<operations>
		<operation sorted-order="1">
			<amount>50.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_Card_Brand":"1","Ds_Response":"0000","Ds_ProcessedPayMethod":"72","Ds_TransactionType":"0","Ds_Language":"1","Ds_Currency":"978","Ds_Card_Country":"724","Ds_MerchantCode":"008043853","Ds_SecurePayment":"0","Ds_Amount":"500","Ds_Card_Type":"C","Ds_MerchantData":"","Ds_AuthorisationCode":"782076","Ds_Terminal":"50","Ds_Order":"2704003"}</details>
			<merchantTransactionId>7554588</merchantTransactionId>
			<message>Operation SUCCESS, with Authorization code : 782076</message>
			<operationType>REFUND</operationType>
			<optionalTransactionParams/>
			<originalAmount>50.0</originalAmount>
			<originalCurrency>EUR</originalCurrency>
			<originalTransactionId>7860068</originalTransactionId>
			<paySolTransactionId>2704003</paySolTransactionId>
			<paymentSolution>redsysrest-applepay</paymentSolution>
			<remainingAmount>0.00</remainingAmount>
			<status>SUCCESS</status>
			<transactionId>7860074</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>84eaac6f_bab5_4e3f_acbc_119ce089cc69</uuid>
			</respCode>
		</operation>
	</operations>
	<status>SUCCESS</status>
</response>

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<operations>
		<operation sorted-order="1">
			<amount>20.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_Card_Brand":"1","Ds_Response":"0000","Ds_ProcessedPayMethod":"72","Ds_TransactionType":"0","Ds_Language":"1","Ds_Currency":"978","Ds_Card_Country":"724","Ds_MerchantCode":"008043853","Ds_SecurePayment":"0","Ds_Amount":"500","Ds_Card_Type":"C","Ds_MerchantData":"","Ds_AuthorisationCode":"782076","Ds_Terminal":"50","Ds_Order":"2704003"}</details>
			<merchantTransactionId>64015341</merchantTransactionId>
			<message>Operation SUCCESS, with Authorization code : 782076</message>
			<operationType>REBATE</operationType>
			<optionalTransactionParams/>
			<originalAmount>50.0</originalAmount>
			<originalCurrency>EUR</originalCurrency>
			<originalTransactionId>7860071</originalTransactionId>
			<paySolTransactionId>2704003</paySolTransactionId>
			<paymentSolution>redsysrest-applepay</paymentSolution>
			<remainingAmount>30.00</remainingAmount>
			<status>SUCCESS</status>
			<transactionId>7860080</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>1fc491a6_db6c_47dc_ba53_6e305ffc5b8f</uuid>
			</respCode>
		</operation>
	</operations>
	<status>SUCCESS</status>
</response>

Error codes

These are the error codes that you may receive in Apple Pay notifications. You can find them in the lines “code”, “paymentCode”, “paymentMessage”.

< code > Addon Payments Code	Addon Payments Message	< paymentCode > Payment solution code	< paymentMessage > Payment solution message
1509	The transaction could not be processed. Check the Payment Solution Response	904	Merchant not registered in the fuc
1509	The transaction could not be processed. Check the Payment Solution Response	909	System error
1509	The transaction could not be processed. Check the Payment Solution Response	913	Duplicated transmission
1509	The transaction could not be processed. Check the Payment Solution Response	944	Wrong session
1511	The refund was unable to be processed. Check Payment Solution Response	950	Return operation not allowed
1513	Unable to process this operation please check the Payment Solution Response	9257	This card does not allow preauthorization operations
1513	Unable to process this operation please check the Payment Solution Response	9261	Operation stopped for exceeding control restrictions at SIS entrance
1524	The provided transaction reference has already been used for another transaction. You must provide a unique value for each request	9997	Another transaction is being processed in SIS with the same card
1532	Merchant is not entitled to initiate this type of transaction	9256	The merchant cannot perform pre-authorizations
1600	Payment solution general input error, please check payment solution respond	9899	The data in Ds_Merchant_Data were not correctly signed.
1600	Payment solution general input error, please check payment solution respond	9909	Generic error. Contact Support
1616	Incorrect CVV	129	Wrong CVV2
1618	Card Decline, please check Payment Solution Respond	101	Expired card
1618	Card Decline, please check Payment Solution Respond	125	Non effective card
1618	Card Decline, please check Payment Solution Respond	180	Non-compliant or non-compatible card.
1620	Card Number not Valid, Please Check Payment Solution Respond	9064	Wrong number of card positions
1620	Card Number not Valid, Please Check Payment Solution Respond	9253	Card does not comply with check-digit
1625	Check the card limits	9995	Prepaid recharge denied
1625	Check the card limits	9996	Does not allow prepaid card reloading
1628	Potencial fraud, transaction declined.	9931	Denied (LINX)
1628	Potencial fraud, transaction declined.	9932	Denied (LINX)
1628	Potencial fraud, transaction declined.	9933	Denied (LINX)
1628	Potencial fraud, transaction declined.	9934	Denied (LINX)
1628	Potencial fraud, transaction declined.	9935	Denied (LINX)
1634	Transaction pending to be processed by the Payment Solution	8102	Transaction redirected to the issuer to be authenticated EMV3DS V1 (for H2H)
1634	Transaction pending to be processed by the Payment Solution	8210	Transaction redirected to the issuer to be authenticated EMV3DS V2 (for H2H)
1634	Transaction pending to be processed by the Payment Solution	9930	The transfer is pending
1634	Transaction pending to be processed by the Payment Solution	9998	Operation in the process of requesting card data
1634	Transaction pending to be processed by the Payment Solution	9999	Transaction that has been redirected to the issuer to be authenticated
1638	Issuer declined the transaction, please check payment solution respond	172	Denied, do not repeat
1638	Issuer declined the transaction, please check payment solution respond	173	Denied, do not repeat without updating card details
1638	Issuer declined the transaction, please check payment solution respond	174	Denied, do not repeat within 72 hours
1638	Issuer declined the transaction, please check payment solution respond	190	Issuer’s refusal without specifying reason
1641	Card or currency not supported, please check payment solution respond	9078	Type of operation not allowed for that card
1647	Issuer unavail	912	Issuer not available
1647	Issuer unavail	9912	Issuer not available
1654	Restricted card	102	Card under suspicion of fraud or temporarily blocked
1654	Restricted card	202	Card under suspicion of fraud
1664	Invalid expire date	191	Wrong expiration date
1673	Card restricted	9094	Rejection of international servers
1682	PIN error. Check the Payment Solution Response	106	Number of attempts with wrong PIN exceeded
1684	Full 3DS operative enabled and 3ds server response was not secured transaction	9104	Trade with “secure holder” and holder without secure purchase key
8005	Cancelled by cardholder	915	The holder has cancelled the payment transaction.
8005	Cancelled by cardholder	9915	At the user’s request, the payment has been cancelled.
8005	Cancelled by cardholder	9928	Preauthorization is cancelled at the user’s request.
8005	Cancelled by cardholder	9929	The holder has cancelled the operation
8011	Invalid/not supported or not permitted transaction. Check Service Response	9218	The merchant does not allow secure transactions per entry/transactions.
8016	No Card record	9093	Non existing card
8016	No Card record	9994	No card has been selected from the wallet.
8032	Authentication error	184	Error in 3DSecure authentication by card holder
8888	Soft Decline	195	SCA authentication required

Apple Pay

Introduction

Operations supported

Data for Apple Pay testing

Environments and endpoints: Staging and Production

Hosted Integration

Required and optional data via Hosted

Authorization

Request

Request parameters

Response

JavaScript Integration

Pre-configuration by the merchant

Obtaining the authToken and rendering the cashier

Parameters of the authToken request

Rendering of the cashier on the front-end

Obtaining the prepayToken

Required and optional data charge JS

Charge

Response

Refunds with Apple Pay

Refund by request

Request

Response

Error codes

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Apple Pay

Introduction

Operations supported

Data for Apple Pay testing

Environments and endpoints: Staging and Production

Hosted Integration

Required and optional data via Hosted

Authorization

Request

Request parameters

Response

JavaScript Integration

Pre-configuration by the merchant

Obtaining the authToken and rendering the cashier

Parameters of the authToken request

Rendering of the cashier on the front-end

Obtaining the prepayToken

Required and optional data charge JS

Charge

Response

Refunds with Apple Pay

Refund by request

Request

Response

Error codes

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: