- Pautas de integración
- Características soportadas (operaciones de pago)
- Soporte del agregador
Soporte del agregador
El Mastercard Gateway ofrece soporte para que usted actúe como un agregador. Esto le permite ofrecer servicios en línea para aceptar pagos electrónicos a otros negocios (llamados subnegocios), donde no sea necesario que el subnegocio tenga una relación contractual ni con el adquirente ni con el motor de pagos. Esta es una opción atractiva para negocios con un bajo número de transacciones para aceptar pagos en línea de sus pagadores y configurarse muy rápidamente.
El subnegocio solo necesita un acuerdo contractual con usted, el agregador. Usted administra la relación contractual con el adquirente, recibe los fondos del subnegocio y liquida estos hacia el subnegocio.
- La funcionalidad de agregador es compatible con DirectAPI versión 32 y posteriores.
- Los esquemas de tarjetas tienen ciertos requisitos que usted debe cumplir si quiere actuar como agregador. Para conocer los detalles, póngase en contacto con su adquirente y/o con los esquemas de tarjetas.
- American Express requiere el correo electrónico y el número de teléfono del agregador de pagos, además de otros detalles del subnegocio.
Prerrequisitos
Debe contactar a su adquirente, que lo registrará a usted con los esquemas de tarjetas para el propósito de establecerle como agregador. Su adquirente podría emitirle un identificador y/o nombre de agregador. Proporcione estos detalles a your payment service provider.
Your payment service provider debe configurar su perfil de negocio (vínculo de adquirente del negocio) en el motor de pagos, como corresponde.
Envío de transacciones de DirectAPI para subnegocios
Al enviar una transacción para un subnegocio a través de las siguientes operaciones de DirectAPI, puede proporcionar los detalles del subnegocio que se indican a continuación en el grupo de parámetros de order.subMerchant.
Solicitudes de DirectAPI:
PAYAUTHORIZE- Standalone
CAPTURE - Standalone
REFUND VERIFYUPDATE_SESSION
Detalles de subnegocio:
order.subMerchant.identifier(obligatorio si se proporcionaorder.subMerchant.tradingName)order.subMerchant.registeredNameorder.subMerchant.tradingName(obligatorio si se proporcionaorder.subMerchant.identifier)order.subMerchant.bankIndustryCode- Campos
order.subMerchant.address.* order.subMerchant.phoneorder.subMerchant.email
Si se proporciona, estos se devolverán en las siguientes respuestas:
RETRIEVE_TRANSACTIONRETRIEVE_ORDERRETRIEVE_SESSION
Si el motor de pagos no ofrece soporte para agregadores para su adquirente, una solicitud con los detalles del subnegocio será rechazada.
Los detalles del subnegocio se aplican a todas las transacciones de un pedido. Solo se pueden proporcionar en las transacciones iniciales, es decir, transacciones que crean un pedido. Si se proporciona en transacciones posteriores (es decir, transacciones para un pedido existente, como una solicitud subsiguiente de CAPTURE o REFUND), el motor de pagos rechaza la solicitud.
Tokenization
Para versiones de API inferiores a la 70, si usted actúa como agregador, no puede usar la funcionalidad de Tokenization. El motor de pagos rechaza las solicitudes de transacciones con detalles de subnegocios para los negocios que están habilitados para Tokenization.
A partir de la versión 70 de la API, si usted actúa como agregador, puede utilizar la funcionalidad de Tokenization. La compatibilidad para la funcionalidad de Tokenization se agrega a las siguientes operaciones:
Solicitud:
TOKENIZECreate or Update TokenCreate or Update Token (system generated token)
DELETE_TOKENSEARCH_TOKEN, andRETRIEVE_TOKEN.
Repuesta:
TOKENIZECreate or Update TokenCreate or Update Token (system generated token)
TOKENIZE_BROWSER_PAYMENT, andRETRIEVE_TOKEN.
Como agregador que usa la funcionalidad de Tokenization, debe proporcionar los siguientes detalles del subnegocio en el grupo de parámetros subMerchant.
subMerchantsubMerchant.identifier
Como negocio agregador, se espera que usted:
- proporcione el identificador del subnegocio en todas las operaciones de tokenización;
- proporcione los detalles del subnegocio en las solicitudes de transacción;
- esté habilitado como agregador; y
- utilice un vínculo de adquirente que admita transacciones de agregador (la capacidad de soporte de agregador debe estar habilitada en el vínculo de adquirente).
Limitaciones
Las siguientes funcionalidades no están disponibles actualmente:
- No se puede configurar un agregador con un depósito con la estrategia de generación de tokens = adquirente.
- No se puede configurar un agregador con un depósito de tokens externo (tokenprovider = LTV o TV2G).
- No se puede configurar un agregador con tokenización de red para tokens del motor de pagos.
Hosted Checkout
Si desea proporcionarles a sus subnegocios la funcionalidad de Hosted Checkout, debe ofrecerles una interfaz para su integración con Hosted Checkout.
Si usted proporciona los detalles del subnegocio, debe ofrecer un ID de sesión cuando llame a Checkout.configure(). Envíe una solicitud DirectAPICREATE_CHECKOUT_SESSION e incluya los detalles del pedido del subnegocio para generar una ID de sesión. El explorador del pagador será devuelto a su aplicación y usted debe redirigir al pagador a la aplicación del subnegocio.
Use Checkout.configure() para proporcionar los detalles de visualización del subnegocio, tales como nombre del negocio, dirección, datos de contacto y logotipo. Estos detalles se presentan al pagador durante la interacción de Hosted Checkout.
Autenticación EMV 3-D Secure
Para permitir que los subnegocios utilicen la Autenticación EMV 3-D Secure (3DS2) por medio del motor de pagos, los agregadores deben enviar los detalles relevantes del subnegocio en la solicitud Initiate Authentication. Cuando los detalles del subnegocio se envían al motor de pagos, el motor de pagos los usa en lugar de los detalles del agregador en el mensaje de autenticación posterior. Los campos que deben proporcionarse varían según el esquema. Entre los esquemas admitidos se encuentran los siguientes:
- Mastercard SecureCode™
- Verified by Visa
- American Express SafeKey
- mada secure
Si la autenticación va seguida de un pago que utilice una operación Authorize o Pay que haga referencia al ID de autenticación 3DS2, los detalles del subnegocio proporcionados en la solicitud Initiate Authentication también se utilizarán en las operaciones Authorize/Pay.
Paso 1: Iniciar autenticación
Proporcione los siguientes detalles sobre la solicitud Initiate Authentication para su subnegocio, además de otros campos obligatorios que se enumeran en la sección Iniciar autenticación en la Guía de integración.
Para ver los campos de respuesta clave para la respuesta de Initiate Authentication, consulte la sección Iniciar autenticación en la Guía de integración.
Detalles de subnegocio
order.subMerchant.identifier(obligatorio para todos los esquemas 3DS2 compatibles)order.subMerchant.tradingName(obligatorio para todos los esquemas 3DS2 compatibles)order.subMerchant.bankIndustryCode(obligatorio para todos los esquemas 3DS2 compatibles)order.subMerchant.registeredNameorder.subMerchant.address.country(obligatorio para todos los esquemas 3DS2 compatibles)order.subMerchant.address.*(otros campos de dirección)order.subMerchant.phoneorder.subMerchant.email
Detalles de 3DS2
Proporcione los siguientes detalles de configuración de 3DS2 de su subnegocio. Como prerrequisito, debe estar habilitado para el esquema de autenticación 3DS2 respectivo en su perfil de negocio, para el cual el subnegocio puede realizar autenticaciones de pagador 3DS2.
order.subMerchant.websiteUrl: URL del sitio web del subnegocio. Si no se proporciona, se utilizará la URL del sitio web de su perfil del negocio.order.subMerchant.authentication[n].protocolorder.subMerchant.authentication[n].3DS2.requestorIdorder.subMerchant.authentication[n].3DS2.requestorName
Para Mastercard SecureCode, JCB J/Secure y mada secure, no proporcione detalles de autenticación. El motor de pagos genera el ID del solicitante y el nombre del solicitante.
Para Verified by Visa, en los detalles de autenticación solo debe proporcionar el protocolo de autenticación. El motor de pagos genera el ID del solicitante y el nombre del solicitante.
Para American Express SafeKey, el motor de pagos utilizará el ID de solicitante "AGG", que significa agregador. Si American Express lo solicita, puede anularlo y utilizar uno diferente. El motor de pagos, al igual que otros esquemas, creará el nombre del solicitante.
| URL | https://test-gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| Método HTTP | PUT |
{
"authentication": {
"acceptVersions":"3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION"
},
"correlationId": "test",
"order": {
"currency": "USD",
"subMerchant": {
"authentication":[
{
"protocol":"AMEX_SAFEKEY",
"3DS2":{
"requestorId":"testRequestorId",
"requestorName":"testRequestorName"
}
}
],
"identifier": "123456",
"tradingName": "SubmerchantName",
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"bankIndustryCode": "1234",
"registeredName": "SubmerchantRegisteredName"
}
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174"
}
}
},
"apiOperation": "INITIATE_AUTHENTICATION"
}
{
"authentication":
{
"3ds2": {
"directoryServerId": "A999999999",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"acceptVersions": "3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"customized": {
"3DS": {
"methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA2LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS8xYjZjMmNiYTc3NjMxZDBjNTAxOWM1YzUxMzZmM2ZjZWI4NDZiMGE4ZTFkZmM2Njg2YjA1YWNkZjQxMGZkMWEwIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJmYzBmNDg0OC03MzQzLTQzMDAtOTg2YS05NmQwYmE0MDM0ODUifQ==",
"methodUrl": "https://qa06.gateway.mastercard.com/acs/mastercard/v2/method"
}
}
},
"redirectHtml":"<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\"> </iframe> <form id=\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://qa06.gateway.mastercard.com/acs/mastercard/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA2LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS8xYjZjMmNiYTc3NjMxZDBjNTAxOWM1YzUxMzZmM2ZjZWI4NDZiMGE4ZTFkZmM2Njg2YjA1YWNkZjQxMGZkMWEwIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJmYzBmNDg0OC03MzQzLTQzMDAtOTg2YS05NmQwYmE0MDM0ODUifQ==\"/> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
"version": "3DS2"
},
"correlationId": "test",
"merchant": "TESTMITSUKO_GWS",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2022-03-03T02:21:20.043Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:21:19.966Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"authentication": [
{
"3DS2": {
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"protocol": "AMEX_SAFEKEY"
}
],
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:21:19.966Z",
"timeOfRecord": "2022-03-03T02:21:20.043Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "USD",
"id": "123",
"type": "AUTHENTICATION"
},
"version": "64"
}
Paso 2: Autenticar al pagador
Consulte Autenticar al pagador para conocer todas las instrucciones relacionadas con el flujo de subnegocios.
| URL | https://test-gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| Método HTTP | PUT |
{
"correlationId": "foo",
"order": {
"amount": "100",
"currency": "USD"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174",
"expiry": {
"month" : "01",
"year" : "39"
}
}
}
},
"device": {
"browser": "MOZILLA",
"browserDetails": {
"3DSecureChallengeWindowSize": "FULL_SCREEN",
"acceptHeaders": "application/json",
"colorDepth": 24,
"javaEnabled": true,
"language": "en-US",
"screenHeight": 640,
"screenWidth": 480,
"timeZone": 273
},
"ipAddress": "127.0.0.1"
},
"apiOperation": "AUTHENTICATE_PAYER"
}
{
"authentication": {
"3ds": {
"acsEci": "05",
"authenticationToken": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId": "AgEAAJZvNBiNg0EWkd6ryLVH8ik="
},
"3ds2": {
"3dsServerTransactionId": "fc0f4848-7343-4300-986a-96d0ba403485",
"acsTransactionId": "ebd1628f-b62a-44f6-bb2d-480359ac3e70",
"directoryServerId": "A999999999",
"dsTransactionId": "966f3418-8d83-4116-91de-abc8b547f229",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "testRequestorId",
"requestorName": "testRequestorName",
"transactionStatus": "Y"
},
"payerInteraction": "NOT_REQUIRED",
"redirect": {
"customized": {
"3DS": {
"acsUrl": "https://qa06.gateway.mastercard.com/callbackInterface/gateway/3a672661a6b7027834df3e5863e78f02152c7b99b18b0f9ea8bbd30f86323dc2",
"cReq": "e30="
}
},
"domainName": "qa06.gateway.mastercard.com"
},
"redirectHtml":"<div id=\"threedsFrictionLessRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"challengeFrame\" name=\"challengeFrame\" </iframe> <form id=\"threedsFrictionLessRedirectForm\" method=\"POST\" action=\"https://qa06.gateway.mastercard.com/acs/mastercard/v2/method\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"order.id\" value=\"TEST1234\"/> <input type=\"hidden\" name=\"transaction.id\" value=\"123\"/> input type=\"hidden\" name=\"response.gatewayRecommendation\" value=\"PROCEED\"/> <input type=\"hidden\" name=\"result\" value=\"SUCCESS\"/> </form> <script id=\"authenticate-payer-script\"> </script> var e=document.getElementById(\"threedsFrictionLessRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
"version": "3DS2"
},
"correlationId": "foo",
"device": {
"browser": "MOZILLA",
"ipAddress": "127.0.0.1"
},
"merchant": "TESTMITSUKO_GWS",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"creationTime": "2022-03-03T02:21:20.043Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:25:30.340Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"authentication": [
{
"3DS2": {
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"protocol": "AMEX_SAFEKEY"
}
],
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0,
"valueTransfer": {
"accountType": "NOT_A_TRANSFER"
}
},
"response": {
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:25:30.340Z",
"timeOfRecord": "2022-03-03T02:21:20.043Z",
"transaction": {
"acquirer": {
"merchantId": "1234567890"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"currency": "USD",
"id": "123",
"type": "AUTHENTICATION"
},
"version": "64"
}
Paso 3: Usar el resultado de la autenticación en una operación de pago
Consulte Usar el resultado de la autenticación en una operación de pago para conocer todas las instrucciones relacionadas con el flujo del subnegocio.
| URL | https://test-gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| Método HTTP | PUT |
{
"apiOperation": "AUTHORIZE",
"authentication": {
"transactionId": "123"
},
"order": {
"amount": "100",
"currency": "USD",
"reference": "300"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174",
"expiry": {
"month": "01",
"year": "39"
}
}
},
"type": "CARD"
},
"transaction": {
"source": "INTERNET",
"reference": "3600"
}
}
{
"authentication": {
"3ds": {
"acsEci": "05",
"authenticationToken": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId": "AgEAAJZvNBiNg0EWkd6ryLVH8ik="
},
"3ds2": {
"dsTransactionId": "966f3418-8d83-4116-91de-abc8b547f229",
"protocolVersion": "2.1.0",
"transactionStatus": "Y"
},
"transactionId": "123",
"version": "3DS2"
},
"authorizationResponse": {
"posData": "1605S0100130",
"transactionIdentifier": "AmexTidTest"
},
"device": {
"browser": "MOZILLA",
"ipAddress": "127.0.0.1"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTMITSUKO_GWS",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2022-03-03T02:21:19.948Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:45:56.851Z",
"merchantAmount": 100.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "USD",
"reference": "300",
"status": "AUTHORIZED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 100.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "000",
"acquirerMessage": "Approved ",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:45:56.851Z",
"timeOfRecord": "2022-03-03T02:45:56.762Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "AMEXGWS",
"merchantId": "1234567890"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"authorizationCode": "007257",
"currency": "USD",
"id": "1234",
"receipt": "2203031",
"reference": "3600",
"source": "INTERNET",
"stan": "1",
"terminal": "123456",
"type": "AUTHORIZATION"
},
"version": "64"
}