Token de Uso Recurrente

El cliente recibe un CommerceToken después de registrar su tarjeta, la cual puede ser utilizada para futuras transacciones. A continuación, se encuentran los pasos para comprar como un usuario registrado en el sitio web.

Crear un Cliente

El primer paso es crear el cliente en Bamboo Payment. Para esto, debe invocar un request POST a las siguientes URL de acuerdo con sus necesidades.

• Producción: https://api.bamboopayment.com/v1/api/customer
• Stage: https://api.stage.bamboopayment.com/v1/api/customer

Parámetros del Request

Ejemplo del Request

{
    "Email": "kristeldyoder@teleworm.us",
    "FirstName": "Kristel",
    "LastName": "Yoder",
    "DocNumber": "31130749",
    "DocumentTypeId": 2,
    "Owner": "Commerce",
    "PhoneNumber": "093000000",
    "BillingAddress": {
        "AddressType": 1,
        "Country": "Uruguay",
        "State": "Montevideo",
        "City": "Montevideo",
        "AddressDetail": "100"
    }
}

Parámetros del Response

El objeto de respuesta retorna la información del cliente recién creado o el error que se haya podido producir. En el parámetro Response.CustomerId se encuentra el identificador de cliente generado por la API para poder consultarlo o actualizarlo.

Utilice los siguientes parámetros para realizar operaciones adicionales sobre los clientes:

• CaptureURL: URL de captura de datos de la tarjeta. Abra esta URL en un iframe para iniciar la captura de datos sensibles. Para más información, consulte Invocando el formulario de inscripción de tarjeta.
• UniqueID: Identificador único temporal utilizado para registrar métodos de pago externos. Cada vez que se solicita la información del Cliente, se obtiene un nuevo identificador. Para más información, consulte Invocando el formulario de inscripción de tarjeta.
• URL: URL en la que se puede consultar la información de un cliente. Para más información, consulte Obtener un cliente.

Ejemplo del Response

{
    "Response": {
        "CustomerId": 249205,
        "Created": "2023-08-22T11:26:53.343",
        "CommerceCustomerId": null,
        "Owner": "Commerce",
        "Email": "kristeldyoder@teleworm.us",
        "Enabled": true,
        "ShippingAddress": null,
        "BillingAddress": {
            "AddressId": 373151,
            "AddressType": 1,
            "Country": "Uruguay",
            "State": "Montevideo",
            "AddressDetail": "100",
            "PostalCode": null,
            "City": "Montevideo"
        },
        "Plans": null,
        "AdditionalData": null,
        "PaymentProfiles": [],
        "CaptureURL": "https://api.stage.bamboopayment.com/Capture/",
        "UniqueID": "UI_b53cb8db-771e-4622-a5db-0e58e156f192",
        "URL": "https://api.stage.bamboopayment.com/api/Customer/249205",
        "FirstName": "Kristel",
        "LastName": "Yoder",
        "DocNumber": "31130749",
        "DocumentTypeId": 2,
        "PhoneNumber": "093000000",
        "ExternalValue": null
    },
    "Errors": []
}

Operaciones sobre los clientes

Una vez haya creado un usuario, puede realizar operaciones para obtener o actualizar su información.

Obtener un cliente

Se puede obtener la información del cliente usando su ID o su dirección de correo electrónico.

Para esto, debe invocar un request GET a las siguientes URL de acuerdo con sus necesidades.

• Producción: https://api.bamboopayment.com/v1/api/customer
• Stage: https://api.stage.bamboopayment.com/v1/api/customer

En la respuesta, se obtiene una lista con el mismo objeto retornado en la creación del cliente. Ejemplo:

{
    "Response": [
        {
            "CustomerId": 249205,
            "Created": "2023-08-22T14:26:53.343",
            "CommerceCustomerId": null,
            "Owner": "Commerce",
            "Email": "kristeldyoder@teleworm.us",
            "Enabled": true,
            "ShippingAddress": null,
            "BillingAddress": {
                "AddressId": 373151,
                "AddressType": 1,
                "Country": "Uruguay",
                "State": "Montevideo",
                "AddressDetail": "100",
                "PostalCode": null,
                "City": "Montevideo"
            },
            "Plans": null,
            "AdditionalData": null,
            "PaymentProfiles": [],
            "CaptureURL": "https://api.stage.bamboopayment.com/Capture/",
            "UniqueID": "UI_61109a7f-5414-4424-8654-18c30060cd2b",
            "URL": "https://api.stage.bamboopayment.com/api/Customer/249205",
            "FirstName": "Kristel",
            "LastName": "Yoder",
            "DocNumber": "31130749",
            "DocumentTypeId": 2,
            "PhoneNumber": "093000000",
            "ExternalValue": null
        }
    ],
    "Errors": []
}

