Integración Hosted

Introducción

En esta sección se exponen los pasos a seguir para completar la integración Hosted. Esta integración consiste en la redirección del cliente hacia un formulario de pago (cajero) alojado por Addon Payments. El cliente llega al formulario desde tu página web, a través de una redirección desde su navegador o mediante un iframe. Como tu negocio no tiene acceso a los datos del cliente se reducen los requerimientos PCI-DSS.

Los parámetros, operativas y procedimientos pueden variar entre las soluciones de pago o servicios. En esta guía se indican los más comunes a la mayoría de soluciones de pago. Si necesitas otros casos de uso no dudes en ponerte en contacto con nuestro equipo de soporte.

Los siguientes enlaces te ayudarán durante tu integración:

  • Glosario, para familiarizarte con los conceptos que usaremos a lo largo de la documentación.
  • Postman, para que pruebas las operativas de esta integración.
  • SDKs, herramienta completa para integrar Addon Payments de forma rápida, flexible y sencilla.

Esperamos que esta guía te sirva de utilidad. 

Flujo de la transacción

A continuación, tienes un diagrama con todo el proceso que sigue la integración Hosted.

A modo de resumen, la integración Hosted sigue este flujo:

  1. El cliente quiere hacer un pago.
  2. El comercio realiza una petición de formulario de solicitud de pago. Los parámetros se cifran usando el cifrado de Addon Payments.
  3. Addon Payments procesa la solicitud y crea una URL de pago de Hosted.
  4. Addon Payments devuelve la URL de pago.
  5. El comercio redirige al cliente a la página de pago de Hosted.
  6. La página de pago de Addon Payments se renderiza.
  7. El cliente interactúa con la página de pago de Addon Payments. Se selecciona una de pago y se procesa la transacción de pago.
  8. Addon Payments procesa la transacción con la solución de pago seleccionada.
  9. Addon Payments realiza el pago con la solución de pago.
  10. Respuesta de la solución de pago.
  11. Addon Payments realiza una notificación al campo statusURL, que hayas indicado en la petición del formulario de solicitud de pago.
  12. Addon Payments redirige al cliente a la página final.

Entornos y endpoints: Staging y Producción

Addon Payments cuenta con dos (2) entornos operativos independientes:

Entorno de Staging:

  • Es el primer entorno con el cual entrarás en contacto.
  • Tienes a tu disposición un listado de tarjetas para pruebas que permiten realizar transacciones simulando diferentes operativas, tipos de autenticación (frictionless, challenge) y resultados (autorizada, denegada).
  • Esto te permite comprobar la correcta gestión de las diferentes casuísticas por parte de tu integración.
  • Las tarjetas y cuentas reales no funcionan.

Entorno de Producción:

  • Es el entorno en el cual las transacciones tienen efectos contables.
  • Únicamente se puede transaccionar con tarjetas y cuentas reales y operativas.

Esta es una tabla con los endpoints donde enviar la petición según el entorno donde operes: 

EntornoURL
Staginghttps://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize
Producciónhttps://checkout.addonpayments.com/EPGCheckout/rest/online/tokenize

Datos requeridos y opcionales Hosted

Estos son los parámetros comunes para las distintas operativas de Hosted en pagos con tarjeta: autorización, pre-autorización, validación de tarjeta, almacenar tarjetas, dar de alta un plan de suscripción y payouts.

Además, recomendamos que visites nuestra sección 3DSecure con el objetivo de añadir campos adicionales al proceso de pago. Estos datos opcionales enriquecen la solicitud de pago y pueden facilitar el proceso de autenticación.

La columna tipo indica si es requerido/obligatorio (R) u opcional (O):

CampoFormatoTipoDescripciónEjemplo
merchantIdNumérico entero
4~7 dígitos		REs el indicador de tu comercio en la plataforma de AP. Es facilitado por Soporte en el correo de bienvenida, es común para los dos entornos14983
productIdNumérico entero
6~11 dígitos		RIdentificador del producto creado en tu comercio en AP. Es facilitado en el correo de bienvenida.149830
paymentSolutionAlfanumérico
Máx. 45 caracteres		RNombre de la solución de pago por la cual debe procesarse la transacción. IMPORTANTE: Si quieres que se muestren todas las soluciones de pago que tengas disponibles, NO envíes este parámetro. creditcards
operationTypeAlfanumérico
Máx. 45 caracteres		REspecifica el tipo de operación a realizar. Valores admitidos:
– debit (por defecto): Transacción de pago. Es decir, el efectivo viaja desde la cuenta del cliente al comercio.
– credit: Transacción de ingreso en cuenta del cliente. Es decir, el efectivo viaja desde el comercio hasta la cuenta del cliente. Por ejemplo, en el pago de un premio. No confundir con las devoluciones. Estas tienen su propio tipo de transacción.		debit
merchantTransactionIdAlfanumérico
Máx. 45 caracteres		REs el identificador único de la transacción del comercio. Sirve para que tu plataforma enlace las notificaciones recibidas con el pedido del cliente.pedido_91684
amountNumérico decimal
0~1000000.00		RImporte de la transacción. Si el importe tiene decimales, el separador es un punto (.). No se puede incluir el separador en los millares127.5
currencyAlfabético
3 caracteres
ISO-4217.3		RDivisa de la transacciónEUR
countryAlfabético
2 caracteres
ISO 3166-1 alfa-2		RPaís desde el que se envía la transacciónES
customerIdAlfanumérico
Máx. 80 caracteres		RId. del cliente en tu plataforma de comercio electrónico.
– Para guardar la tarjeta del cliente, usa el parámetro «forceTokenRequest«, con valor «true» para guardar el token y «false» para no hacerlo.
– Para que el cliente vea o no la opción de recordar su tarjeta, usa el parámetro «showRememberMe«, con valor «true» para mostrarle y «false» para ocultarlo.		A34623
statusURLAlfanumérico (caracteres permitidos en URL)
Máx. 2048 caracteres		RURL de tu plataforma de comercio electrónico donde AP enviará la notificación con el estado de la transacción. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.https://www.example.com/status
successURLAlfanumérico (caracteres permitidos en URL)
Máx. 2048 caracteres		RURL de tu plataforma a la que se redirecciona al cliente si la transacción es autorizada. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.https://www.example.com/success
errorURLAlfanumérico (caracteres permitidos en URL)
Máx. 2048 caracteres		RURL de tu plataforma a la que se redirecciona al cliente si la transacción es denegada. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.https://www.example.com/error
cancelURLAlfanumérico (caracteres permitidos en URL)
Máx. 2048 caracteres		RURL de tu plataforma a la que se redirecciona el cliente si cancela la transacción durante el proceso de pago. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.https://www.example.com/cancel
awaitingURLAlfanumérico (caracteres permitidos en URL)
Máx. 2048 caracteres		RURL de tu plataforma a la que se redirecciona el cliente si la transacción está pendiente de procesar. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.https://www.example.com/awaiting
customerEmailAlfanumérico
Máximo 100 caracteres		R*Dirección de correo electrónico del titular de la tarjeta.

Comercios europeos: requerido para SCA.
*Se debe enviar el customerEmail o telephone, sólo se requiere 1 de estos campos. 		correo@ejemplo.com
telephoneAlfanumérico
Máximo 45 caracteres		R*Prefijo internacional + Número de teléfono del titular de la tarjeta. Puede ser el teléfono móvil, del trabajo o de casa.

