Tokenization

Overview

Card tokenization allows you to securely collect and store your customer’s card details without handling raw card data directly after the initial interaction.
With Orkestra’s tokenization endpoint, you send the card details once, and we return a token that can be safely used for future payments.

Tokens are PCI-compliant, unique, and scoped to your merchant environment.

🔐 Endpoint

POST {{host}}/cards/tokenize

📝 Required Fields

Field	Type	Description
card.number	String	PAN (Primary Account Number).
card.expiresAt	String	Expiration date in MM/YYYY format.
card.securityCode	String	CVV/CVC of the card.
card.holder.firstName	String	First name of the cardholder.
card.holder.lastName	String	Last name of the cardholder.
card.holder.document	String	CPF/CNPJ of the cardholder.
card.holder.documentType	String	"CPF" or "CNPJ".
card.billingAddress.street	String	Street name of billing address.
card.billingAddress.number	String	Street number.
card.billingAddress.complement	String	Address complement (optional).
card.billingAddress.neighborhood	String	Neighborhood or district.
card.billingAddress.zipCode	String	ZIP/postal code.
card.billingAddress.city	String	City name.
card.billingAddress.state	String	State/Province abbreviation.
card.billingAddress.country	String	3-letter ISO country code (e.g. BRA).
card.billingAddress.mainInformation	String	Street + number (for autofill tools).
card.billingAddress.secondaryInformation	String	Additional delivery info (e.g. apt number).
card.billingAddress.latitude	Float	Optional GPS coordinate (latitude).
card.billingAddress.longitude	Float	Optional GPS coordinate (longitude).
card.issuingCountry	String	3-letter ISO code for card-issuing country (e.g. BRA).

📦 Example: Tokenization Request

JSON

{
  "card": {
    "number": "5162200000000000",
    "expiresAt": "12/2026",
    "securityCode": "123",
    "holder": {
      "firstName": "Maria",
      "lastName": "Souza",
      "document": "00000000000",
      "documentType": "CPF"
    },
    "billingAddress": {
      "street": "Av. Exemplo",
      "number": "123",
      "complement": "Ap 101",
      "neighborhood": "Centro",
      "zipCode": "00000000",
      "city": "Cidade Exemplo",
      "state": "SP",
      "country": "BRA",
      "mainInformation": "Av. Exemplo, 123",
      "secondaryInformation": "Ap 101",
      "latitude": -23.000000,
      "longitude": -46.000000
    },
    "issuingCountry": "BRA"
  }
}

📦 Example: Tokenization Response

JSON

{
  "token": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "scheme": "MASTERCARD",
  "firstSixDigits": "516220",
  "lastFourDigits": "0000",
  "expiresAt": "12/2026"
}

✅ Usage Notes

• Once tokenized, the token can be used in future charge requests via paymentMethod = "CARD" and paymentMethod.token.
• You must not store the card number or CVV — only the token.
• CVV is only used during tokenization. It cannot be reused.
• This endpoint requires secure server-side handling (PCI SAQ-D or Token Proxy).
• If using frontend libraries, make sure your integration is PCI compliant.

📬 Summary

Card tokenization with Orkestra allows you to:

• Securely store customer cards
• Enable 1-click payments
• Reduce PCI compliance scope

Use this flow to collect and convert cards into tokens for a safe, fast, and compliant checkout experience.