Actualizar un cliente

Para actualizar la información de un cliente, debe invocar un request POST a las siguientes URL de acuerdo con sus necesidades.

• Producción: https://api.bamboopayment.com/v1/api/customer/{{{{customer-id}}}}/update
• Stage: https://api.stage.bamboopayment.com/v1/api/customer/{{customer-id}}/update

Donde {{customer-id}} es el id generado cuando se creó el usuario. En el cuerpo del request los parámetros que quiera actualizar.

En la respuesta, se obtiene el mismo objeto retornado en la creación del cliente.

Capturar la información de la tarjeta

El siguiente paso es obtener el token de la tarjeta del cliente. Para esto, puede invocar el formulario de inscripción de tarjeta o utilizar la Tokenización Directa si su comercio cumple con la normativa PCI.

Invocando el formulario de inscripción de tarjeta

El siguiente diagrama de secuencia explica el flujo de inscripción de tarjetas.

Llamadas API durante el flujo:

• 3 HTTP/GET (server to server): {environment_api}/v1/api/customer/{customer-id}
• 11 HTTP/GET (server to server): {environment_api}/v1/api/customer/{customer-id}

Con la información obtenida en el paso anterior, puede invocar los métodos OpenIframeCustom o OpenIframeCustomWithPaymentMediaOptions (ver detalles más abajo) de la librería JavaScript PWCheckout, que gestionan la captura de datos de la tarjeta.

OpenIframeCustom

El método OpenIframeCustom recibe dos parámetros:

• URL: La URL especifica la dirección del iFrame donde los clientes introducen los datos de la Tarjeta.
  La URL se crea concatenando los datos recibidos de la siguiente manera: {CaptureURL}?key={publicKey}&session_id={UniqueID} donde {CaptureURL} representa la URL base + /Capture. Por ejemplo https://api.stage.bamboopayment.com/v1/Capture.
  Puede encontrar esta información en el parámetro CaptureURL del response.
• UniqueID: un identificador para distinguir la sesión de captura de datos. Puede encontrar esta información en el parámetro CaptureURL del response.

<script type="text/javascript">
        PWCheckout.OpenIframeCustom(url, UniqueID);
</script>

OpenIframeCustomWithPaymentMediaOptions

El método OpenIframeCustomWithPaymentMediaOptions recibe cuatro parámetros:

• URL: Igual que en OpenIframeCustom.
• UniqueID: Igual que en OpenIframeCustom.
• PaymentMediaid: Identificador del Medio de pago. Si se envía, el Formulario de Captura de Tarjeta sólo aceptará tarjetas de este medio de pago. Este parámetro sólo aplica para Uruguay.
• BankId: Identificador del banco. Este parámetro sólo aplica para Uruguay.

Si se envían ambos parámetros, el Formulario de Captura de Tarjeta sólo aceptará tarjetas del Medio de pago y Banco especificados, pero son opcionales.

Ejemplos de llamadas al método OpenIframeCustomWithPaymentMediaOptions:

1. Llamada con PaymentMediaId y BankId enviados:

<script type="text/javascript">
      PWCheckout.Iframe.OpenIframeCustomWithPaymentMediaOptions(url, UniqueID, paymentMediaId,bankId);
</script>

2. Llamada con PaymentMediaId y BankId vacíos:

<script type="text/javascript">
      PWCheckout.Iframe.OpenIframeCustomWithPaymentMediaOptions(url, UniqueID, null, null);
</script>

El cliente ingresa los datos de la tarjeta y, tras confirmar, la librería PWCheckout recibe la notificación de que la tarjeta se ha capturado correctamente.

La página del comercio puede suscribirse al evento tokenCreated que se disparará al recibir la notificación de que los datos de la tarjeta fueron capturados.

La página también puede configurar la propiedad form_id (utilizando el método SetProperties) para enviar el identificador del formulario en la página que será controlada por la librería PWCheckout. La librería enviará el formulario una vez capturada la información de la tarjeta.

En respuesta a la notificación recibida (por el evento JavaScript o por el envío del formulario), la página del comercio debe volver a solicitar la información actualizada del cliente realizando la siguiente llamada HTTP/GET (server to server): {environment_api}/v1/api/customer/{customer-id}.

El objeto Customer retornado contiene los PaymentProfiles del cliente. Estos objetos tienen información sobre los medios de pago asociados al cliente, donde en los campos Token y CommerceToken representan la tarjeta de pago.

