1. Charge the card the first time

API call

POST /api/transactions

An ordinary card sale, with the card number on the request. This is the one and only time the card number crosses your system in this flow: everything after it addresses the card by a handle. Keep the transaction id and the merchant id off the response, because the tokenization below is scoped by both.

Reference for this operation

curl -X POST "{{BASE_URL}}/api/transactions" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "Sale",
    "cardData": {
      "cardNumber": "4111111111111111",
      "nameOnCard": "Jane Doe",
      "expirationMonth": 12,
      "expirationYear": 2030,
      "cvv": 123
    },
    "invoiceData": {
      "amounts": { "base": 10.00, "total": 10.00 }
    }
  }'

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };
http.DefaultRequestHeaders.Add("api-key", "{{API_KEY}}");

var response = await http.PostAsJsonAsync("/api/transactions", new
{
    transactionType = "Sale",
    cardData = new
    {
        cardNumber = "4111111111111111",
        nameOnCard = "Jane Doe",
        expirationMonth = 12,
        expirationYear = 2030,
        cvv = 123
    },
    invoiceData = new
    {
        amounts = new { @base = 10.00m, total = 10.00m }
    }
});

response.EnsureSuccessStatusCode();

var sale = await response.Content.ReadFromJsonAsync<JsonElement>();
var transactionId = sale.GetProperty("id").GetString();
var merchantId = sale.GetProperty("merchantId").GetString();

{
  "id": "9f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "merchantId": "3a7b1c9d-2e4f-4a6b-8c8d-9e0f1a2b3c4d",
  "transactionType": "Sale",
  "resultCode": "Ok",
  "authorizedAmount": 10.00,
  "responseData": {
    "resultCode": "Ok",
    "resultMessage": "Approved"
  }
}

2. Turn that sale into a reusable stored payment method

API call

POST /api/tokens/create-from-transaction-async?transactionId={{transactionId}}&merchantId={{merchantId}}

Mint a token from the card the sale was paid with. Nothing sensitive travels in either direction. The request carries two ids, and the response carries the handle plus masked details for you to show the customer, such as "Visa ending 1111" in a wallet list. Store the publicReference against your customer record and nothing else about the card. Do this only when the customer has agreed you may keep their card, and keep a record of that agreement. Storing a card is a promise to them before it's an API call.

Reference for this operation

curl -X POST \
  "{{BASE_URL}}/api/tokens/create-from-transaction-async?transactionId={{transactionId}}&merchantId={{merchantId}}" \
  -H "api-key: {{API_KEY}}"

var minted = await http.PostAsync(
    "/api/tokens/create-from-transaction-async"
    + $"?transactionId={transactionId}&merchantId={merchantId}",
    content: null);

minted.EnsureSuccessStatusCode();

var token = await minted.Content.ReadFromJsonAsync<JsonElement>();

// The opaque pt_ handle: store this against your customer and nothing else about
// the card. The masked details beside it are for showing the customer which card
// they picked, not for reconstructing one.
var savedCardToken = token.GetProperty("publicReference").GetString();

{
  "id": "4e6f8a0b-2c3d-4e5f-9a6b-7c8d9e0f1a2b",
  "publicReference": "pt_7Qh2Kd4RmT9xLbVn",
  "type": "Card",
  "category": "Internal",
  "maskedPaymentDetails": {
    "paymentMethodType": "Card"
  }
}

3. Charge the stored payment method without the card number

API call

POST /api/transactions

Send the same create call as the first sale, with tokenData in place of cardData and no card number anywhere. The amount is free to differ (9.00 here rather than 10.00), because a stored payment method is a stored instrument rather than a stored amount. Send initiationType as well, and choose it by whether the customer is present for this charge, not by which system sends it. This step is the customer at your checkout picking the card they saved and selecting Pay, so it's CardholderInitiated: the platform reports it to the processor as a card-on-file use and needs nothing else from you. A charge the customer isn't sitting in front of, such as a subscription renewal or a balance you collect later, is MerchantInitiated instead, with a mitReason and the owning customer in invoiceData.customerId, and it's accepted only against a stored-credential consent captured when the card was saved on a hosted payment page. That's a different collection story from this one, so this step doesn't demonstrate it. The guide linked below shows both shapes side by side.

