Tokenization

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

How It 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.

Before You Begin

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

API Credentials

Valid API credentials and access token for authentication.

Account Setup

Proper account setup for your target country and business verification.

Country Requirements

Understanding of country-specific requirements and local regulations.

Tokenization Methods

There are two available methods for tokenizing a card:

Endpoint for card tokenization
Card tokenization during payment

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:

Parameter	Description	Required
`name`	Cardholder name.	✅
`number`	Card number.	✅
`cvv`	Card Verification Value.	✅
`expirationMonth`	Card expiration month.	✅
`expirationYear`	Card expiration year.	✅

Example Request

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": 2029,
    "expirationMonth": 11
  },
  "errors": []
}

Key Response Fields

Field	Description
`card.token`	Tokenized card.

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 and include the card.save property set to true in your Payin request.

Example Request

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": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "[email protected]"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "[email protected]"
    },
    "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": "dffbd2a6-6e65-469b-8bbe-dac269882220",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "MXN",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "MXN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "MXN",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "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": "YYY180222YY6",
      "type": "RFC"
    },
    "email": "[email protected]",
    "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": "400000",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 12
  },
  "errors": []
}

Key Response Fields

Field	Description
`card.token`	Tokenized card.

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": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "[email protected]"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "[email protected]"
    },
    "card": {
        "token": "WleV6CZ111IMxqp53SIrqzOn1JsGKCef8oBh2mbi56M%3D",
        "cvv": "123",
        "installments": "1"
    }
}'

Get 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.

Example Request

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": []
}

Delete 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.

Example Request

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.

Subscriptions

Set up automated recurring billing cycles using the tokenized card.

Installments

Offer installment payment options to your customers using the tokenized card.

3D Secure

Enhance the security of tokenized card payments with 3D Secure authentication.