Tokenize, store, charge

Preferred path

1. Collect the card with hosted fields.
2. Store tokenId on your customer or order. Store BIN + last four for display if you need them. Never store a PAN.
3. Charge with POST /api/v1/transaction/{apiKey}/debit.

curl -sS https://sandbox-api.tokeni.io/api/v1/transaction/$TOKENI_API_KEY/debit \
  -u "$TOKENI_API_KEY:$TOKENI_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "tokenId": "tok_...",
    "amount": "42.00",
    "currency": "USD"
  }'

Use X-Idempotency-Key when retries are possible. Capture, void, and refund are separate endpoints under /api/v1/transaction/{apiKey}/.

Server-side tokenize

POST /api/v1/tokenize accepts card data. Use it only from a system that is already allowed to see PANs. A normal web origin is not that system.

The response is a token ID plus display fields (BIN, last four, brand, expiry). The PAN is not returned.

Detokenize

POST /api/v1/detokenize returns card data to your server. It requires Basic auth and an HMAC-SHA512 X-Signature. See Authentication.

Detokenize is for processor connections and other PCI environments. Do not detokenize into a browser, a support tool, or logs. Responses must stay inside the CDE boundary you designed with your QSA.

Profiles

Attach a token to a customer with POST /api/v1/profiles/. Recurring charges use the stored token. Update and delete are on the same resource.