Card Tokenization

Tokenization with Localpayment provides a secure way to handle card information, reducing your security risk and simplifying future transactions.

How Tokenization Works

The process involves these key steps:

Card Information Collection: Card information is securely collected through a form within your application and then transmitted to the Localpayment API.
Token Generation: Localpayment securely stores the card information and generates a unique, irreversible token representing the card details. This token is returned in the API response.
Using the Tokenized Card: For subsequent card payments, you will send the card.token property instead of the customer's actual card details.

Availability

Card tokenization is available in the following countries:

🇦🇷 Argentina: Visa, Mastercard, American Express, Diners, Argencard, Cabal.
🇧🇴 Bolivia: Visa.
🇧🇷 Brazil: Visa, Mastercard, American Express, Elo, Hipercard.
🇨🇱 Chile: Visa, Mastercard, American Express, Diners, Magna.
🇨🇴 Colombia: Visa, Mastercard, American Express, Diners.
🇩🇴 Dominic Republic: Visa.
🇲🇽 Mexico: Visa, Mastercard, American Express.
🇵🇦 Panama: Visa.
🇵🇪 Peru: Visa, Mastercard, American Express, Diners.

Before a card tokenization

Before tokenizing a card, ensure you have completed the following:

Generate an Access Token (Required): You'll need a valid access token to authenticate your API requests. Refer to the Generate an Access Token documentation for instructions.

Tokenization Methods

There are two available methods for tokenizing a card.

Option 1. Endpoint for card tokenization

You can securely tokenize card information for future use through a dedicated endpoint.

To tokenize a card, send a POST request to the Tokenize Card endpoint with the following parameters:

Parameters

name: Cardholder name.
number: Card number.
cvv: Card Verification Value.
expirationMonth: Card expiration month.
expirationYear: Card expiration year.

Request Example

curl --request POST \
     --url https://api.stage.localpayment.com/api/card \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "John Doe",
  "number": "4000000000000002",
  "cvv": "123",
  "expirationMonth": "11",
  "expirationYear": "2029"
}
'

Successful Response Example

In response, the API returns the card token:

{
  "card": {
    "token": "xsWMaLcYjS3L11aBwxl465%2F2d8J85FXPAaBFIKfr0Fx%3D",
    "bin": "400000",
    "brand": "VISA",
    "country": "US",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2028,
    "expirationMonth": 11
  },
  "errors": []
}

The card.token property represents the tokenized card and should be used for subsequent transactions.

Option 2. Card tokenization during payment

Localpayment enables merchants to tokenize cards during payment processing by including the save parameter in the payment requests. This streamlined approach allows you to both process a transaction and store card details in a single API call.

To tokenize a card, send a POST request to the Create Payin endpoint with the following parameters:

Parameters

To tokenize a card during a payment, include the card.save property set to true in your Payin request.

Request Example

curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1000",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "032.032.00000000",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "CUIT",
            "id": "3000091105"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "54",
            "areaCode": "351",
            "number": "1234567"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "DNI",
            "id": "37993123"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        },
        "bank": {
            "name": "BANCO BBVA ARGENTINA S.A.",
            "code": "017",
            "account": {
                "type": "S",
                "number": "19101196551119123456789"
            }
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029",
        "save": true
    }
}'

Successful Response Example

In response, the API returns the card token:

{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "032.032.00000000",
  "confirmed": {
    "currency": "ARS",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "032.032.00000001"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "37895247",
      "type": "DNI"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "token": "xsWMaLcYjS3L11aBwxl465%2F2d8J85FXPAaBFIKfr0Fx%3D",
    "bin": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": []
}

The card.token property represents the tokenized card and should be used for subsequent transactions.

Using Tokenized Cards

To use a tokenized card for a payment, include the card.token in your payment request.

Example Request with Token

curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1000",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "032.032.00000000",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "CUIT",
            "id": "3000091105"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "54",
            "areaCode": "351",
            "number": "1234567"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "DNI",
            "id": "37993123"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        },
        "bank": {
            "name": "BANCO BBVA ARGENTINA S.A.",
            "code": "017",
            "account": {
                "type": "S",
                "number": "19101196551119123456789"
            }
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    },
    "card": {
        "token": "WleV6CZ111IMxqp53SIrqzOn1JsGKCef8oBh2mbi56M%3D",
        "cvv": "123",
        "installments": "1"
    }
}'

Retrieving Card Information

After a card has been tokenized, you can retrieve its details using the Localpayment API. This allows you to display stored payment methods to customers while maintaining PCI compliance.

To obtain card information, send a GET request to the Get Card Details endpoint, including the card's token as a query parameter.

Request Example

curl --location 
--request GET 'https://api.stage.localpayment.com/api/card/?token={token}' \
--header 'Authorization: Bearer <your_access_token>'

Successful Response Example

In response, the API returns the card details:

 {
  "card": {
    "token": "WleV6CZ111IMxqp53SIrqzOn1JsGKCef8oBh2mbi56M%3D",
    "bin": "400000",
    "brand": "VISA",
    "country": "US",
    "name": "",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 11
  },
  "errors": []
}

Deleting a Tokenized Card

Permanently remove stored card tokens through a dedicated API endpoint. This irreversible action helps maintain compliance with data privacy regulations and allows for proper card lifecycle management.

To delete a tokenized card, send a DELETE request to the Delete Tokenized Card endpoint, including the card's token as a query parameter.

Request Example

curl --location \
--request DELETE 'https://api.stage.localpayment.com/api/card/?token={token}' \
--header 'Authorization: Bearer <your_access_token>'

Successful Response Example

A successful deletion will typically return an empty JSON object:

{
  "errors": []
}

Next Steps

Now that you've successfully tokenized a card, you can use the generated token for secure processing across Localpayment's payment services:

One-Time Payments: Use the token to process single, immediate payments. See the One-Time Payments documentation for details.
Recurring Payments: Set up automated recurring billing cycles using the tokenized card. Refer to the Recurring Payments documentation for more information.
Pre-Authorization: Authorize a transaction amount before capturing funds using the tokenized card. See the Pre-Authorization documentation for more details.
Installments: Offer installment payment options to your customers using the tokenized card. Refer to the Installments documentation for more information.
3D Secure: Enhance the security of tokenized card payments with 3D Secure authentication. See the 3D Secure documentation for details.