Guardado y uso de tarjetas

En esta guía se explican las distintas maneras en las que podemos almacenar una tarjeta (tokenizarla) y de que formas podemos luego recuperarla y utilizarla.

Cuando hablamos de tokenización, nos estamos refiriendo a la acción de guardar un método de pago para su uso futuro. Al guardar el método de pago se genera un token que permitirá emitir cobros al cliente sin necesidad de solicitarle nuevamente los datos.

La tokenización protege los datos confidenciales a través de un proceso de reemplazo de los datos con un equivalente no confidencial, conocido como token. El token no tiene significado o valor externo. Es una referencia, o identificador, que a través de un sistema de tokenización, se mapea de nuevo a los datos confidenciales. Este proceso recopila de forma segura información confidencial de la tarjeta de crédito y evita el robo de datos.

info

Auque solemos llamarlo "token" a raíz de que "tokenizamos" la tarjeta, nos estamos refiriendo al UUID de la tarjeta. El campo "token" de una tarjeta es en realidad un valor calculado a partir del número de la tarjeta, de modo que dos tarjetas con mismo PAN tienen diferente UUID pero mismo token. Este token solamente sirve para saber si dos tarjetas son iguales. Siempre que queremos utilizar una tarjeta es necesario indicar su UUID.

Cómo guardar una tarjeta

Podemos almacenar una tarjeta en Paylands mediante uno de los siguientes métodos:

Realizando un pago

Podemos tokenizar cualquier tarjeta al realizar un primer pago con ella. El método habitual para comercios que no son PCI, es utilizar la integración simple mediante carta de pago aunque también es posible lanzar la carta de pago mediante:

En la notificación recibida tras el pago se incluye un objeto de la orden procesada. Dentro de la transacción existe a su vez el objeto source que contiene en su interior el token de la tarjeta utilizada en el pago. Este token quedará a partir de ahora ligado al cliente, por lo que en nuevas operaciones se podrán confirmar los pagos para este usuario sin necesidad de solicitarle de nuevo la tarjeta.

Estos métodos realizan una orden con transacción 3DS la cual genera un token con SCA permitiendo que el comercio envie:

MITs
Cargos puntuales (incrementales)
Cobros recurrentes (subscripciones)

Integrando el SDK de Tokenización

En el caso de estar construyendo una plataforma, web o mobile, donde se desea que el usuario pueda guardar su tarjeta (como Netflix, Amazon) para posteriormente emitirle cobros ya sea de compras o de suscripciones, disponemos de una libreria SDK de Tokenización. Con este SDK los comercios que no son PCI pueden guardar y tokenizar las tarjetas de los clientes embebiendo un iframe en su web/app.

Obtención de las tarjetas

Una vez tenemos guardadas las tarjetas de nuestros clientes en Paylands podemos recuperarlas y hacer uso de ellas de distintas formas. El primer paso será obtener las tarjetas almacenadas de un cliente.

La forma más habitual de recuperar la tarjeta de un cliente es realizando una llamada al método del API de Paylands para obtener las tarjetas de un cliente. Mediante este método se obtiene el listado de tarjetas almacenadas en el sistema para un cliente customer_ext_id dado. El customer_ext_id debe coincidir con el que se utilizó al guardar la tarjeta en el sistema o al crear la orden de pago para cliente.

curl --request GET 'https://api.paylands.com/v1/sandbox/customer/{customer_ext_id}/cards?unique=true' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \

Obtendremos como respuesta el listado de tarjetas del cliente con el uuid de cada una de ellas.

{
  "message": "OK",
  "code": 200,
  "current_time": "2017-01-12T09:12:58+0100",
  "cards": [
    {
      "additional": null,
      "bank": "SERVIRED, SOCIEDAD ESPANOLA DE MEDIOS DE PAGO, S.A.",
      "bin": 454881,
      "brand": "VISA",
      "country": "724",
      "creation_date": "2020-02-18 17:22:56",
      "expire_month": "12",
      "expire_year": "21",
      "holder": "Test user",
      "is_saved": true,
      "last4": "0004",
      "object": "CARD",
      "token": "ebc9b5ffa2efcf74197734a071192817e6f2a3fc15f49c4b1bdb6edc46b16e3ab4109498bff8e6ba00fb6d2bd1838afbea67095c4caaa2f46e4acf4d5851884c",
      "type": "C",
      "uuid": "90F358C9-7D3F-4334-A60D-1717CC1FBF5B"
    },
    {
      "additional": null,
      "bank": "SERVIRED, SOCIEDAD ESPANOLA DE MEDIOS DE PAGO, S.A.",
      "bin": 533821,
      "brand": "MASTERCARD",
      "country": "724",
      "creation_date": "2020-02-18 17:22:56",
      "expire_month": "04",
      "expire_year": "23",
      "holder": "Test user",
      "is_saved": true,
      "last4": "0004",
      "object": "CARD",
      "token": "ad49b5b1a2efcf74197734a071192817e6f2a3fc15f49c4b1bdb6edc46b16e3ab4109498bff8e6ba00fb6d2bd1838afbea67095c4caaa2f46e4acf4d58516cba",
      "type": "C",
      "uuid": "0FDE261B-0E76-499D-A394-B6DCF6C03C56"
    }
  ]
}

