Tokenization

Overview

Tokenization lets you securely handle your customers' payment card data by replacing sensitive information — such as the card number and expiration date — with a token. A token is a short-lived reference value that you use in place of raw card data when submitting payments.

Collecting, storing, and processing your customers' card data requires PCI DSS certification. Tokenization allows you to customize your payment page without transmitting or storing sensitive card data on your side.

📘

Note

Make sure your payment form complies with Visa and Mastercard requirements. See External payment page requirements.

How tokenization works

Card data is posted directly from the customer's browser to the Centrobill Gateway API using the tokenization endpoint. The gateway returns a short-lived token in the response. Your server then uses that token in the payment request instead of the actual card details.

The initial payment request must include paymentSource.type = token. Subsequent payments use the paymentAccountId or consumer.id returned from the initial payment — both are available in the IPN callback or via the Feed API. Because card data is never transmitted to or stored by the merchant, this approach removes the PCI DSS certification requirement.

🚧

Important

Every card must be tokenized before its first use. Process each customer's first payment with paymentSource.type = token, using a token generated specifically for that card. If a customer adds a new card, tokenize it before charging it.

Supported payment types

Tokenization supports credit and debit card payments only.

One-time payments

Use one-time payments for single purchases or services. The payment request includes a price object with repeat: false.

Recurring subscriptions

Use recurring subscriptions for automated rebills. When the initial payment request includes a recurring price schedule, Centrobill handles automated rebills and retries. See Set up price information for details on configuring one-time and recurring payment schedules.

Reconciliation

IPNs (Instant payment notifications)

Centrobill sends an IPN to your configured ipnUrl for each transaction event, including initial sales and subscription rebills. Your server must respond with HTTP 200 to acknowledge receipt. See Process IPN for details on handling IPN payloads.

Data polling

If an IPN is undelivered, or for chargebacks, refunds, and other transaction discrepancies, you can poll transaction data directly using the Feed API.