> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/customers-and-saved-methods/tokenization-guide.md). # Tokenization Guide Save payment instruments for later use with the public sessions, customers, and payments APIs. ## Overview The public API supports tokenization in three contract-backed ways: * Create a hosted tokenization session with `POST /v1/sessions` and `"type": "tokenization"` * Save a card during a payment by sending `paymentMethod.card.tokenizationSettings` * Tokenize a wallet payment method (Google Pay or Apple Pay) directly via `POST /v1/tokenizations` If you are integrating the hosted session flow specifically, start with [Tokenization Session Integration](/rest-api/sessions/tokenization-session.md). If you want to reuse a saved card later, associate it with a customer and read the token from `GET /v1/customers/{customerId}/payment-instruments`. The public contract does not document a standalone `/api/tokens` endpoint or a `saveCard` request flag. If you are tokenizing wallet credentials (Google Pay or Apple Pay) with your own UI, see [Direct Wallet Tokenization](#direct-wallet-tokenization-google-pay--apple-pay) below. Use this guide for collecting and storing reusable payment instruments. For customer CRUD, use [Customer Management](/rest-api/customers-and-saved-methods/customer-management.md). For recurring billing on top of saved instruments, use [Recurring Payments](/rest-api/customers-and-saved-methods/recurring-payments.md). ## Recommended Flow: Tokenization Session Use a tokenization session when you need to save a card without charging it immediately. ### 1. Create a customer Customers are optional for some flows, but they are the recommended way to manage reusable payment instruments. ```http POST /v1/customers Authorization: Basic {credentials} Content-Type: application/json { "referenceId": "customer-1001", "email": "customer@example.com", "firstName": "Test", "lastName": "User" } ``` ### 2. Create the tokenization session ```http POST /v1/sessions Authorization: Basic {credentials} Content-Type: application/json { "merchantId": 12345, "referenceId": "tok-session-1001", "type": "tokenization", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "settings": { "tokenization": { "type": "store", "allowedCardTypes": ["credit", "debit"], "features": ["create", "list", "select", "delete"] }, "callbacks": { "tokenizationCallbackUrl": "https://merchant.example.com/callbacks/tokenization" } } } ``` Use the returned session data in your hosted flow. After completion, either consume the tokenization callback or inspect created sessions with `GET /v1/sessions` using your `referenceId` and pagination filters. ### Inspect created sessions Use `GET /v1/sessions` when you need to audit or troubleshoot checkout and tokenization sessions created by your API key. ```http GET /v1/sessions?merchantId=12345&referenceId=tok-session-1001&page=1&size=20 Authorization: Basic {credentials} ``` You can filter this list by `merchantId`, `referenceId`, `minDate`, and `maxDate`, then paginate with `page` and `size`. ### 3. List the saved instruments ```http GET /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/payment-instruments Authorization: Basic {credentials} ``` Example response: ```json [ { "token": "9b7f1c2e-4a3d-4e8b-9c1f-2d3e4f5a6b7c", "name": "4242", "type": "credit", "issuer": { "id": 1, "name": "VISA" }, "expMonth": 12, "expYear": 2028, "status": "Ok", "tokenizationType": "persistent" } ] ``` ## Save a Card During the First Payment If the first transaction should both charge the customer and save the card, create the payment with `paymentMethod.card.tokenizationSettings`. ```http POST /v1/payments Authorization: Basic {credentials} Content-Type: application/json { "merchantId": 12345, "referenceId": "order-1001", "invoiceNumber": "INV-1001", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "amount": { "total": 10000, "currency": "UYU" }, "paymentMethod": { "source": "card", "card": { "number": "4444333322221111", "expMonth": 12, "expYear": 2028, "cvc": "123", "cardholder": { "firstName": "Test", "lastName": "User", "email": "customer@example.com" }, "tokenizationSettings": { "type": "store" } } }, "capture": { "method": "automatic" } } ``` When the payment succeeds, retrieve the saved token through the customer's payment instruments endpoint. Do not assume the payment response itself is the source of truth for stored instruments. ## Charge a Saved Instrument Once you have the token, create a new payment with `paymentMethod.source = token`. ```http POST /v1/payments Authorization: Basic {credentials} Content-Type: application/json { "merchantId": 12345, "referenceId": "renewal-1001", "invoiceNumber": "INV-RENEWAL-1001", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "amount": { "total": 10000, "currency": "UYU" }, "paymentMethod": { "source": "token", "paymentInstrument": { "token": "9b7f1c2e-4a3d-4e8b-9c1f-2d3e4f5a6b7c" } }, "capture": { "method": "automatic" } } ``` Add `cvc` inside `paymentMethod.paymentInstrument` if your processor or risk policy requires it. ## Direct Wallet Tokenization (Google Pay / Apple Pay) Use `POST /v1/tokenizations` when you collect Google Pay or Apple Pay wallet tokens with your own UI (e.g. the Google Pay or Apple Pay JavaScript SDKs) and want to tokenize them server-side without creating a hosted session. This endpoint only accepts `google-pay-token` and `apple-pay-token` sources. Card tokenization must use sessions or the save-during-payment flow described above. ### Google Pay example ```http POST /v1/tokenizations Authorization: Basic {credentials} Content-Type: application/json { "merchantId": 12345, "type": "temporal", "paymentMethod": { "source": "google-pay-token", "googlePayToken": { "token": "eyJzaWduYXR1cmUiOi...", "cardholder": { "name": "John Doe" } } } } ``` ### Apple Pay example ```http POST /v1/tokenizations Authorization: Basic {credentials} Content-Type: application/json { "merchantId": 12345, "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "store", "paymentMethod": { "source": "apple-pay-token", "applePayToken": { "token": "{\"data\":\"...\",\"header\":{},\"signature\":\"...\",\"version\":\"EC_v1\"}", "cardholder": { "name": "John Doe" } } } } ``` ### Response The response is a `PaymentInstrumentTokenDto` with card metadata including `cardType` (credit, debit, prepaid), `cardOrigin` (uruguay, international), and issuer details: ```json { "token": "9b7f1c2e-4a3d-4e8b-9c1f-2d3e4f5a6b7c", "paymentMethodId": "VISA", "paymentMethodType": "card", "tokenizationType": "temporal", "status": "active", "source": "network-token", "bin": "41111111", "last4": "1111", "expMonth": 12, "expYear": 2030, "cardName": "411111XXXXXX1111", "cardholderName": "John Doe", "cardType": "credit", "cardOrigin": "uruguay", "issuer": { "id": 101, "name": "Banco República Oriental del Uruguay", "shortName": "BROU", "country": "Uruguay", "countryCode": "UY" }, "createdAt": "2025-01-15T10:30:00Z", "expiresAt": "2025-01-16T10:30:00Z" } ``` Use `cardType` and `cardOrigin` (or `issuer.countryCode` when present) to decide which installment options to display in your UI. The endpoint does not calculate installment plans; use the metadata combined with your own merchant configuration for that logic. ### Tokenization types | Type | Behavior | | ---------- | ---------------------------------------------------------------------------------- | | `temporal` | Expires automatically after 24 hours. Use for immediate payment flows. | | `store` | Persists until deleted. Requires a `customerId` for the customer instruments list. | ## Manage Saved Instruments The public customer instrument surface is intentionally small: * List instruments: `GET /v1/customers/{customerId}/payment-instruments` * Delete an instrument: `DELETE /v1/customers/{customerId}/payment-instruments/{tokenId}` The public API does not currently document a "set default instrument" operation. ## Best Practices * Create a customer before tokenization if the card should be reusable * Use tokenization sessions when you do not need an immediate charge * Treat the customer payment instruments endpoint as the canonical source for reusable tokens * Do not store PAN or CVV in your own systems * Use distinct `referenceId` values for the tokenization step and each later charge ## Related Resources * [Customer Management](/rest-api/customers-and-saved-methods/customer-management.md) * [Recurring Payments](/rest-api/customers-and-saved-methods/recurring-payments.md) * [PaymentRequestDto](/rest-api/api-reference/models.md#paymentrequestdto) * [SessionRequest](/rest-api/api-reference/models.md#sessionrequest) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://plexo.gitbook.io/rest-api/customers-and-saved-methods/tokenization-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.