Cómo usar la tarjeta

Una vez hemos obtenido las tarjetas de un cliente, podemos realizar pagos y autorizaciones de distintas formas que se explican a continuación.

Pago directo por webservice

El método de pago directo por webservice permite realizar pagos sin la intervención del usuario. Esta forma de pago está dirigida a comercios avanzados que traten ellos mismos sus recurrencias, ya que son ellos quienes deciden la periodicidad de los cobros.

Para ello se necesita el uuid de la orden de pago order_uuid y el uuid de una tarjeta card_uuid previamente almacenada en el sistema. Para generar una nueva orden podemos hacerlo llamando al método Generar orden de pago. La respuesta nos devolverá el [order_uuid]. Por seguridad se solicita la IP del usuario customer_ip que solicita el pago pudiéndose indicar en formato IPv4 o IPv6.

curl --request POST 'https://api.paylands.com/v1/sandbox/payment/direct' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "121149a0ba5361191d740fa898784a8b",
  "order_uuid": "1F405EA3-9798-42A6-9E87-BD347EF67F55",
  "card_uuid": "C10721E7-1404-45DC-8762-351DD9945D1D",
  "customer_ip": "62.43.214.55"
}'

Al ejecutar este método se realizará el pago sin la intervención del usuario devolviendo la siguiente respuesta.

{
  "message": "OK",
  "code": 200,
  "current_time": "2021-12-28T13:51:27+0100",
  "order": {
    "uuid": "91016708-967B-4B58-AD6B-94776C9F7220",
    "created": "2021-12-28T13:51:18+0100",
    "created_from_client_timezone": "2021-12-28T14:51:18+0200",
    "amount": 1,
    "currency": "978",
    "paid": false,
    "status": "PENDING_CONFIRMATION",
    "safe": false,
    "refunded": 0,
    "additional": "",
    "service": "CREDORAX",
    "service_uuid": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
    "customer": "test",
    "cof_txnid": "887001863998888",
    "transactions": [
      {
        "uuid": "580B8D14-FEB0-4DF4-BF81-7B22BFE0F26E",
        "created": "2021-12-28T13:51:22+0100",
        "created_from_client_timezone": "2021-12-28T14:51:22+0200",
        "operative": "DEFERRED",
        "amount": 1,
        "authorization": "055005",
        "processor_id": "XZZ727f5d8192a0c0DCY5FKHSB3MVA6N",
        "status": "SUCCESS",
        "error": "NONE",
        "source": {
          "object": "CARD",
          "uuid": "7088F344-4261-4244-B0E3-CAEE35E4ADB3",
          "type": "",
          "token": "f41fdb5764efad821b2527aeaaf236e29d010771ea5a73ba26044526ec934f1100d8fc6930910ccd634ecc81c0aa7a1b3b721a739f2bac8aa4eedc0d529806d8",
          "brand": "VISA",
          "country": "US",
          "holder": "Paco",
          "bin": 476173,
          "last4": "0016",
          "is_saved": true,
          "expire_month": "09",
          "expire_year": "23",
          "additional": null,
          "bank": "",
          "prepaid": "",
          "validation_date": "2021-12-28 13:51:26",
          "creation_date": "2021-12-28 13:50:45",
          "brand_description": null
        },
        "antifraud": null,
        "device": null
      }
    ],
    "token": null,
    "ip": "127.0.0.1",
    "reference": null,
    "dynamic_descriptor": null,
    "threeds_data": null
  },
  "client": {
    "uuid": "42B8CF56-A7D7-4D4A-8349-4E27263CB2D5"
  }
}

Si como comercio tienes el sistema antifraude activado, podría darse el caso que alguna regla se activase y fuese necesario finalizar el cobro por 3DS. De ser así, la respuesta devuelta contendrá en el campo details la URL a la que debe redirigirse al usuario para autenticarse y poder finalizar el cobro.