Comercios europeos: requerido para SCA.
*Se debe enviar el customerEmail o telephone, sólo se requiere 1 de estos campos. 		34600600600
languageCódigo ISO 639-1Oidioma para mostrar en la pasarela de pago al cliente. Actualmente, sólo está disponible en castellano (ES) y en inglés (EN).ES
referenceIdAlfanumérico
12 caracteres		OReferencia variable para comercios que necesiten de archivos de conciliación FB500.SM1258X795WW
merchantParamsClave1:Valor1;Clave2:Valor2;ClaveN:ValorN
Máx. 500 caracteres		OParámetros que se envían para modificar la configuración del comercio o el procesamiento de una trasacción.
Se reciben de vuelta dentro de la etiqueta
No admite caracteres especiales		nombre:pablo;apellido:ferrer;idcliente:12345
forceTokenRequestBooleano
– true
– false		OIndica si guardar o no el token de la tarjeta del cliente. Si no quieres guardar la tarjeta, usa «false»false
printReceiptBooleanoOMuestra al cliente final un recibo en el proceso de redirección tipo opcional.True
autoCaptureBooleanoOEstablece si la transacción será una autorización o pre autorización. En el último caso, requiere una captura o liberación posterior por parte del comercio.True
typeAlfanumérico:
MOTO
ECOM		OEstablece si la petición de pago es tipo comercio electrónico o MO/TO. Si no se incluye, es tipo comercio electrónico por defecto.ECOM
descriptionAlfanumérico
Máx. 1000 caracteres		ODescripción de la transacción que está teniendo lugar.Descripción del producto
cityAlfanumérico
Máximo 100 caracteres		OCiudad del titular de la tarjeta.

Comercios europeos: Opcional para SCA		Barcelona
chCountry2 caracteres
ISO 3166-1 alfa-2		OCódigo ISO 3166-1 alfa-2 del país del titular de la tarjeta.

Comercios europeos: Opcional para SCA		ES
addressLine1Alfanumérico
Máximo 250 caracteres		OPrimera línea de la dirección del titular de la tarjeta

Comercios europeos: Opcional para SCA		Calle Romero 123
addressLine2Alfanumérico
Máximo 50 caracteres		OCódigo postal del titular de la tarjeta

Comercios europeos: Opcional para SCA		08001
stateAlfanumérico
Máximo 45 caracteres		OProvincia o estado del titular de la tarjeta

Comercios europeos: Opcional para SCA		Barcelona

Pago con tarjeta

Tu plataforma tiene que enviar varios parámetros y sus respectivos valores para poder generar una petición válida que enviar a AP. En cada solicitud y caso de uso tendrás una solicitud de ejemplo, una tabla con los parámetros obligatorios y opcionales y un ejemplo de respuesta. 

Dispones de un listado con los códigos de respuesta/error en esta página. 

Autorización 

A continuación facilitamos un ejemplo con los campos básicos para redireccionar al cliente a nuestra pasarela de pago Hosted.

Además, recomendamos que visites nuestra sección 3DSecure con el objetivo de añadir campos adicionales al proceso de pago. Estos datos opcionales enriquecen la solicitud de pago y pueden facilitar el proceso de autenticación.

Petición

Este es un ejemplo de petición de una autorización de pago con tarjeta, el primero como cadena y el segundo como cURL. Recuerda que la cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&customerId=000001&forceTokenRequest=false&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://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 0Pn6pDEm73YvekNKUJcvwg==' \
--form 'merchantId="12345"' \
--form 'encrypted="jULXEtDfSVYIgfV29GBTcibe+ED+IvnfI2ssayrpqoJRzmI+SVst1SV3LRjt7DHlU5+0FoBPZy8KfoajNYn6DwRU0ltMtgd2TsR2ccm+Aeg5NAPbMlVZZnDmWA2WUmh3sXFWDMFGcHnwigMv0dWW+0QOieFJN+NLPMo/HMhLOLNNfS9240qdT++PTx7IdtSM3hfbD31ZDgKSkxwCDQYSrcIS0LyPtRuRkMQjHNMjOzo/FNSe0dqTdRw0dI5QpoqAgFk8MEkByIiZPIK6GYzkRv9NsBrVpRw3271VPG7gDlK4+ZEkjRXJ+JQgV0QxybU4XNE1pPlB3BxzBtsr56gPEVCNrVjNQtfTwNqphT39+7GShtEUrAsKU7r+nxivGxhd/8b2ECkk/7Dk7WPLnCJPnXJrIAWzKd1wiPaTPYrMvCuxRAMYF+sk6ZPENAipntbetAbXHDVs6KKbjyCjDLRwGX7rrIlPi0TTIH9nGfPTq4DL1CDxivnjd1eOGOnHzQRr”' \
--form 'integrityCheck="0bc22b4408a6a2bf135fd2eb3832775f44b02f96d7e10d940b81c5069763685f"'

Una vez enviado el POST a Addon Payments, recibirás la URL donde redireccionar al cliente:

				
					https://checkout33.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize?token
=3a873502-826c-4daf-be51-28804926d63b&apiVersion=5

Parámetros de la solicitud de autorización

Los parámetros requeridos/obligatorios y opcionales se encuentran en esta tabla.

Respuesta