Ejemplo de respuesta que incluye un PaymentProfile:

{
  "Response": {
    "CustomerId": 53479,
    "Created": "2021-04-06T16:08:43.767",
    "CommerceCustomerId": null,
    "Owner": "Commerce",
    "Email": "Email222222@mail.com",
    "Enabled": true,
    "ShippingAddress": null,
    "BillingAddress": {
      "AddressId": 51615,
      "AddressType": 1,
      "Country": "UY",
      "State": "Montevideo",
      "AddressDetail": "10000",
      "PostalCode": null,
      "City": "MONTEVIDEO"
    },
    "Plans": null,
    "AdditionalData": null,
    "PaymentProfiles": [
      {
        "PaymentProfileId": 55591,
        "PaymentMediaId": 2,
        "Created": "2021-04-19T11:26:17.693",
        "LastUpdate": null,
        "Brand": "MasterCard",
        "CardOwner": "John Simpson",
        "Bin": null,
        "IssuerBank": "Santander",
        "Installments": "1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24",
        "Type": "CreditCard",
        "Token": "OT__wZcNQkcZtnYWeHIgR2vgWUUliS3lR18E4jiYpVJ8SzQ_",
        "Expiration": "202211",
        "Last4": "0001",
        "Enabled": true
      }
    ],
    "CaptureURL": "https://testapi.BambooPayment.com/v1/Capture/",
    "UniqueID": "UI_263b2dde-b151-4f09-b8bf-c65883d2cb3b",
    "URL": "https://testapi.BambooPayment.com/v1/api/Customer/53479",
    "FirstName": "FistName 2222",
    "LastName": "LastName 2222",
    "DocNumber": "12345672",
    "DocumentTypeId": 2,
    "PhoneNumber": "24022330"
  },
  "Errors": []
}

Utilizando la Tokenización Directa

Como el usuario está registrado en su comercio, debe invocar el método para crear el token para usuarios registrados.

Crear una Compra Básica

Debe enviar el token recién obtenido desde el navegador o la aplicación móvil al servidor de aplicaciones para crear la transacción de compra.

Desde el servidor, invoque el método Crear una Compra, incluyendo el objeto Purchase con el token y los datos de la transacción adicionales.

{
  "TrxToken": "CT_kYv0qTHckRiZ4wjCz5NguZRuwFLSIrQc4jiYpVJ8SzQ_",
  "Order": "17030613595101621fb",
  "Amount": 123456,
  "Currency": "USD",
  "Capture": true,
  "TargetCountryISO":"CL",
  "PaymentMediaId":106
}

Los campos PaymentMediaId y TrxToken son opcionales, pero es obligatorio enviar uno dependiendo del flujo que quiere utilizar.

• PaymentMediaId: Identificador de medio de pago alternativo (transferencia, efectivo y procesamiento que requiere redirección del cliente). Puede obtener este identificador consultando la sección Medios de pago por país.

• TrxToken: Puede generar el token y transaccionar enviándolo en este campo.

Compras recurrentes en un clic

Después de que los clientes se registren correctamente, algunas tarjetas permiten ciertas transacciones sin necesidad de un Código de Verificación (CVV), lo que permite una experiencia de usuario más ágil (pagos en un solo clic). En estos casos, las compras se pueden enviar directamente sin solicitar más información al cliente, como se explica en el punto anterior, Compra básica.

Debe solicitar el Código de Verificación cada vez que realice transacciones en las que la tarjeta no permita esta función, ya que no podemos almacenarlo en nuestros servidores.

Flujo de Solicitud de Código de Verificación

Para las Tarjetas que requieren ingresar del Código de Verificación en todas las transacciones, hemos diseñado el siguiente flujo de trabajo:

1. El cliente, identificado correctamente en la web de Comercio, inicia el proceso de pago de una compra utilizando una tarjeta previamente registrada y asociada a su cuenta.

2. La página del Comercio envía los datos al web server para preparar la información enviada a Bamboo Payment.

3. El Web Server del comercio envía la compra a través de la API de Bamboo Payment, identificando el CommerceToken como el medio de pago que el cliente seleccionó.

4. Realizamos una serie de validaciones; en este caso, verificamos si el medio de pago elegido permite la ejecución de transacciones sin el Código de Verificación. El Medio de pago seleccionado no permite esta funcionalidad en este flujo, por lo que la transacción sólo podrá completarse una vez haya obtenido el Código de Verificación de la tarjeta.

5. Retornamos el objeto Purchase en estado Pending (pendiente) como respuesta, indicando que es necesaria alguna acción para completar el proceso. El objeto Purchase devuelto también contiene el objeto CommerceAction que describe los pasos necesarios que debe realizar el comercio.