{
  "message": "OK",
  "code": 200,
  "current_time": "2021-12-28T13:51:27+0100",
  "details": "URL_3DS",
  "client": {
    "uuid": "42B8CF56-A7D7-4D4A-8349-4E27263CB2D5"
  }
}

danger

Bajo ningún concepto debe modificarse esta URL, puesto que su formato puede variar en futuras actualizaciones. Su uso se restringe a obtenerla del cuerpo de la petición y redirigir al usuario.

Pago tokenizado 3DS

Este método de pago mediante el token de una orden es similar al pago directo por webservice, con la diferencia que en este caso al usuario se le mostrará la pantalla de 3DS antes de finalizarlo.

Para generar una nueva orden podemos hacerlo llamando al método Generar orden de pago. La respuesta nos devolverá el order_token. Lanzaremos un pago tokenizado 3DS añadiendo el order_token de la orden en la URL de la llamada.

Autorización 3DS de la tarjeta

Si para una tarjeta no se ha realizado todavía un pago 3DS y queremos utilizarla más adelante para lanzar pagos directos por webservice sin querer cobrar todavía al usuario, es posible realizar una autorización 3DS de la tarjeta lanzando un pago 3DS de 0€. En este caso el usuario solamente se autentica de forma segura para más adelante poder ser cobrado por el comercio sin que él tenga que volver a intervenir. Este es un proceso habitual por ejemplo en hoteles o algunos proveedores de subscripciones.

Deberemos generar una nueva orden de pago con el método Generar orden de pago indicando en el campo source_uuid el uuid de la tarjeta que deseamos autorizar y en el campo amount indicar el valor 0. También es preciso indicar el campo operative con el valor AUTHORIZATION.

curl --request POST 'https://api.paylands.com/v1/sandbox/payment' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "341f7de8e6fc49da8d8736473af6b03a",
  "amount": 0,
  "operative": "AUTHORIZATION",
  "source_uuid": "UUID_TARJETA",
  "secure": false,
  "customer_ext_id": "test",
  "service": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
  "description": "Payment #1",
  "additional": null,
  "url_post": "https://my.website.com/process",
  "url_ok": "https://my.website.com/ok",
  "url_ko": "https://my.website.com/ko",
  "template_uuid": "6412549E-933E-4DFE-A225-2E87FBF7623E",
  "dcc_template_uuid": "BF418CA6-7043-4864-B36F-F02C2CF2B76B",
  "save_card": true,
  "reference": "50620",
  "dynamic_descriptor": "PNP*NombreComercio",
  "expires_in": 3600
}'

Al lanzar la orden de autorización 3DS obtendremos la siguiente respuesta y la tarjeta estará autorizada para emitir futuros cobros.

{
  "message": "OK",
  "code": 200,
  "current_time": "2021-12-28T13:51:27+0100",
  "order": {
    "uuid": "91016708-967B-4B58-AD6B-94776C9F7220",
    "created": "2021-12-28T13:51:18+0100",
    "created_from_client_timezone": "2021-12-28T14:51:18+0200",
    "amount": 0,
    "currency": "978",
    "paid": false,
    "status": "PENDING_CONFIRMATION",
    "safe": false,
    "refunded": 0,
    "additional": "",
    "service": "CREDORAX",
    "service_uuid": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
    "customer": "test",
    "cof_txnid": "887001863998888",
    "transactions": [
      {
        "uuid": "580B8D14-FEB0-4DF4-BF81-7B22BFE0F26E",
        "created": "2021-12-28T13:51:22+0100",
        "created_from_client_timezone": "2021-12-28T14:51:22+0200",
        "operative": "AUTHORIZATION",
        "amount": 0,
        "authorization": "055005",
        "processor_id": "XZZ727f5d8192a0c0DCY5FKHSB3MVA6N",
        "status": "SUCCESS",
        "error": "NONE",
        "source": {
          "object": "CARD",
          "uuid": "7088F344-4261-4244-B0E3-CAEE35E4ADB3",
          "type": "",
          "token": "f41fdb5764efad821b2527aeaaf236e29d010771ea5a73ba26044526ec934f1100d8fc6930910ccd634ecc81c0aa7a1b3b721a739f2bac8aa4eedc0d529806d8",
          "brand": "VISA",
          "country": "US",
          "holder": "Paco",
          "bin": 476173,
          "last4": "0016",
          "is_saved": true,
          "expire_month": "09",
          "expire_year": "23",
          "additional": null,
          "bank": "",
          "prepaid": "",
          "validation_date": "2021-12-28 13:51:26",
          "creation_date": "2021-12-28 13:50:45",
          "brand_description": null
        },
        "antifraud": null,
        "device": null
      }
    ],
    "token": "34f1100d8fc6930910ccd634ecc81c0aa7a1b3b721a739f2bac8aa4eedc0d529806d8f41fdb5764efad821b2527aeaaf236e29d010771ea5a73ba26044526ec9",
    "ip": "127.0.0.1",
    "reference": null,
    "dynamic_descriptor": null,
    "threeds_data": null
  },
  "client": {
    "uuid": "42B8CF56-A7D7-4D4A-8349-4E27263CB2D5"
  }
}