Este es un ejemplo de la respuesta de pago que se obtiene para una operación autorizada: 

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7667902</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>
			<service>TRA</service>
			<status>SUCCESS</status>
			<transactionId>7667902</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>c03cbb3d_6436_4bb4_a0b0_e0fe717e13ad</uuid>
			</respCode>
		</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>
			<paymentDetails>
				<cardNumberToken>4535954006730084</cardNumberToken>
				<extraDetails/>
			</paymentDetails>
			<service>3DSv2</service>
			<status>REDIRECTED</status>
			<transactionId>7667902</transactionId>
			<respCode>
				<code>8000</code>
				<message>Successful authentication</message>
				<uuid>4fdf180e_60c6_4b17_9938_55cbf8439ca4</uuid>
			</respCode>
			<mpi>
				<acsTransID>274f5839-b4f8-408e-a5a3-9f7b3bfd5514</acsTransID>
				<authMethod>02</authMethod>
				<authTimestamp>202310021012</authTimestamp>
				<authenticationStatus>Y</authenticationStatus>
				<cavv>AJkBAlQ0Y1czBidENjRjAAAAAAA=</cavv>
				<eci>05</eci>
				<messageVersion>2.2.0</messageVersion>
				<result>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjVkYTRiNGUzLWQ4NGMtNGM5Yy04ZmUzLWFiN2MwNjJmYjBjZSIsImFjc1RyYW5zSUQiOiIyNzRmNTgzOS1iNGY4LTQwOGUtYTVhMy05ZjdiM2JmZDU1MTQiLCJhdXRoZW50aWNhdGlvblR5cGUiOiIwMSIsImF1dGhlbnRpY2F0aW9uTWV0aG9kIjoiMTAiLCJhdXRoZW50aWNhdGlvblZhbHVlIjoiQUprQkFsUTBZMWN6QmlkRU5qUmpBQUFBQUFBPSIsImRzVHJhbnNJRCI6IjE5NDQ0YzQzLTU2YmYtNDhiOS1iZmVkLTE1YzFjZjNkYzkyZSIsImVjaSI6IjA1IiwiaW50ZXJhY3Rpb25Db3VudGVyIjoiMDEiLCJtZXNzYWdlVHlwZSI6IlJSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwibWVzc2FnZUNhdGVnb3J5IjoiMDEiLCJ0cmFuc1N0YXR1cyI6IlkifQ==</result>
				<threeDSv2Token>5da4b4e3-d84c-4c9c-8fe3-ab7c062fb0ce</threeDSv2Token>
			</mpi>
			<paymentCode>nsY1</paymentCode>
			<paymentMessage>Authenticated successfully</paymentMessage>
		</operation>
		<operation sorted-order="3">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfRTS":"355534686 790190 809968 231002121202","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":"************0084","rfOperationDateTime":"02/10/23 12:12:02","rfTerminalOperationNumber":"1121","rfAuthNumber":"014523","rfTransactionAmountCurrency":"10,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1121","posTransactionToken":"{\"pucIdMsg\":\"1200\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000001000\",\"pucP11TransactionNumber\":\"809968\",\"pucP12LocalDateTime\":\"231002121202\",\"pucP22ServicePointData\":\"1U00506U3000\",\"pucP38AuthNumber\":\"014523\",\"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\":\"1121\",\"transactionResponseCode\":null,\"transactionCurrency\":\"978\",\"transactionFuc\":\"355534686\",\"cardMaskedPan\":\"************0084\",\"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/>
			<paySolTransactionId>355534686 790190 809968 231002121202</paySolTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa</cardHolderName>
				<cardNumber>490727****2227</cardNumber>
				<cardType>VISA/CREDIT OR DEBIT</cardType>
				<expDate>1023</expDate>
				<extraDetails>
					<entry>
						<key>cardCategory</key>
						<value>Not Available</value>
					</entry>
					<entry>
						<key>rememberMe</key>
						<value>false</value>
					</entry>
				</extraDetails>
				<issuerBank>SERVIRED MASTERCARD INTERNACIONAL</issuerBank>
				<issuerCountry>ES</issuerCountry>
			</paymentDetails>
			<paymentMethod>19900</paymentMethod>
			<paymentSolution>caixapucpuce</paymentSolution>
			<status>SUCCESS</status>
			<transactionId>7667902</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>c03cbb3d_6436_4bb4_a0b0_e0fe717e13ad</uuid>
			</respCode>
			<authCode>014523</authCode>
			<mpi>
				<eci>05</eci>
			</mpi>
			<paymentCode>000</paymentCode>
			<paymentMessage>Operación finalizada con éxito</paymentMessage>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</response>

Pre-autorización

Las pre-autorizaciones son un método de pago en 2 fases. Se realiza el envío de la operación por redirección con el valor “false” en el parámetro “autoCapture”. Al cliente se le mostrará el Hosted de forma idéntica al de una autorización.

Después de que el cliente haya autorizado la transacción, el dinero correspondiente se aparta temporalmente de su cuenta bancaria o del saldo de su tarjeta. El comercio tiene un plazo máximo de 30 días para confirmar o rechazar esta pre-autorización. Sin embargo, no se asegura que el importe retenido se liquide después de 7 días. Es importante destacar que el comercio no recibirá los fondos de la pre-autorización en su cuenta hasta que esta sea confirmada.

Las pre-autorizaciones, si la transacción está autorizada, quedarán en status «Pending». Puedes liquidar manualmente estas transacciones desde el portal BackOffice de Addon Payments o mediante una solicitud H2H para capturar el importe.

Además, recomendamos que visites nuestra sección 3DSecure con el objetivo de añadir campos adicionales al proceso de pago. Estos datos opcionales enriquecen la solicitud de pago y pueden facilitar el proceso de autenticación.

Petición

Este es un ejemplo de petición de una pre-autorización de pago con tarjeta, el primero como cadena y el segundo como cURL. Recuerda que la cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&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
				
			
				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: JdzesBT3L9h4lGnf2joraA==' \
--form 'merchantId="12345"' \
--form 'encrypted="4xUYxJxLc/ABCyqJfwttTalkds3YeijsJe6MlTnC6mgmbm0aXKwhI7thwa70o6lLyjrUtW8fFNUWf/l3jIojR4H5nW54Pl+GxerG1/AjMFpHlacchB3+kfkZzko42dQKk7MopAALi6SAFbl1Uq//qsESz8fV07ED7IvRQwlXREZDFtxQn2m9eyPr5zrJczILhRx27p3lqFQ61Sqlq0nCN+3sgJmuPUMKRqlXhYqf+vErv+fBaZMPV/8iKgERJLpIjPn+HZSLpc+q5VBcD4b+rGAgEKNi56Ni/MPCpKVWBUv8HFb06PngrLfiXcnFTfNeegg0XPkkmuGwR1l1y/k1tv9dPrdBkSIwE2OuHYvrkrn+NAOTHBxjGR4Ap93aZEwcPX9afkHkFOMi/5e3JdoxtFvSwOCe1ScEw2vRDhonE+5lV7jwOrqSMr+tfWVGPqzrYj/DZiQwCIUQJM6g5x+ocLTAURzz4IiJ26kBlQpYVnedKEVhevNJNZ88z6m50W2THtDR70pQq6qjF37NCfOeq/UDCg0RB/MPfYUJRUIsfPk=' \
--form 'integrityCheck="1c256f5b834e5db6d5f453043a8a3830859b308f297cc2cf423064510c5c9b72"'

Una vez enviado el POST a Addon Payments, recibirás la URL donde redireccionar al cliente:

				
					https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize
?token=f5a11694-206f-48db-8b0c-cd958b0382e7&apiVersion=5

Parámetros de la solicitud de pre-autorización

Los parámetros requeridos/obligatorios y opcionales se encuentran en esta tabla.

Además de esos parámetros, para una pre-autorización debes incluir:

  • autoCapture: false

Respuesta

En la pre-autorización, la respuesta de la transacción quedará como pendiente hasta que captures o liberes el importe:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7667941</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>
			<service>TRA</service>
			<status>SUCCESS</status>
			<transactionId>7667941</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>c03cbb3d_6436_4bb4_a0b0_e0fe717e13ad</uuid>
			</respCode>
		</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>
			<paymentDetails>
				<cardNumberToken>4535954006730084</cardNumberToken>
				<extraDetails/>
			</paymentDetails>
			<service>3DSv2</service>
			<status>REDIRECTED</status>
			<transactionId>7667941</transactionId>
			<respCode>
				<code>8000</code>
				<message>Successful authentication</message>
				<uuid>4fdf180e_60c6_4b17_9938_55cbf8439ca4</uuid>
			</respCode>
			<mpi>
				<acsTransID>38677419-ade7-47c4-8229-43857e3ce4f0</acsTransID>
				<authMethod>02</authMethod>
				<authTimestamp>202310021025</authTimestamp>
				<authenticationStatus>Y</authenticationStatus>
				<cavv>AJkBAlQ0Y1czBidENjRjAAAAAAA=</cavv>
				<eci>05</eci>
				<messageVersion>2.2.0</messageVersion>
				<result>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6Ijc4YWRiNWZlLWU3ZGYtNDQ0Mi04Y2QwLWNhODYwYmRhYzY3MSIsImFjc1RyYW5zSUQiOiIzODY3NzQxOS1hZGU3LTQ3YzQtODIyOS00Mzg1N2UzY2U0ZjAiLCJhdXRoZW50aWNhdGlvblR5cGUiOiIwMSIsImF1dGhlbnRpY2F0aW9uTWV0aG9kIjoiMTAiLCJhdXRoZW50aWNhdGlvblZhbHVlIjoiQUprQkFsUTBZMWN6QmlkRU5qUmpBQUFBQUFBPSIsImRzVHJhbnNJRCI6ImZjYWRhMGQ1LTkwODgtNGM5OS04YzQxLWY2OTU0ZDkwOGE3MyIsImVjaSI6IjA1IiwiaW50ZXJhY3Rpb25Db3VudGVyIjoiMDEiLCJtZXNzYWdlVHlwZSI6IlJSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwibWVzc2FnZUNhdGVnb3J5IjoiMDEiLCJ0cmFuc1N0YXR1cyI6IlkifQ==</result>
				<threeDSv2Token>78adb5fe-e7df-4442-8cd0-ca860bdac671</threeDSv2Token>
			</mpi>
			<paymentCode>nsY1</paymentCode>
			<paymentMessage>Authenticated successfully</paymentMessage>
		</operation>
		<operation sorted-order="3">
			<amount>10.00</amount>
			<currency>EUR</currency>
			<details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfRTS":"355534686 790190 809959 231002122555","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":"************0084","rfOperationDateTime":"02/10/23 12:25:55","rfTerminalOperationNumber":"1122","rfAuthNumber":"221432","rfTransactionAmountCurrency":"10,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1122","posTransactionToken":"{\"pucIdMsg\":\"1100\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000001000\",\"pucP11TransactionNumber\":\"809959\",\"pucP12LocalDateTime\":\"231002122555\",\"pucP22ServicePointData\":\"1U00506U3000\",\"pucP38AuthNumber\":\"221432\",\"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\":\"1122\",\"transactionResponseCode\":null,\"transactionCurrency\":\"978\",\"transactionFuc\":\"355534686\",\"cardMaskedPan\":\"************0084\",\"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/>
			<paySolTransactionId>355534686 790190 809959 231002122555</paySolTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Challenge</cardHolderName>
				<cardNumber>401200****0084</cardNumber>
				<cardNumberToken>4535954006730084</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>EXTRAS TEST - VISA</issuerBank>
				<issuerCountry>ES</issuerCountry>
			</paymentDetails>
			<paymentMethod>19900</paymentMethod>
			<paymentSolution>caixapucpuce</paymentSolution>
			<status>PENDING</status>
			<transactionId>7667941</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>c03cbb3d_6436_4bb4_a0b0_e0fe717e13ad</uuid>
			</respCode>
			<authCode>221432</authCode>
			<mpi>
				<eci>05</eci>
			</mpi>
			<paymentCode>000</paymentCode>
			<paymentMessage>Operación finalizada con éxito</paymentMessage>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</response>

Validación de tarjeta

La validación de tarjeta consiste en una operación con importe 0, que genera un token o referencia de la tarjeta del cliente para futuras operaciones. Esta operativa también se conoce como Open To Buy (OTB). 

Normalmente, estas validaciones de tarjeta con importe 0 tienen como objetivo guardar la tarjeta del cliente para futuros pagos, en ese caso recomendamos que adicionalmente se incluyan los parámetros:

  • amount: 0
  • paymentRecurringType: newCof
  • challengeInd: 04 (recomendable para forzar la SCA de la transacción y evitar denegaciones del emisor en peticiones posteriores)

Esta operativa valida que la tarjeta está operativa en el momento de la consulta, por lo que no garantiza que los pagos posteriores sean autorizados. 

Además, recomendamos que visites nuestra sección 3DSecure con el objetivo de añadir campos adicionales al proceso de pago. Estos datos opcionales enriquecen la solicitud de pago y pueden facilitar el proceso de autenticación.

Petición

Este es un ejemplo de petición de una validación de tarjeta, el primero como cadena y el segundo como cURL. Recuerda que la cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&amount=0&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://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: NLcwVLj3JPECqmat32gGaw==' \
--form 'merchantId="12345"' \
--form 'encrypted=" WtL6Eq+5/OYSIKWexrjdKHzxv9xL3HQqjH5OA/bCXH4iaKll9Zk2d9l2tOiWgOJqejrbndsmJWudCWnkYWxU18jSzIxO8lbBnVw5SgL24Ygq6b0jhb0IyJXK018kc0FaKNFM3DN29ZU5uhrJpd7nzQhulP2uc3CLcQymJDue2vEns1q3zPysEkWjPL+Z+6HoTtbxMUWK8ibimMO8BYl5FamkmWWcrx6+fcyUL553WjfdvnW9+G1kuyTez8WwOR6PNsSEKsm2lOBRABLzfLIPxHbCMN29cWOybVf1CEomJm+pZzDUiBlSpFFu5mT9NOZzrc4fklaexp63+UpjnnjvOSRHr0HmL4C5YdsS/OowJvUEdrMaexbO7uRGOwKlU8+c6gHK8NpEBSK1fbLhi9qnUvzoIUyuMndqUJQ7Nomc4YxR906tZzahe19Cc/7ewt3/ZWDTQSaRUSsq1PMe3krtAVxnWwOqR+gCWQWu50Kyp/qEMfuswBPq9m2u6/I7+5zZ”' \
--form 'integrityCheck="e834eea3beec3cd3964a0b94e909d658424778b50659a591b2653e52db8a41c4"'

Una vez enviado el POST a Addon Payments, recibirás la URL donde redireccionar al cliente:

				
					https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize
?token=c4cd4823-6514-4300-8365-f0ad1d1ec8ce&apiVersion=5

Parámetros de la solicitud de validación de tarjeta

Los parámetros requeridos/obligatorios y opcionales se encuentran en esta tabla.

Además de esos parámetros, para una validación de tarjeta debes incluir los de la siguiente tabla. El tipo indica si el elemento es Requerido (R) u Opcional (O):

CampoFormatoTipoDescripciónEjemplo
amountNumérico decimal
0~1000000.00		RImporte de la transacción. Si el importe tiene decimales, el separador es un punto (.). No se puede incluir el separador en los millares. En validaciones de tarjeta, ha de ser «0». 0
paymentRecurringType– newCof: Pagos puntuales, sin importe ni intervalo de tiempo fijo.
– newSubscription: Pago recurrente con importe e intervalo de tiempo definido.
– newInstallment: Pago aplazado limitado a una compra individual con importe e intervalo de tiempo definido.		OTipo de pago recurrente o sucesivo. Indica si la transacción C.O.F. es inicial o sucesiva, así como el motivo u objetivo del pago.newCof
challengeIndValores aceptados:
– 01: sin preferencia (valor por defecto si no se envía este parámetro)
– 02: evitar challenge
– 03: requerir challenge (preferencia del comercio)
– 04: requerir challenge (obligatorio)
– 05: evitar challenge (realizado análisis de riesgo de transacción)
– 06: evitar challenge (sólo en compartir datos)
– 07: evitar challenge (SCA ya realizada)
– 08: evitar challenge (utiliza exención de lista blanca)
– 09: evitar challenge (solicitar lista blanca)		OIndica la preferencia marcada por el comercio ante un proceso de autenticación. El emisor puede modificar la preferencia especificada en este campo.04

Respuesta

Esta es la respuesta recibida en la validación de tarjeta. En la zona resaltada de la respuesta, tienes los detalles de la tarjeta que podrás usar en futuras operaciones, como el token. 

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7668634</message>
	<operations>
		<operation sorted-order="1">
			<amount>0</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Exemptions has been removed</message>
			<operationType>DEBIT</operationType>
			<service>TRA</service>
			<status>SUCCESS</status>
			<transactionId>7668634</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>c03cbb3d_6436_4bb4_a0b0_e0fe717e13ad</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>0</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Starting 3DSecure 2.0 process.</message>
			<operationType>DEBIT</operationType>
			<paymentDetails>
				<cardNumberToken>4535954006730084</cardNumberToken>
				<extraDetails/>
			</paymentDetails>
			<service>3DSv2</service>
			<status>REDIRECTED</status>
			<transactionId>7668634</transactionId>
			<respCode>
				<code>8000</code>
				<message>Successful authentication</message>
				<uuid>7c5d8b33_9def_4dc5_8d75_53c6306f10b2</uuid>
			</respCode>
			<mpi>
				<acsTransID>19086b03-a6b1-4ff2-8193-853092241fa2</acsTransID>
				<authMethod>02</authMethod>
				<authTimestamp>202310021341</authTimestamp>
				<authenticationStatus>Y</authenticationStatus>
				<cavv>AJkBAlQ0Y1czBidENjRjAAAAAAA=</cavv>
				<eci>05</eci>
				<messageVersion>2.2.0</messageVersion>
				<result>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNlMTlhOTZmLTExNWItNDQ4Mi05N2NmLWM4YzRjN2RkYjRlZCIsImFjc1RyYW5zSUQiOiIxOTA4NmIwMy1hNmIxLTRmZjItODE5My04NTMwOTIyNDFmYTIiLCJhdXRoZW50aWNhdGlvblR5cGUiOiIwMSIsImF1dGhlbnRpY2F0aW9uTWV0aG9kIjoiMTAiLCJhdXRoZW50aWNhdGlvblZhbHVlIjoiQUprQkFsUTBZMWN6QmlkRU5qUmpBQUFBQUFBPSIsImRzVHJhbnNJRCI6IjVhZDVmOTJmLWY0YWYtNGY1Zi1hMjA0LTk5MDQwNDI3NzcyZiIsImVjaSI6IjA1IiwiaW50ZXJhY3Rpb25Db3VudGVyIjoiMDEiLCJtZXNzYWdlVHlwZSI6IlJSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwibWVzc2FnZUNhdGVnb3J5IjoiMDEiLCJ0cmFuc1N0YXR1cyI6IlkifQ==</result>
				<threeDSv2Token>3e19a96f-115b-4482-97cf-c8c4c7ddb4ed</threeDSv2Token>
			</mpi>
			<paymentCode>nsY1</paymentCode>
			<paymentMessage>Authenticated successfully</paymentMessage>
		</operation>
		<operation sorted-order="3">
			<amount>0.00</amount>
			<currency>EUR</currency>
			<details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfRTS":"355534686 790190 810151 231002154112","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":"************0084","rfOperationDateTime":"02/10/23 15:41:12","rfTerminalOperationNumber":"1125","rfAuthNumber":"090354","rfTransactionAmountCurrency":"0,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1125","posTransactionToken":"{\"pucIdMsg\":\"1100\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000000000\",\"pucP11TransactionNumber\":\"810151\",\"pucP12LocalDateTime\":\"231002154112\",\"pucP22ServicePointData\":\"1U00506U3000\",\"pucP38AuthNumber\":\"090354\",\"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\":\"1125\",\"transactionResponseCode\":null,\"transactionCurrency\":\"978\",\"transactionFuc\":\"355534686\",\"cardMaskedPan\":\"************0084\",\"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/>
			<paySolTransactionId>355534686 790190 810151 231002154112</paySolTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Challenge</cardHolderName>
				<cardNumber>401200****0084</cardNumber>
				<cardNumberToken>4535954006730084</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>EXTRAS TEST - VISA</issuerBank>
				<issuerCountry>ES</issuerCountry>
			</paymentDetails>
			<paymentMethod>19900</paymentMethod>
			<paymentSolution>caixapucpuce</paymentSolution>
			<status>SUCCESS</status>
			<transactionId>7668634</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>c03cbb3d_6436_4bb4_a0b0_e0fe717e13ad</uuid>
			</respCode>
			<authCode>090354</authCode>
			<mpi>
				<eci>05</eci>
			</mpi>
			<paymentCode>000</paymentCode>
			<paymentMessage>Operación finalizada con éxito</paymentMessage>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</response>

Guardado de tarjetas

En Addon Payments puedes guardar tarjetas mediante la generación de referencias o tokenización. Esta operativa tiene varios casos de uso, que veremos a continuación.

Almacenamiento de tarjetas

El guardado de tarjetas se controla según los parámetros enviados en la petición. Si el cliente finaliza la transacción con éxito obtendrás el «cardNumberToken», que es el token de la tarjeta del cliente. Este campo está directamente relacionado con el «customerId» enviado en la solicitud de pago. Además, ten en cuenta que un «customerId» puede tener varios tokens de tarjetas asociados.

Casos de uso y parámetros 

Los casos de uso en el guardado de las tarjetas en Hosted son los de la siguiente tabla. Recuerda que el guardado de la tarjeta es opcional en las operativas. Para guardar (o no) la tarjeta del cliente, incluye los siguientes parámetros además de los comunes:

ObjetivoParámetroTipoValorDescripción
Guardar la tarjetaforceTokenRequestBooleanotrueSi fuerzas el guardado del token recibirás el token de la tarjeta y esta se guardará para usos posteriores. Debes informar al cliente de que almacenarás información de su tarjeta.
Nota: Aunque fuerces el guardado de token, si muestras las casilla de «Recuérdame» y el cliente NO la marca, no se guardará el token. Para forzar el guardado del token, no envíes el parámetro «showRememberMe» o envíalo a «false».
No guardar tarjetashowRememberMeBooleanofalseSe ocultará el checkbox en nuestro formulario que permite elegir al cliente guardar o no la tarjeta. No tendrás el «cardNumberToken» en la respuesta y no aparecerá cumplimentada en pagos subsiguientes del mismo cliente (customerId). Nota: Para asegurarte de que NO se guarda, envía adicionalmente «forceTokenRequest=false», de esta forma, aunque se muestre y se marque la casilla «Recúerdame», no se guardará el token.
Permitir guardar tarjeta al clienteshowRememberMeBooleanotrueMostrará el check de guardado de tarjeta «Recuérdame». Si el cliente elige guardar la tarjeta y la transacción se autoriza, se guardará para este customerId y obtendrás el token en la respuesta. Si el cliente no marca «Recuérdame», no se guardará el token de la tarjeta.
No enviar ninguno de los parámetros anterioresN/AN/AN/ASi no se envía ninguno de los parámetros anteriores, se mostrará el check de guardado de la tarjeta «Recuérdame». Si el cliente lo marca, se guardará la tarjeta para usos posteriores. Si el cliente no lo marca, se generará el token pero no lo podrás usar para pagos posteriores.
Nota: En la notificación se recibirá el «rememberMe» con valor «false», de esta forma sabrás que no se puede usar ese token.

Petición

Este es un ejemplo de petición para forzar el guardado de la tarjeta, el primero como cadena y el segundo como cURL. Recuerda que la cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency
=EUR&country=ES&customerId=000001&paymentSolution=creditcards&productId
=123450001&forceTokenRequest=true&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://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 02WakwHB2vl0iq4AZ1PMVQ==' \
--form 'merchantId="12345"' \
--form 'encrypted=" 2rWonKmWKGFzJ6WRIGuyCRIX+4laoAvKqdiBNc+19TiT89yi0oaUTgyI3MTHdIlArpHCJec3NhXzDmyaHpImPSpYkzyP2sgQm9xaZCf/z+XGFe6c3VypQtmQtyr3V0VrJzJxGQq/9la4la+QNH20YNNpsDrV/AwVldQXCWU3h6aLZi1gW0SsrGAm60tNsSkBjFbFqWukimRpnwhScJ0sQ7ngWvnT1l1uD07O9MdGvQe9y39ukq6Agrw0isz5SCifHqQjgJgTtZQ5SBOBP7E3bLCS1oD+Nk7KJpjqQgEoFjHd/L6gzvEuBJl3/JPbpmHtTbFoPQlAEiY3VXMV6GFddUowwBFPRg+Lw6A6SQWYY7zOjJJbGxBRZ4MsFX+oaBYog1ectoGJsMnTohTykOhdO91DXVADTo24dg7FrdDPNNYpw0lgwEI0U3/+kv8MJ+I0yKR6gti0Mt4Go6ccYVjgsJy7oRwt7cCOI7fgU/j8DNknqzFAviAb5kYDSvgmZyEXMFSFjUl7WmgkYAocWVxxaSFIQ0wmZx5ZJjaJN4ckqow=”' \
--form 'integrityCheck="87b9a3c29645de41fbf1d337d79232db55c10a481e17b9e65d18a8e0b04c3b01"'

Una vez enviado el POST a Addon Payments, recibirás la URL donde redireccionar al cliente:

				
					https://checkout.stg-eu-west1.epgint.com/EPGCheckout/rest/online/detokenize
?token=dd058d10-cb76-48d8-a3fb-750a643b779f&apiVersion=5

Respuesta

Este es un ejemplo de tarjeta donde se nos devuelve el «cardNumberToken»:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="3">
	<message>WorkFlow has finished successfully, for transaction Id: 7668634</message>
	<operations>
		<operation sorted-order="1">
			<amount>0</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Exemptions has been removed</message>
			<operationType>DEBIT</operationType>
			<service>TRA</service>
			<status>SUCCESS</status>
			<transactionId>7668634</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>c03cbb3d_6436_4bb4_a0b0_e0fe717e13ad</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>0</amount>
			<currency>EUR</currency>
			<merchantTransactionId>00000001</merchantTransactionId>
			<message>Starting 3DSecure 2.0 process.</message>
			<operationType>DEBIT</operationType>
			<paymentDetails>
				<cardNumberToken>4535954006730084</cardNumberToken>
				<extraDetails/>
			</paymentDetails>
			<service>3DSv2</service>
			<status>REDIRECTED</status>
			<transactionId>7668634</transactionId>
			<respCode>
				<code>8000</code>
				<message>Successful authentication</message>
				<uuid>7c5d8b33_9def_4dc5_8d75_53c6306f10b2</uuid>
			</respCode>
			<mpi>
				<acsTransID>19086b03-a6b1-4ff2-8193-853092241fa2</acsTransID>
				<authMethod>02</authMethod>
				<authTimestamp>202310021341</authTimestamp>
				<authenticationStatus>Y</authenticationStatus>
				<cavv>AJkBAlQ0Y1czBidENjRjAAAAAAA=</cavv>
				<eci>05</eci>
				<messageVersion>2.2.0</messageVersion>
				<result>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNlMTlhOTZmLTExNWItNDQ4Mi05N2NmLWM4YzRjN2RkYjRlZCIsImFjc1RyYW5zSUQiOiIxOTA4NmIwMy1hNmIxLTRmZjItODE5My04NTMwOTIyNDFmYTIiLCJhdXRoZW50aWNhdGlvblR5cGUiOiIwMSIsImF1dGhlbnRpY2F0aW9uTWV0aG9kIjoiMTAiLCJhdXRoZW50aWNhdGlvblZhbHVlIjoiQUprQkFsUTBZMWN6QmlkRU5qUmpBQUFBQUFBPSIsImRzVHJhbnNJRCI6IjVhZDVmOTJmLWY0YWYtNGY1Zi1hMjA0LTk5MDQwNDI3NzcyZiIsImVjaSI6IjA1IiwiaW50ZXJhY3Rpb25Db3VudGVyIjoiMDEiLCJtZXNzYWdlVHlwZSI6IlJSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwibWVzc2FnZUNhdGVnb3J5IjoiMDEiLCJ0cmFuc1N0YXR1cyI6IlkifQ==</result>
				<threeDSv2Token>3e19a96f-115b-4482-97cf-c8c4c7ddb4ed</threeDSv2Token>
			</mpi>
			<paymentCode>nsY1</paymentCode>
			<paymentMessage>Authenticated successfully</paymentMessage>
		</operation>
		<operation sorted-order="3">
			<amount>0.00</amount>
			<currency>EUR</currency>
			<details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfRTS":"355534686 790190 810151 231002154112","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":"************0084","rfOperationDateTime":"02/10/23 15:41:12","rfTerminalOperationNumber":"1125","rfAuthNumber":"090354","rfTransactionAmountCurrency":"0,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1125","posTransactionToken":"{\"pucIdMsg\":\"1100\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000000000\",\"pucP11TransactionNumber\":\"810151\",\"pucP12LocalDateTime\":\"231002154112\",\"pucP22ServicePointData\":\"1U00506U3000\",\"pucP38AuthNumber\":\"090354\",\"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\":\"1125\",\"transactionResponseCode\":null,\"transactionCurrency\":\"978\",\"transactionFuc\":\"355534686\",\"cardMaskedPan\":\"************0084\",\"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/>
			<paySolTransactionId>355534686 790190 810151 231002154112</paySolTransactionId>
			<paymentDetails>
				<cardHolderName>Pruebas Visa Challenge</cardHolderName>
				<cardNumber>401200****0084</cardNumber>
				<cardNumberToken>4535954006730084</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>EXTRAS TEST - VISA</issuerBank>
				<issuerCountry>ES</issuerCountry>
			</paymentDetails>
			<paymentMethod>19900</paymentMethod>
			<paymentSolution>caixapucpuce</paymentSolution>
			<status>SUCCESS</status>
			<transactionId>7668634</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>c03cbb3d_6436_4bb4_a0b0_e0fe717e13ad</uuid>
			</respCode>
			<authCode>090354</authCode>
			<mpi>
				<eci>05</eci>
			</mpi>
			<paymentCode>000</paymentCode>
			<paymentMessage>Operación finalizada con éxito</paymentMessage>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>31380</id>
		<name>debit creditcards (TRA)</name>
		<version>0</version>
	</workFlowResponse>
</response>

Mostrar tarjetas

En Addon Payments puedes decidir si mostrar las tarjetas guardadas al cliente. Esta operativa está relacionada con el guardado de tarjetas y el identificador del cliente.

Para mostrar las tarjetas guardadas a un cliente se deben cumplir estos requisitos:

  • Has forzado el guardado de tarjeta como se muestra en la sección anterior o el cliente ha decidido guardar su tarjeta marcando el checkbox de «Recuérdame». El token de la tarjeta que se guarda se asocia a un identificador de cliente (customerId).
  • En las siguientes transacciones, el identificador de cliente (customerId) debe ser el mismo que el que se usó para guardar la tarjeta. Por lo que estas se muestran en el cajero de pago.

Por ejemplo, el cliente con el «customerId» «01» hace una compra en tu comercio electrónico y decide marcar la casilla de «recuérdame», por lo que se guarda su tarjeta. Más tarde, el mismo cliente (con el «customerId» «01») hace otra compra y tiene su tarjeta disponible en el cajero de pago. 

Si el cliente entra como invitado a tu plataforma, tendrá otro «customerId», por lo que no verá sus tarjetas guardadas.

Petición

La petición para mostrar las tarjetas a un cliente es igual que el resto de operativas. Sin embargo, debes enviar el mismo «customerId» que se ha utilizado para guardar tarjetas.

Visualización del cajero

Pagos recurrentes

En esta sección, encontrarás cómo guardar la tarjeta del cliente con el objetivo de realizar pagos posteriores sin la interacción del cliente o C.I.T (Customer Initiated Transaction).

En estos casos de uso, el cliente debe realizar un pago inicial autenticado con 3DS2 y SCA, que permitirá guardar los datos de su tarjeta y dar su consentimiento para pagos posteriores. Este tipo de transacción se denomina C.O.F (Credential On File).

Alta plan de suscripción

Mediante esta integración puedes dar de alta un plan de suscripción, permitiendo que el cliente guarde su tarjeta para pagos posteriores. En la petición, deberás incluir parámetros C.O.F y forzar SCA, para evitar futuras denegaciones del emisor. En la respuesta, recibirás el «subscriptionPlan», que será el identificador para las operaciones posteriores y está directamente vinculado al «cardNumberToken» de la respuesta, y al «customerId» remitido por tu parte en la solicitud del pago. Todo esto lo veremos a continuación.

En esta primera transacción, debes informar del tipo de transacciones que se emitirán posteriormente en función de tus necesidades. Aquí tienes una tabla con los parámetros para indicarlo, dentro de «paymentRecurringType», y su función:

Pago inicialPagos sucesivosDescripciónEjemplo
newCofcofPagos puntuales, sin importe ni intervalo de tiempo fijo.Compra en la cual el cliente selecciona guardar la tarjeta para transacciones posteriores.
newSubscriptionsubscriptionPago recurrente con importe e intervalo de tiempo definido.Cuotas o suscripciones.
newInstallmentinstallmentPago aplazado limitado a una compra individual con importe e intervalo de tiempo definido.Compra a plazos

Además, recomendamos que visites nuestra sección 3DSecure con el objetivo de añadir campos adicionales al proceso de pago. Estos datos opcionales enriquecen la solicitud de pago y pueden facilitar el proceso de autenticación.

Petición

A continuación, tienes ejemplos de alta de un plan de suscripción, el primero como cadena y el segundo como cURL. Recuerda que la cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&amount=1.00&currency=EUR&country
=ES&challengeInd=04&paymentRecurringType=newSubscription&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://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 0Pn6pDEm73YvekNKUJcvwg==' \
--form 'merchantId="12345"' \
--form 'encrypted="jULXEtDfSVYIgfV29GBTcibe+ED+IvnfI2ssayrpqoJRzmI+SVst1SV3LRjt7DHlU5+0FoBPZy8KfoajNYn6DwRU0ltMtgd2TsR2ccm+Aeg5NAPbMlVZZnDmWA2WUmh3sXFWDMFGcHnwigMv0dWW+0QOieFJN+NLPMo/HMhLOLNNfS9240qdT++PTx7IdtSM3hfbD31ZDgKSkxwCDQYSrcIS0LyPtRuRkMQjHNMjOzo/FNSe0dqTdRw0dI5QpoqAgFk8MEkByIiZPIK6GYzkRv9NsBrVpRw3271VPG7gDlK4+ZEkjRXJ+JQgV0QxybU4XNE1pPlB3BxzBtsr56gPEVCNrVjNQtfTwNqphT39+7GShtEUrAsKU7r+nxivGxhd/8b2ECkk/7Dk7WPLnCJPnXJrIAWzKd1wiPaTPYrMvCuxRAMYF+sk6ZPENAipntbetAbXHDVs6KKbjyCjDLRwGX7rrIlPi0TTIH9nGfPTq4DL1CDxivnjd1eOGOnHzQRr”' \
--form 'integrityCheck="0bc22b4408a6a2bf135fd2eb3832775f44b02f96d7e10d940b81c5069763685f"'

Una vez enviado el POST a Addon Payments, recibirás la URL donde redireccionar al cliente: 

				
					https://checkout33.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize?token
=3a873502-826c-4daf-be51-28804926d63b&apiVersion=5

Parámetros de la solicitud de alta plan de suscripción

Los parámetros requeridos/obligatorios y opcionales se encuentran en esta tabla.

Además de esos parámetros, para dar de alta un plan de suscripción, debes añadir los siguientes parámetros. El tipo indica si el elemento es Requerido (R) u Opcional (O):

    CampoFormatoTipoDescripciónEjemplo
    paymentRecurringType– newCof: Pagos puntuales, sin importe ni intervalo de tiempo fijo.
    – newSubscription: Pago recurrente con importe e intervalo de tiempo definido.
    – newInstallment: Pago aplazado limitado a una compra individual con importe e intervalo de tiempo definido.    		RTipo de pago recurrente o sucesivo. Indica si la transacción C.O.F. es inicial o sucesiva, así como el motivo u objetivo del pago.newSubscription
    challengeIndValores aceptados:
    – 01: sin preferencia (valor por defecto si no se envía este parámetro)
    – 02: evitar challenge
    – 03: requerir challenge (preferencia del comercio)
    – 04: requerir challenge (obligatorio)
    – 05: evitar challenge (realizado análisis de riesgo de transacción)
    – 06: evitar challenge (sólo en compartir datos)
    – 07: evitar challenge (SCA ya realizada)
    – 08: evitar challenge (utiliza exención de lista blanca)
    – 09: evitar challenge (solicitar lista blanca)    		RIndica la preferencia marcada por el comercio ante un proceso de autenticación. El emisor puede modificar la preferencia especificada en este campo.04

    Respuesta

    Este es un ejemplo de respuesta. Destacamos el «subscriptionPlan», que es el parámetro que debes usar en pagos sucesivos. 

    				
					<?xml version="1.0" encoding="UTF-8"?>
<payfrex-response operation-size="3">
   <message>WorkFlow has finished successfully, for transaction Id: 7707259</message>
   <operations>
      <operation sorted-order="1">
         <amount>1.00</amount>
         <currency>EUR</currency>
         <merchantTransactionId>88388066</merchantTransactionId>
         <message>Exemptions has been removed</message>
         <operationType>DEBIT</operationType>
         <payFrexTransactionId>7707259</payFrexTransactionId>
         <service>TRA</service>
         <status>SUCCESS</status>
         <respCode>
            <code>0000</code>
            <message>Successful</message>
            <uuid>dd04d570_bf82_4b9b_baf6_6ec123601521</uuid>
         </respCode>
      </operation>
      <operation sorted-order="2">
         <amount>1.00</amount>
         <currency>EUR</currency>
         <merchantTransactionId>88388066</merchantTransactionId>
         <message>3dsv2 - processed</message>
         <operationType>DEBIT</operationType>
         <payFrexTransactionId>7707259</payFrexTransactionId>
         <paymentDetails>
            <extraDetails />
         </paymentDetails>
         <service>3DSv2</service>
         <status>SUCCESS3DS</status>
         <respCode>
            <code>8000</code>
            <message>Successful authentication</message>
            <uuid>28d943be_e311_4889_a810_dfa699c1d200</uuid>
         </respCode>
         <mpi>
            <acsTransID>d3378e3e-8c5a-450b-b697-73520f6ce8c1</acsTransID>
            <authMethod>01</authMethod>
            <authTimestamp>202310260734</authTimestamp>
            <authenticationStatus>Y</authenticationStatus>
            <cavv>AJkBB4OBmVFmgYFYFIGZAAAAAAA=</cavv>
            <eci>05</eci>
            <messageVersion>2.2.0</messageVersion>
            <threeDSSessionData>ZjExNjgyMWYtZDJlOC00ZjA3LTkxNWQtZmM3OTMwZDQ3NWMy</threeDSSessionData>
            <threeDSv2Token>f116821f-d2e8-4f07-915d-fc7930d475c2</threeDSv2Token>
         </mpi>
         <paymentCode>nsY1</paymentCode>
         <paymentMessage>Authenticated successfully</paymentMessage>
      </operation>
      <operation sorted-order="3">
         <amount>1.00</amount>
         <currency>EUR</currency>
         <details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfRTS":"355534686 790190 840066 231026093455","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":"26/10/23 09:34:55","rfTerminalOperationNumber":"1150","rfAuthNumber":"075909","rfTransactionAmountCurrency":"1,00 EUR","rfProcessorMessage":"","rfPrintSignatureBox":"false","rfCardPresent":"true","rfReferenceId":"1150","posTransactionToken":"{\"pucIdMsg\":\"1200\",\"pucP3ProcessCode\":\"000000\",\"pucP4OriginalAmount\":\"000000000100\",\"pucP11TransactionNumber\":\"840066\",\"pucP12LocalDateTime\":\"231026093455\",\"pucP22ServicePointData\":\"1U00506K3000\",\"pucP38AuthNumber\":\"075909\",\"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\":\"1150\",\"transactionResponseCode\":null,\"transactionCurrency\":\"978\",\"transactionFuc\":\"355534686\",\"cardMaskedPan\":\"************2227\",\"cardAid\":null,\"cardDdfName\":null,\"cardApplicationLabel\":null,\"cardCypherData\":null}","OperationResult":"000","cofAdditionalInformation":"RS708120533554282"},"threeDsProtocolVersion":"2.2.0"}</details>
         <merchantTransactionId>88388066</merchantTransactionId>
         <message>Success 'Settle' operation</message>
         <operationType>DEBIT</operationType>
         <optionalTransactionParams />
         <payFrexTransactionId>7707259</payFrexTransactionId>
         <paySolTransactionId>355534686 790190 840066 231026093455</paySolTransactionId>
         <paymentDetails>
            <cardHolderName>Pruebas Visa</cardHolderName>
            <cardNumber>490727****2227</cardNumber>
            <cardNumberToken>4535954006730084</cardNumberToken>
            <cardType>VISA/CREDIT OR DEBIT</cardType>
            <expDate>1023</expDate>
            <extraDetails>
               <entry>
                  <key>cardCategory</key>
                  <value>Not Available</value>
               </entry>
               <entry>
                  <key>rememberMe</key>
                  <value>false</value>
               </entry>
            </extraDetails>
            <issuerBank>SERVIRED MASTERCARD INTERNACIONAL</issuerBank>
            <issuerCountry>ES</issuerCountry>
         </paymentDetails>
         <paymentMethod>19900</paymentMethod>
         <paymentSolution>caixapucpuce</paymentSolution>
         <status>SUCCESS</status>
         <respCode>
            <code>0000</code>
            <message>Successful</message>
            <uuid>dd04d570_bf82_4b9b_baf6_6ec123601521</uuid>
         </respCode>
         <authCode>075909</authCode>
         <mpi>
            <eci>05</eci>
         </mpi>
         <paymentCode>000</paymentCode>
         <paymentMessage>Operación finalizada con éxito</paymentMessage>
         <subscriptionPlan>708120533554282</subscriptionPlan>
      </operation>
   </operations>
   <optionalTransactionParams />
   <status>SUCCESS</status>
   <workFlowResponse>
      <id>31380</id>
      <name>debit creditcards (TRA)</name>
      <version>0</version>
   </workFlowResponse>
</payfrex-response>

    Payouts

    Los payouts son una operativa de pagos del comercio a la cuenta del cliente. No confundir con devoluciones. El objetivo de esta operativa es el pago de premios, por ejemplo. Debes solicitar esta operativa a Soporte para su activación.

    La petición es muy parecida a la de una autorización normal, pero con «operationType: credit». El tipo de Payout depende del flujo que tenga activo tu comercio, no se puede elegir el tipo de Payout (directo o en 2 pasos) con los parámetros de la petición. Existen 2 tipos de Payouts:

    • Payout directo: El cliente recibe el importe cuando la petición se completa con éxito.
    • Payout en 2 fases: El cliente inicia el proceso del Payout pero este queda pendiente de ser aprobado o rechazado por el comercio.

    Además, por seguridad, para realizar un Payout debe existir un pago autorizado previo (del cliente al comercio). El Payout se realizará con la misma solución de pago y a la misma tarjeta con la que se hizo el pago previo. Sin embargo, hay excepciones donde se puede realizar un Payout sin depósito previo, según la naturaleza del comercio.

    Petición

    Tu plataforma de comercio electrónico envía la petición Hosted de Payout al endpoint establecido. Tienes un ejemplo en cadena y cURL. Recuerda que la cadena debe pasar el proceso de cifrado.  

    				
					merchantId=12345&merchantTransactionId=00000001&amount=10&currency
=EUR&country=ES&customerId=000001&paymentSolution=creditcards&productId=123450001
&statusURL=https://micomercio.com/recepcion_notificacion.php
&successURL=https://micomercio.com2/url-ok.php&errorURL=https://micomercio.com/url-ko.php
&cancelURL=https://micomercio.com/url-cancelacion.php&awaitingURL=https://micomercio.com/url-espera.php
&cardNumberToken=4535954006730084&operationType=credit 
				
			
    				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 0Pn6pDEm73YvekNKUJcvwg==' \
--form 'merchantId="12345"' \
--form 'encrypted="YhkE2nrG1vmWRxNnMxWtbqDHsi/x1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzmL4o17lyYZds2eQ48hNGO8O8EmnDzTfveqZUASpII=”' \
--form 'integrityCheck="06c928531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

    Parámetros del Payout Hosted

    Los parámetros requeridos para un Payout en Hosted son los de esta tabla.

    Además, debes añadir o modificar los siguientes datos:

    CampoFormatoTipoDescripciónEjemplo
    operationTypeAlfanumérico
    Máx. 45 caracteres    		REspecifica el tipo de operación a realizar. Valores admitidos:
    – credit: Transacción de ingreso en cuenta del cliente. Es decir, el efectivo viaja desde el comercio hasta la cuenta del cliente. Por ejemplo, en el pago de un premio.     		credit
    cardNumberTokenAlfanumérico
    16~20 caracteres    		RToken de Addon Payments del número de tarjeta del cliente. Los últimos 4 dígitos coinciden con el número de tarjeta original.4535954006730084
    cardNumberNumérico
    Máximo 19 dígitos.    		O (R si no se envía el cardNumberToken)PAN de la tarjeta. Debe superar el algoritmo Luhn Check.4907270002222227
    expDateNumérico
    4 dígitos
    Formato MMAA, los meses son MM y AA el año.     		O (R si no se envía el cardNumberToken)Fecha de caducidad de la tarjeta.0623
    cvnNumberNumérico
    3 a 4 dígitos.    		O (R si no se envía el cardNumberToken)CVC de la tarjeta.123
    chNameAlfanumérico
    Máx. 100 caracteres    		O (R si no se envía el cardNumberToken)Nombre completo del titular de la tarjeta.
    Los nombres y apellidos se separan con espacios.
    Soporta UTF-8.    		Pablo Ferrer

    Respuesta

    Este es un ejemplo de la notificación que obtienes de una transacción Payout:

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

    Aprobar y rechazar Payout

    Si el flujo de tu comercio así lo indica, los Payouts se quedarán en status «PENDING» to «CREDIT» hasta que se aprueben o rechacen. Consulta la documentación Host2Host para realizar esta operativa.

    Personalización

    En la integración Hosted, es posible modificar el aspecto del formulario de varias formas. Consulta la guía de Personalización de la experiencia de pago para aprender cómo.

    Próximos pasos

    Llegados a este punto, esperamos que hayas podido integrar exitosamente vía Hosted. Consulta el resto de guías para conseguir una integración completa:

    Comparte este documento
    Tabla de Contenidos

    Cyberpac

    Consulta la documentación de Cyberpac. Aquí tienes las distintas secciones:

    Canales

    Módulos de integración

    Integraciones a medida

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

    Comienza a integrar

    undraw_add_to_cart_re_wrdo 1 (1) (1)

    Plugins para CMS

    Complementa la integración

    SDKs

    Métodos de pago

    Herramientas

    Addon Payments

    Consulta la documentación de Addon Payments. Aquí tienes las distintas secciones:

    Integraciones

    Consultas frecuentes

    Portal Backoffice

    Pagos integrados en TPV

    Crea una solución que te ayudará a automatizar procesos. Incluso, podrás agregar procesos de pago en terminales físicos.

    Pago integrado con TPV Android

    Pago integrado con Smartphone TPV

    Fichas Técnicas TPVs