# POST /api/tokens Create payment token Creates a secure token for storing payment method information. **Operation ID:** `tokensCreate` ## Authorization No permission required. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Request Body **Content type:** `application/json` Schema: `PaymentTokenCreateDto` Properties: - `numericToken` (integer(int64)): The numeric representation of the token. - `cardFormatToken` (string): The card format representation of the token. - `transactionId` (string(uuid)): The unique identifier of the transaction that minted the token, when one did. Stored as supplied on create; a token created with it reads as transaction-created, and one created without it as standalone. - `paymentDetails` (object): The payment details snapshot associated with this token. Conditional: When PaymentDetails is not null. - `type` (object): The underlying payment type of the token. - `category` (object): The category of the token (e.g., internal, network). - `merchantId` (string(uuid)): Id of the related Merchant. - `label` (string): Optional human-readable label for the token (e.g. "John's Visa"). - `customerId` (string(uuid)): Id of the related Customer. - `isActive` (boolean): Gets or sets a value indicating whether this entity is active. - `status` (object): The status of the token (Active, Inactive, Invalidated, Redacted). - `invalidatedByTokenId` (string(uuid)): The ID of the token that replaced this one (if invalidated and regenerated). - `replacesTokenId` (string(uuid)): The ID of the token that this token replaced (if this is a regenerated token). - `regenerationReason` (object): The reason for token regeneration (if applicable). - `lastRegeneratedAt` (string(date-time)): The timestamp when this token was last regenerated. **Content type:** `text/json` Schema: `PaymentTokenCreateDto` Properties: - `numericToken` (integer(int64)): The numeric representation of the token. - `cardFormatToken` (string): The card format representation of the token. - `transactionId` (string(uuid)): The unique identifier of the transaction that minted the token, when one did. Stored as supplied on create; a token created with it reads as transaction-created, and one created without it as standalone. - `paymentDetails` (object): The payment details snapshot associated with this token. Conditional: When PaymentDetails is not null. - `type` (object): The underlying payment type of the token. - `category` (object): The category of the token (e.g., internal, network). - `merchantId` (string(uuid)): Id of the related Merchant. - `label` (string): Optional human-readable label for the token (e.g. "John's Visa"). - `customerId` (string(uuid)): Id of the related Customer. - `isActive` (boolean): Gets or sets a value indicating whether this entity is active. - `status` (object): The status of the token (Active, Inactive, Invalidated, Redacted). - `invalidatedByTokenId` (string(uuid)): The ID of the token that replaced this one (if invalidated and regenerated). - `replacesTokenId` (string(uuid)): The ID of the token that this token replaced (if this is a regenerated token). - `regenerationReason` (object): The reason for token regeneration (if applicable). - `lastRegeneratedAt` (string(date-time)): The timestamp when this token was last regenerated. **Content type:** `application/*+json` Schema: `PaymentTokenCreateDto` Properties: - `numericToken` (integer(int64)): The numeric representation of the token. - `cardFormatToken` (string): The card format representation of the token. - `transactionId` (string(uuid)): The unique identifier of the transaction that minted the token, when one did. Stored as supplied on create; a token created with it reads as transaction-created, and one created without it as standalone. - `paymentDetails` (object): The payment details snapshot associated with this token. Conditional: When PaymentDetails is not null. - `type` (object): The underlying payment type of the token. - `category` (object): The category of the token (e.g., internal, network). - `merchantId` (string(uuid)): Id of the related Merchant. - `label` (string): Optional human-readable label for the token (e.g. "John's Visa"). - `customerId` (string(uuid)): Id of the related Customer. - `isActive` (boolean): Gets or sets a value indicating whether this entity is active. - `status` (object): The status of the token (Active, Inactive, Invalidated, Redacted). - `invalidatedByTokenId` (string(uuid)): The ID of the token that replaced this one (if invalidated and regenerated). - `replacesTokenId` (string(uuid)): The ID of the token that this token replaced (if this is a regenerated token). - `regenerationReason` (object): The reason for token regeneration (if applicable). - `lastRegeneratedAt` (string(date-time)): The timestamp when this token was last regenerated. ## Responses ### 200 OK **Content type:** `application/json` Schema: `PaymentTokenDto` Properties: - `extraProperties` (object) - `id` (string(uuid)) - `creationTime` (string(date-time)): The date and time when this entity was created. - `creatorId` (string(uuid)): The ID of the user who created this entity. - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. - `isDeleted` (boolean): Indicates whether this entity has been deleted. - `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. - `tenantId` (string(uuid)): Id of the related tenant. - `concurrencyStamp` (string) - `numericToken` (integer(int64)): The numeric representation of the token. - `cardFormatToken` (string): The card format representation of the token. - `transactionId` (string(uuid)): The unique identifier of the associated transaction when the token was created. - `paymentDetails` (object): The payment details snapshot associated with this token. - `type` (object): The underlying payment type of the token. - `category` (object): The category of the token (e.g., internal, network). - `merchantId` (string(uuid)): Id of the related Merchant. - `customerId` (string(uuid)): The customer this stored credential is bound to, or `null` when it is not bound to one. - `tokenSharing` (boolean): The sharing status of the token. - `label` (string): Optional human-readable label for the token. - `status` (object): The status of the token (Active, Inactive, Invalidated). - `invalidatedByTokenId` (string(uuid)): The ID of the token that replaced this one (if invalidated and regenerated). - `replacesTokenId` (string(uuid)): The ID of the token that this token replaced (if this is a regenerated token). - `regenerationReason` (object): The reason for token regeneration (if applicable). - `lastRegeneratedAt` (string(date-time)): The timestamp when this token was last regenerated. - `redactedAt` (string(date-time)): When the token's stored card or bank account details were erased, or `null` for a token that has not been redacted. - `redactionReason` (string): The reason recorded when the token's stored details were erased, or `null` for a token that has not been redacted. - `publicReference` (string): The stable, opaque `pt_`-prefixed handle for this token: the only token identifier permitted to leave the gateway, and the value to charge against on a merchant-initiated transaction. Distinct from the internal id, which correlates to a card number and is never treated as a merchant-facing handle. ### 403 Forbidden **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 401 Unauthorized **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 400 Bad Request **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 404 Not Found **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 501 Not Implemented **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 500 Internal Server Error **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. See the error-code reference in this document's description for the values `error.code` can take. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause. **Content type:** `application/problem+json` Schema: `RateLimitProblemDetails` Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. - `title` (string) required: A short, human-readable summary of the problem type. - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ## Example request Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key. The request body is a PaymentTokenCreateDto. See the Request body section below for its fields. ### cURL ```bash curl -X POST "{{BASE_URL}}/api/tokens" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "numericToken": 0, "cardFormatToken": "", "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentDetails": {}, "type": {}, "category": {}, "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": false, "status": {}, "invalidatedByTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "replacesTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "regenerationReason": {}, "lastRegeneratedAt": "2026-01-01T00:00:00Z" }' ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "numericToken": 0, "cardFormatToken": "", "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentDetails": {}, "type": {}, "category": {}, "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": false, "status": {}, "invalidatedByTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "replacesTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "regenerationReason": {}, "lastRegeneratedAt": "2026-01-01T00:00:00Z" } '@ $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/tokens' ` -Headers $headers -ContentType 'application/json' -Body $body ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, TokensApi } from '@winkpg/winkpg-api'; const api = new TokensApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.tokensCreate({ "numericToken": 0, "cardFormatToken": "", "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentDetails": {}, "type": {}, "category": {}, "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": false, "status": {}, "invalidatedByTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "replacesTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "regenerationReason": {}, "lastRegeneratedAt": "2026-01-01T00:00:00Z" }); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/tokens', { method: 'POST', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "numericToken": 0, "cardFormatToken": "", "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentDetails": {}, "type": {}, "category": {}, "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": false, "status": {}, "invalidatedByTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "replacesTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "regenerationReason": {}, "lastRegeneratedAt": "2026-01-01T00:00:00Z" }), }); const data = await response.json(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp using WinkPg.Api.Client.Api; using WinkPg.Api.Client.Client; using System.Text.Json; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new TokensApi(config); var body = JsonSerializer.Deserialize(""" { "numericToken": 0, "cardFormatToken": "", "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentDetails": {}, "type": {}, "category": {}, "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": false, "status": {}, "invalidatedByTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "replacesTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "regenerationReason": {}, "lastRegeneratedAt": "2026-01-01T00:00:00Z" } """); var result = await api.TokensCreateAsync(body); ``` ### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/tokens"); request.Headers.Add("api-key", "{{API_KEY}}"); request.Content = new StringContent(""" { "numericToken": 0, "cardFormatToken": "", "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentDetails": {}, "type": {}, "category": {}, "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": false, "status": {}, "invalidatedByTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "replacesTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "regenerationReason": {}, "lastRegeneratedAt": "2026-01-01T00:00:00Z" } """, Encoding.UTF8, "application/json"); var response = await http.SendAsync(request); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python import winkpg_api configuration = winkpg_api.Configuration(host="{{BASE_URL}}") configuration.api_key["ApiKey"] = "{{API_KEY}}" with winkpg_api.ApiClient(configuration) as client: api = winkpg_api.TokensApi(client) body = winkpg_api.PaymentTokenCreateDto.from_dict({ "numericToken": 0, "cardFormatToken": "", "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentDetails": {}, "type": {}, "category": {}, "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": False, "status": {}, "invalidatedByTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "replacesTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "regenerationReason": {}, "lastRegeneratedAt": "2026-01-01T00:00:00Z" }) result = api.tokens_create(body) ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "numericToken": 0, "cardFormatToken": "", "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "paymentDetails": {}, "type": {}, "category": {}, "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": False, "status": {}, "invalidatedByTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "replacesTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "regenerationReason": {}, "lastRegeneratedAt": "2026-01-01T00:00:00Z" } response = requests.request( "POST", "{{BASE_URL}}/api/tokens", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal-simpay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.