Tarjetas dinámicas

Cuando el usuario paga mediante un wallet como Google Pay o Apple Pay, no está proporcionando el número de su tarjeta sino un pseudónimo llamado DPAN (Device PAN). Este número tiene la misma apariencia y está asociado al PAN (Primary Account Number) real de la tarjeta, sin embargo existen varias limitaciones en torno a la información que obtenemos y su uso. Estos medios de pago se conocen como tarjetas dinámicas en Paylands.

	PAN	DPAN
Definición	Identificador único por tarjeta	Identificador único por tarjeta y dispositivo
Disponibilidad	Todos los proveedores lo soportan, no requiere de un wallet	Solo algunos proveedores lo soportan, requiere de un wallet
Reusabilidad	Puede reutilizarse en cualquier tipo de pago	Solo puede reutilizarse en pagos sin la presencia del usuario
Tokenización	El PAN es real y no se puede invalidar	El DPAN es un alias y el usuario puede invalidarlo posteriormente

Debido a que varios DPAN corresponden a un mismo PAN, las tarjetas dinámicas no contienen el campo token que se utiliza para determinar si dos tarjetas tienen el mismo PAN. Debido también a que el DPAN es un alias y no el número de la tarjeta, no disponemos del BIN, aunque sí del last4 real de la tarjeta porque Google Pay y Apple Pay lo proporcionan por separado. Finalmente, la fecha de expiración no se proporciona, por lo que no disponemos de ella.

	PAN	DPAN
UUID	✔	✔
Token único	✔	❌
Fecha de expiración	✔	❌
BIN	✔	❌
Last4	✔	✔
Holder/Alias*	✔	✔
Débito/Crédito	✔	✔
País de emisión	✔	✔
Nombre del banco	✔	✔
Prepago	✔	✔
Descripción de la marca	✔	✔

Ventajas y desventajas

La principal ventaja de solicitar los datos de tarjeta a través de Google Pay o Apple Pay es que en algunos casos el pago ya se considera autenticado y no es necesario llevar a cabo el 3DS. La desventaja es que la autenticación la lleva a cabo el wallet cuando obtiene los datos de la tarjeta, por lo que es necesario que el usuario interactúe con el wallet cada vez. Esto previene que se lancen pagos tokenizados 3DS con UUIDs de tarjetas dinámicas.

Otra ventaja es que el usuario no necesita introducir los datos de su tarjeta si ya los tiene registrados en su wallet. Esto puede afectar positivamente a la conversión ya que para el usuario le resulta más cómodo seleccionar su tarjeta. Además, utilizar Google Pay o Apple Pay puede resultar más familiar a ciertos usuarios que desconfíen de introducir los datos de su tarjeta en páginas web de terceros.

Una desventaja es que debido a que desconocemos el BIN de la tarjeta, el usuario solamente podrá ver los últimos 4 dígitos de su tarjeta para poder identificarla. Esto es relevante si se muestra al usuario la lista de tarjetas que tiene asociadas y necesita seleccionar una de ellas. Para facilitar su identificación, recomendamos mostrar la marca de la tarjeta junto a sus últimos 4 dígitos como en el siguiente ejemplo:

Ejemplo de listado de tarjetas

Dependiendo del uso que se le vaya a dar a la tarjeta, es importante tener en cuenta su tipo cuando se obtienen las tarjetas de un usuario. Las tarjetas dinámicas pueden identificarse mediante el campo "object": "DYNAMIC_CARD" de la respuesta.

Otra desventaja es que no todos los servicios de pago soportan pagos con DPAN, sin embargo esto es cada vez menos habitual. Si tu comercio quiere ofrecer Google Pay o Apple Pay debes asegurarte de que el servicio de pago que utilizas soporta pagos con DPAN.

Cómo guardar una tarjeta​

Realizando un pago​

Integrando el SDK de Tokenización​

Obtención de las tarjetas​

Cómo usar la tarjeta​

Pago directo por webservice​

Pago tokenizado 3DS​

Autorización 3DS de la tarjeta​

Tarjetas dinámicas​

Ventajas y desventajas​