- Authenticating with the Network Tokenization API
- Set up webhooks to receive updates
- Provisioning a token from a primary account number (PAN)
- Obtaining a cryptogram for transacting with the network token
- Suspending an active token
- Resuming a suspended token
- Getting the status of a token
- Requesting account data and card art for the card underlying an existing network token
- Deleting an existing token
Review our Testing guide for full instructions on how to test the Network Tokenization API in the sandbox.
Authentication
The Pagos platform uses API keys to authenticate requests to all our services. See our API Authentication guide for full instructions on generating API keys and authenticating with the Pagos APIs.Set Up Webhooks
Webhooks are automated notifications that push information to your designated destination when important events occur. They’re essential for receiving notifications about token status changes or lifecyvle management updates. See our Network Tokenization Webhooks guide for details on setting up and validating webhooks.Provisioning a Network Token
You can provision a network token on POST: /tokenize. “Provisioning a network token” refers to the step you take to convert a PAN into a network token. This is the critical step that signals to an issuer that your company is establishing a relationship with a cardholder that will persist over time. Every time you use the network token for a transaction, that context is accessible to the issuer.Keep in Mind:
-
While we only require the card PAN (
accountNumber
) and expiration date (expirationDate
) to provision a network token, we recommend also providing the card’s CVV2 value if possible, as this gives the issuer more context when authorizing the token’s creation. -
If your tokenization request includes your own
metadata
value for a PAN, that same value will be returned in the response for all API calls associated with that PAN’s token. -
The
expirationDate
object returned from the /tokenize response is the expiration date of the token, not the underlying PAN
Transacting With a Network Token
Before you can process a transaction with a network token, you must first fetch a cryptogram for that token by calling the /transact API endpoint. A cryptogram is an issuer-generated value for the transaction you’re processing, and is a key mechanism to the additional trust issuing banks give network tokens.When you sell recurring subscriptions, you aren’t required to fetch a cryptogram at this time—you can use the details of the token and the expiration date.
Suspending a Token
Token suspension is only available for Visa and American Express cards.
Resuming a Suspended Token
Resuming of a suspended token is only available for Visa and American Express cards.
Getting the Status of a Network Token
Once you’ve provisioned a network token there will be instances when you will want to check the token status and basic token information, such as network, last 4 digits of the token, or expiration date of the token. To do so, call the /status endpoint. There are three possible statuses that a network token can be in:- Active - the token is active and can be used to transact with
- Suspended - the token is temporarily suspended by the merchant
- Deleted - the token has been deleted by the merchant
Requesting Account Data
Call the /account endpoint to request account data for the card underlying an existing network token. The response will include information you can share with the customer to help them identify the exact card saved on file and tokenized with your business (e.g. last four digits of the PAN, expiry date of the PAN, etc.). The response can include acardArt
array containing URLs to the card image file(s).
Card art is only available for Visa and Mastercard. Discover and American Express coming soon.
Deleting a Token
All four networks (Visa, Mastercard, Discover, and American Express) support token deletion.