Paso 1: Crear una sesión
Como primer paso, cree una sesión enviando una solicitud Create Session al motor de pagos desde su servidor web. La operación devuelve un ID de sesión que puede utilizar para hacer referencia a esta sesión.
Referencia de API de Create Session[REST][NVP]
Paso 2: Inicio del acuerdo de facturación
Proporcione los siguientes campos en la solicitud de Tokenize Browser Payment para iniciar un acuerdo de facturación y personalizar la experiencia del pagador que PayPal presenta.
token: el token que desea crear o actualizar. Los detalles del acuerdo se almacenan sobre este token.
Solo es necesario que rellene este campo si está configurado para la estrategia de generación de tokens "Proporcionado por el negocio". De lo contrario, el motor de pagos crea el token automáticamente.
sourceOfFunds.type = PAYPALsession.id: el identificador de la sesión de pago (devuelto en el Paso 1) que se actualizará con el token que contiene los detalles del acuerdo.sourceOfFunds.provided.paypal.billingAgreement.description: su descripción para el acuerdo de facturación de PayPal. Esta descripción se muestra al pagador cuando se le pide que apruebe el acuerdo de facturación.sourceOfFunds.provided.paypal.billingAgreement.name: su nombre para el acuerdo de facturación de PayPal.sourceOfFunds.provided.paypal.billingAgreement.cardinality: indica el número de acuerdos de facturación entre usted y este pagador. Puede configurar esto en:
MULTIPLE: indica que tiene múltiples acuerdos de facturación con este pagador. Esto significa que se devolverá un nuevo acuerdo en respuesta a cada solicitud.SINGLE: indica que tiene un solo acuerdo de facturación con este pagador. Esto significa que se devolverá el mismo acuerdo en respuesta a cada solicitud.
browserPayment.returnUrl: la URL a la que se desea redirigir el explorador del pagador tras la aprobación del acuerdo de facturación en PayPal.browserPayment.paypal.agreementConfirmation: indica la acción que PayPal muestra al pagador antes de ser redirigido de vuelta a su sitio web. Puede configurar esto en:
AGREE: se muestra como "Aceptar y continuar" en el sitio web de PayPal. Esto significa que, después de que el pagador haya aprobado el acuerdo de facturación y el explorador de este se haya devuelto a su sitio web, usted no procesará un pago sobre este acuerdo de facturación en ese momento.AGREE_AND_PAY: se muestra como "Aceptar y pagar" en el sitio web de PayPal. Esto significa que, después de que el pagador haya aprobado el acuerdo de facturación y el explorador de este se haya devuelto a su sitio web, usted procesará un pago sobre este acuerdo de facturación.
browserPayment.paypal.displayShippingAddress: indica si se desea que PayPal muestre la dirección de envío al pagador en el sitio Web de PayPal. Se puede establecer como "true" o "false".
De forma predeterminada, se muestra la dirección de envío al pagador. Para obtener más información, consulte Mostrar/Anular dirección de envío.browserPayment.paypal.overrideShippingAddress: indica si se desea permitir al pagador cambiar la dirección de envío para el pago en el sitio Web de PayPal. Se puede establecer como "true" o "false".
De forma predeterminada, se permite al pagador cambiar la dirección de envío. Para obtener más información, consulte Mostrar/Anular dirección de envío.
Después de enviar esta solicitud, debe redirigir el explorador del pagador a la URL devuelta en el campo browserPayment.redirectUrl.
Referencia de API de Tokenize Browser Payment [REST][NVP]
Solicitud de ejemplo
A continuación se ofrece un ejemplo de una solicitud Tokenize Browser Payment, en la que el token se ha generado usando la estrategia de generación de token "Proporcionado por el negocio".
| URL |
https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}
|
| Método HTTP |
POST |
{
"apiOperation": "TOKENIZE_BROWSER_PAYMENT",
"browserPayment": {
"paypal": {
"agreementConfirmation": "AGREE_AND_PAY",
"displayShippingAddress": true,
"overrideShippingAddress": false
},
"returnUrl": "https://<return_url>"
},
"correlationId": "f4d8b752-4f68-47c6-81e7-2ee488f821a0",
"session": {
"id": "SESSION0002567768179L82204264I7"
},
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<post_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"firstName": "<merchant_first_name>",
"lastName": "<merchant_last_name>"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"billingAgreement": {
"description": "Test Billing Agreement",
"name": "Test Name",
"cardinality": "MULTIPLE"
}
}
},
"type": "PAYPAL"
},
"token": "975890899756"
}
Respuesta de ejemplo
{
"browserPayment": {
"redirectUrl": "https://<redirect_url>"
},
"correlationId": "f4d8b752-4f68-47c6-81e7-2ee488f821a0",
"merchant": "<test_merchant_Id>",
"response": {
"gatewayCode": "NO_VERIFICATION_PERFORMED"
},
"result": "SUCCESS",
"session": {
"id": "SESSION0002567768179L82204264I7"
}
}
Recuperar detalles de la sesión
El token, ya sea generado por el motor de pagos o proporcionado por usted en la solicitud Tokenize Browser Payment, se almacena en una sesión de pago y se devuelve en la respuesta Tokenize Browser Payment.
Si está configurado para tokens generados por el motor de pagos, envíe una solicitud Retrieve Session inmediatamente usando el session.id y obtenga el valor devuelto en el campo sourceOfFunds.token. Si el pagador no pudo configurar el acuerdo de facturación correctamente, el token no se devuelve.
Si está configurado para tokens proporcionados por negocios, vaya al Paso 3: Recuperar detalles del acuerdo de facturación.
Ejemplo de solicitud de Retrieve Session
A continuación, se muestra un ejemplo de una solicitud de Retrieve Session para un ID de sesión obtenido de la respuesta de Tokenize Browser Payment donde el token lo generó el motor de pagos.
| URL |
https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session/{sessionId}
|
| Método HTTP |
GET |
Ejemplo de una respuesta de Retrieve Session
{
"merchant": "<test_merchant>",
"session": {
"id": "SESSION0002567768179L82204264I7",
"updateStatus": "SUCCESS",
"version": "82cbc9f602"
},
"sourceOfFunds": {
"token": "975890899756"
},
"version": "72"
}
Personalizando su acuerdo de facturación en PayPal
Para personalizar la experiencia del pagador en PayPal, puede proporcionar parámetros adicionales al configurar el acuerdo en PayPal.
- Nombre del acuerdo
- Descripción del acuerdo
- Datos personalizados del negocio: datos de acuerdos específicos del negocio.
- Omitir dirección de envío: si se establece como true, no se obtiene del pagador la dirección de envío durante la aprobación del acuerdo.
- Dirección de envío inmutable: si se establece en true, la dirección de envío se mostrará pero no se podrá editar.
- Incluir dirección de envío: se debe permitir al pagador proporcionar una dirección de envío si es diferente de la dirección predeterminada.
Asegúrese de que los campos de la dirección de envío en la solicitud de Tokenize Browser Payment y de que el acuerdo de facturación de PayPal se haya establecido para crear la experiencia de pagador deseada durante la aprobación del acuerdo de facturación.
Paso 3: Recuperar detalles del acuerdo de facturación
Antes de continuar con un pago sobre el acuerdo de facturación, debe comprobar si el token que contiene los detalles del acuerdo es válido. Esto se debe a que el pagador puede optar por cancelar el acuerdo de facturación en el sitio web de PayPal, en cuyo caso el estado del token dejará de ser válido. Continuar con un pago utilizando un token no válido hará que la transacción falle.
Cuando el pagador haya regresado a la página especificada por browserPayment.returnUrl, puede enviar una solicitud Retrieve Token. Debe proporcionar el ID del token para recuperar los detalles del acuerdo de facturación. Se devuelven los siguientes detalles si el pagador se suscribió correctamente para el acuerdo de facturación. De lo contrario, se devuelve el error "token no encontrado".
sourceOfFunds.provided.paypal.billingAgreement.cardinalitysourceOfFunds.provided.paypal.billingAgreement.descriptionsourceOfFunds.provided.paypal.billingAgreement.idsourceOfFunds.provided.paypal.billingAgreement.namesourceOfFunds.provided.paypal.payerIdsourceOfFunds.provided.paypal.accountEmailsourceOfFunds.provided.paypal.accountHolder
Ejemplo de una solicitud de Retrieve Token
A continuación, se muestra un ejemplo de una solicitud de Retrieve Token para un ID de token obtenido de la respuesta de Retrieve Session o según lo que usted haya facilitado en la solicitud Tokenize Browser Payment.
| URL |
https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/token/{tokenId}
|
| Método HTTP |
GET |
Ejemplo de una respuesta de Retrieve Token
{
"repositoryId": "TEST8108F6CF-6899-42",
"result": "SUCCESS",
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<pos_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"firstName": "<merchant_first_name>",
"lastName": "<merchant_last_name>"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "test@test.com",
"accountHolder": "FirtName LastName",
"billingAgreement": {
"cardinality": "MULTIPLE",
"description": "Test Billing Agreement",
"id": "B-NGxIf31554266975867",
"name": "Test Name"
},
"payerId": "K4ZK9KRAXRVNA"
}
},
"type": "PAYPAL"
},
"status": "VALID",
"token": "975890899756",
"usage": {
"lastUpdated": "2019-04-03T04:49:48.029Z",
"lastUpdatedBy": "<test_merchant>",
"lastUsed": "2019-04-03T04:49:48.029Z"
},
"verificationStrategy": "NONE"
}
Paso 4: Inicio de un pago sobre el acuerdo de facturación
Si el acuerdo de facturación está aprobado y es válido, se debe iniciar un pago inmediatamente sobre el acuerdo de facturación si establece browserPayment.paypal.agreementConfirmation=AGREE_AND_PAY en la solicitud de Tokenize Browser Payment.
Proporcione los siguientes campos en una solicitud Pay, además de los campos estándar.
sourceOfFunds.type = PAYPALsourceOfFunds.token: proporcione el ID de token que identifica los detalles del acuerdo de facturación (recibidos de PayPal) en el motor de pagos. Puede utilizar este ID de token para los pagos únicos y recurrentes.
Puede ver los detalles del acuerdo de facturación para una transacción Authorize o Pay al realizar una transacción Retrieve Transaction o a través de Merchant Administration.
Solicitud Pay de ejemplo
A continuación, se muestra un ejemplo de una solicitud de transacción Pay mediante el token que identifica los detalles del acuerdo de facturación con PayPal.
| URL |
https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
|
| Método HTTP |
PUT |
{
"apiOperation": "PAY",
"order": {
"amount": "123.46",
"currency": "USD",
"description": "Quantity description",
"item": [
{
"name": "name",
"quantity": "40",
"sku": "sku",
"unitPrice": "2.8"
}
],
"itemAmount": "112.00",
"tax": [
{
"amount": "0.29",
"rate": "9.77"
}
],
"taxAmount": "11.46"
},
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<pos_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"email": "test@test.com",
"firstName": "FirstName"
}
},
"sourceOfFunds": {
"token": "975890899756"
}
}