El comercio debe almacenar la información de la compra pendiente (al menos el PurchaseId para futuras validaciones) y procesar la información del CommerceAction para determinar la acción requerida. Tenga en cuenta las siguientes propiedades en este escenario:

ActionReason: Tiene el valor VERIFICATION_CODE_NEED ya que la compra requiere este Código de Verificación.

• ActionType: Este campo tiene el valor 2 correspondiente a la acción PWCapture, que es una función del componente javascript PWCheckout que permite procesar este tipo de acciones.
• ActionURL: Este campo especifica la URL que debe enviar como parámetro al método PWCapture del componente PWCheckout.

6. La página web del comercio debe mostrar el formulario de solicitud de Código de Verificación al cliente utilizando el método PWCapture de la siguiente forma:

<script type="text/javascript">
  PWCheckout.PWCapture(url);
</script>

Donde el valor del parámetro url corresponde al campo ActionURL del objeto CommerceAction recibido.

7. El cliente ve el iframe con el Formulario de Captura, que en este caso se presenta mostrando el número de tarjeta enmascarado (sólo los cuatro últimos dígitos) y un campo de texto para ingresar el Código de Verificación.

8. El cliente ingresa el Código de Verificación de la tarjeta utilizada para realizar la compra.

9. El código de verificación que ingresa el cliente se envía directamente a los servidores de Bamboo Payment, donde se utiliza para crear el mensaje de autorización.

10. Bamboo Payment envía el mensaje de autorización a la entidad adquirente correspondiente con los datos completos.

11. Bamboo Payment procesa la respuesta del adquirente y actualiza el estado de la compra de acuerdo con dicha respuesta.

12. Bamboo Payment genera una notificación al comercio, informando el objeto Purchase y de su estado final determinado por el proceso de autorización. La Purchase enviada es la misma previamente respondida en el paso 5, el comercio debe validar la información recibida (al menos que el PurchaseId coincide con el esperado). Esta notificación se envía al servicio de WebHook que el comercio debe implementar para obtener las diferentes notificaciones generadas por Bamboo Payment.

Alternativa de Notificación

Además de la opción de recibir una notificación desde Bamboo Payment al finalizar el proceso de compra (paso 12 del flujo normal), se puede ejecutar un flujo alternativo para consultar explícitamente el resultado de la compra una vez detectado que el proceso pendiente ha finalizado (tras el paso 5).

Este flujo utiliza las funcionalidades implementadas en la librería JavaScript PWCheckout para informar de la finalización del proceso de compra pendiente.

A continuación se enumeran y se explican los pasos relacionados con este flujo; las etapas iniciales antes del paso 12 son las mismas que las descritas anteriormente.

12. Una vez finalizado el proceso pendiente, la librería PWCheckout recibe una notificación del estado del proceso.

13. La librería PWCheckout lanza el evento notificationReceived event. El comercio debe suscribirse previamente al evento a través del método Bind de la siguiente manera:

<script type="text/javascript"> 
  PWCheckout.Bind("notificationReceived", NotificationHandler);
</script>

El comercio debe implementar la función NotificationHandler (el nombre es sólo un ejemplo), que recibirá la información sobre el estado final del proceso.

Ejemplo de la función para el manejo de notificaciones:

<script type="text/javascript">
    function NotificationHandler(notification) {
        if (notification.ProcessStatus == 1) {
            //Proceso OK
        } else {
            //Proceso con errores
        }
    }
</script>

El campo ProcessStatus de la notificación recibida determina el estado final del proceso. Los posibles valores son:

OK (valor 1) - El proceso ha finalizado correctamente.

• Pending (valor 2) - El proceso sigue pendiente.
• Error (valor 3) - El proceso finalizó con error.

14. Después de que la página web reciba el evento notificationReceived, puede continuar con el flujo.

15. El comercio debe invocar una llamada GET desde el servidor web a la API de Compras de Bamboo Payment, consultando el PurchaseId almacenado previamente en el paso 5.

Para esto, se realiza la llamada: HTTP/GET (server to server):

{environment_api}/v1/api/purchase/{purchase-id}

16. La respuesta de Bamboo Payment contiene el objeto Purchase con un estado distinto de Pending (dependiendo del resultado de la transacción), por lo que puede procesarse como una respuesta de compra normal.

Para esto, se realiza la llamada: HTTP/POST (server to server):

{environment_api}/v1/api/purchase

Última modificación 18 de noviembre de 2024

© Bamboo | All rights reserved 2024