Storing and using cards

This guide explains the different ways in which we can store a card (tokenize it) and in which ways we can later retrieve and use it.

When we talk about tokenization, we are referring to the action of saving a payment method for future use. By saving the payment method, a token is generated that will allow us to issue payments to the customer without the need to request the customer's data again.

Tokenization protects sensitive data through a process of replacing the data with a non-sensitive equivalent, known as a token. The token has no external meaning or value. It is a reference, or identifier, that through a tokenization system, is mapped back to the confidential data. This process securely collects sensitive credit card information and prevents data theft.

info

Although we usually call it "token" after "tokenizamos" the card, we are referring to the UUID of the card. The "token" field of a card is actually a value calculated from the card number, so that two cards with the same PAN have different UUID but the same token. This token only serves to know if two cards are the same. Whenever we want to use a card it is necessary to indicate its UUID.

How to store a card

We can store a card in Paylands using one of the following methods:

Making a payment.

We can tokenize any card when making a first payment with it. The usual method for non-PCI merchants, is to use simple-integration via payment card although it is also possible to launch the payment card via:

Payment links
Motorcycle payments](/docs/integration/moto-payments)
E-commerce plugins.

In the notification received after the payment an object of the processed order is included. Within the transaction there is also a source object that contains the token of the card used in the payment. This token will from now on be linked to the customer, so that in new transactions it will be possible to confirm payments for this user without the need to request the card again.

These methods perform an order with transaction 3DS which generates a token with SCA allowing the merchant to send:

MITs
One-time charges (incremental)
Recurring charges (subscriptions)

Integrating the Tokenization SDK

In the case of building a platform, web or mobile, where you want the user to be able to save his card (like Netflix, Amazon) to later charge him for purchases or subscriptions, we have a library SDK for Tokenization. With this SDK non-PCI merchants can store and tokenize customer cards by embedding an iframe in their web/app.

Obtaining the cards

Once we have stored our customers' cards in Paylands we can retrieve them and use them in different ways. The first step is to retrieve the stored cards of a customer.

The most common way to retrieve a customer's card is to call the Paylands API method to get a customer's cards. This method retrieves the list of cards stored in the system for a given customer customer_ext_id. The customer_ext_id must match the one used when saving the card in the system or creating the customer payment order.

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' \

We will obtain as response the list of client cards with the uuid of each one of them.

{
  "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"
    }
  ]
}

How to use the card

Once we have obtained a customer's cards, we can make payments and authorizations in the following ways.

Direct payment by webservice

The direct webservice payment method allows payments to be made without user intervention. This payment method is intended for advanced merchants who handle their recurring payments themselves, as they are the ones who decide on the frequency of payments.

For this we need the uuid of the payment order order_uuid and the uuid of a card card_uuid previously stored in the system. To generate a new order we can do it by calling the method Generate payment order. The response will return the [order_uuid]. For security reasons the IP of the user customer_ip requesting the payment is requested and can be specified in IPv4 or IPv6 format.

curl --request POST 'https://api.paylands.com/v1/sandbox/payment/direct' \``jsx {6-8}
--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"
}'

Executing this method will perform the payment without user intervention by returning the following response.

{
  "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"
  }
}

If as a merchant you have the anti-fraud system activated, it could be the case that some rule is activated and it is necessary to finalize the charge for 3DS. If so, the returned response will contain in the details field the URL to which the user must be redirected to authenticate and finalize the payment.

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

danger

Under no circumstances should this URL be modified, as its format may change in future updates. Its use is restricted to obtaining it from the request body and redirecting the user.

3DS tokenized payment

This method of payment by tokenizing an order is similar to direct payment by webservice, with the difference that in this case the user will be shown the 3DS screen before finalizing it.

To generate a new order we can do it by calling the method Generate payment order. The response will return the order_token. We will launch a tokenized 3DS payment by adding the order_token of the order in the URL of the call.

3DS authorization of the card

If a 3DS payment has not yet been made for a card and we want to use it later to launch direct payments by webservice without wanting to charge the user yet, it is possible to perform a 3DS authorization of the card by launching a 3DS payment of 0€. In this case the user is only authenticated securely and can later be charged by the merchant without the user having to intervene again. This is a common process for example in hotels or some subscription providers.

We must generate a new payment order with the method Generate payment order indicating in the field source_uuid the uuid of the card we want to authorize and in the field amount indicate the value 0. It is also necessary to indicate the operative field with the value 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*MerchantName",
  "expires_in": 3600
}'

When launching the 3DS authorization command we will get the following response and the card will be authorized to issue future charges.

{
  "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"
  }
}

Dynamic cards

When the user pays using a wallet such as Google Pay or Apple Pay, they are not providing their card number but an alias called DPAN (Device PAN). This number has the same appearance and is associated with the actual PAN (Primary Account Number) of the card, however there are several limitations around the information we obtain and its use. These payment methods are known as dynamic cards in Paylands.

	PAN	DPAN
Definition	Unique identifier per card	Unique identifier per card and wallet
Availability	Supported by all payment services, does not require a wallet	Supported by some payment services, requires a wallet
Reusability	Can be reused in any kind of payment	Can only be reused on payments in which the user is not present
Tokenization	The PAN is real and cannot be revoked	The DPAN is an alias which the user can revoke at any time

Because several DPANs correspond to the same PAN, dynamic cards do not contain the token field used to determine if two cards have the same PAN. Also because the DPAN is an alias and not the card number, we do not have the BIN, although we do have the actual last4 of the card because Google Pay and Apple Pay provide it separately. Finally, the expiration date is not provided, so we do not have it.

	PAN	DPAN
UUID	✔	✔
Unique token	✔	❌
Expiration date	✔	❌
BIN	✔	❌
Last4	✔	✔
Holder/Alias	✔	✔
Debit/Credit	✔	✔
Issuing country	✔	✔
Bank name	✔	✔
Prepaid	✔	✔
Brand description	✔	✔

Advantages and disadvantages

The main advantage of requesting card data through Google Pay or Apple Pay is that in some cases the payment is already considered authenticated and it is not necessary to carry out 3DS. The disadvantage is that the authentication is performed by the wallet when it obtains the card data, so it is necessary for the user to interact with the wallet each time. This prevents 3DS tokenized payments being launched with dynamic card UUIDs.

Another advantage is that the user does not need to enter their card details if they already have them registered in their wallet. This can positively affect conversion as it is more convenient for the user to just select their card. In addition, using Google Pay or Apple Pay may be more familiar to some users who are wary of entering their card details on third-party websites.

A disadvantage is that because we do not know the BIN of the card, the user will only be able to see the last 4 digits of their card in order to identify it. This is relevant if the user is shown the list of cards associated with the card and needs to select one of them. To facilitate its identification, we recommend showing the card brand next to its last 4 digits as in the following example:

Card listing example .

Depending on the intended use of the card, it is important to consider its type when getting cards from a user. Dynamic cards can be identified by the "object": "DYNAMIC_CARD" field in the response.

Another disadvantage is that not all payment services support DPAN payments, however this is becoming less and less common. If your merchant wants to offer Google Pay or Apple Pay you should make sure that the payment service you use supports DPAN payments.

How to store a card​

Making a payment.​

Integrating the Tokenization SDK​

Obtaining the cards​

How to use the card​

Direct payment by webservice​

3DS tokenized payment​

3DS authorization of the card​

Dynamic cards​

Advantages and disadvantages​