Reference for this operation

Guides: reusing a stored payment method with payment tokens

curl -X POST "{{BASE_URL}}/api/transactions" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "Sale",
    "initiationType": "CardholderInitiated",
    "tokenData": {
      "token": "{{savedCardToken}}"
    },
    "invoiceData": {
      "amounts": { "base": 9.00, "total": 9.00 }
    }
  }'

var repeat = await http.PostAsJsonAsync("/api/transactions", new
{
    transactionType = "Sale",
    initiationType = "CardholderInitiated",
    tokenData = new { token = savedCardToken },
    invoiceData = new
    {
        amounts = new { @base = 9.00m, total = 9.00m }
    }
});

repeat.EnsureSuccessStatusCode();

4. Look the stored payment method up by its handle

API call

POST /api/tokens/resolve-payment-token-async?paymentTokenidentifier={{savedCardToken}}&transactionMerchantId={{merchantId}}&doOwnershipCheck=true

Resolve the handle to the stored record. Two things come back that matter: the masked details, which let you render a wallet list from handles alone, and the record's own id, which is what the deactivation below addresses. Keep sending doOwnershipCheck=true, which is what makes the resolution refuse a handle belonging to another merchant. The record id is neither a charge handle nor the value to store. Look it up when you need it, and keep storing the publicReference.

Reference for this operation

curl -X POST \
  "{{BASE_URL}}/api/tokens/resolve-payment-token-async?paymentTokenidentifier={{savedCardToken}}&transactionMerchantId={{merchantId}}&doOwnershipCheck=true" \
  -H "api-key: {{API_KEY}}"

var lookup = await http.PostAsync(
    "/api/tokens/resolve-payment-token-async"
    + $"?paymentTokenidentifier={savedCardToken}"
    + $"&transactionMerchantId={merchantId}&doOwnershipCheck=true",
    content: null);

lookup.EnsureSuccessStatusCode();

var stored = await lookup.Content.ReadFromJsonAsync<JsonElement>();
var storedTokenId = stored.GetProperty("id").GetString();
var maskedCard = stored.GetProperty("paymentDetails");

{
  "id": "4e6f8a0b-2c3d-4e5f-9a6b-7c8d9e0f1a2b",
  "publicReference": "{{savedCardToken}}",
  "merchantId": "{{merchantId}}",
  "transactionId": "{{transactionId}}",
  "type": "Card",
  "category": "Internal",
  "status": "Active",
  "label": "Visa ending 1111",
  "paymentDetails": {
    "paymentMethodType": "Card"
  }
}

5. Retire the stored payment method

API call

POST /api/tokens/deactivate-async?id={{storedTokenId}}

Deactivate the token when the customer removes their card, closes their account, or asks you to forget them. The record survives, so the transactions that referenced it still reconcile, and further charges against the handle are refused. Prefer this to deleting. Deletion is refused outright once any transaction references the token, which is every token that was ever used. Build this path now rather than the day you need it.

Reference for this operation

curl -X POST "{{BASE_URL}}/api/tokens/deactivate-async?id={{storedTokenId}}" \
  -H "api-key: {{API_KEY}}"

var retired = await http.PostAsync(
    $"/api/tokens/deactivate-async?id={storedTokenId}", content: null);

retired.EnsureSuccessStatusCode();

var result = await retired.Content.ReadFromJsonAsync<JsonElement>();
var status = result.GetProperty("status").GetString(); // Inactive

6. If you need to save a card without charging it

On your side

This blueprint saves the card it just charged, which is the case an integration that already takes payments grows into. A signup that stores a card before the first order has no sale to mint from, and collecting the number yourself to vault it puts you back in scope for handling it. The hosted payment page has a no-charge save mode for exactly that. The customer enters the card on a page you don't host, and you get the same handle back. The hosted page is also where the customer's stored-credential consent is recorded, which a later charge made without them present has to have. The blueprint below covers the hosted flow end to end.

Reference for this operation

Take a payment with a hosted payment page