Card Tokenization

Card Tokenization allows you to debit a customer's card automatically on future transactions, without requiring any input from the customer. After the customer completes their first card payment with tokenization enabled, Monnify generates a secure token representing their card. You store this token and use it to charge them on subsequent payments.

How It Works

1. The customer makes their first payment using the Monnify checkout or SDK. If tokenization is enabled on your merchant account, Monnify will automatically generate a card token on successful payment.
2. On successful payment, you call the Get Transaction Status API to retrieve the cardToken from the cardDetails object.
3. You store the cardToken securely on your server, linked to the customer's account and email address.
4. For future charges, you send the cardToken to the Charge Card Token API with no checkout UI required.

Enable tokenization first:

Card tokenization must be activated on your integration before use. Contact [email protected] to enable this feature on your account.

Step 1 – Collect the First Card Payment

If card tokenization is enabled on your merchant account, Monnify automatically returns a card token after any successful card payment — no additional parameter is needed in your SDK call.

Step 2 – Retrieve the Card Token

After the first payment completes, call the Get Transaction Status API using the transaction's transactionReference or paymentReference. The cardDetails object in the response contains the cardToken.

Sandbox behaviour:

In the sandbox environment, Monnify does not return a real cardToken. Instead, check the supportsTokenization field in reusable: true means the card would produce a token in production, and false means it would not.

Step 3 – Store the Card Token

Once you have the cardToken, store it securely on your server alongside the customer's email address used for the original transaction. Both the token and the email must match on every subsequent charge, as Monnify validates this pair.

1. Treat the token like a sensitive credential and store it encrypted at rest.
2. Never expose the token to the client (browser or mobile app).
3. Link the token to the customer's internal user ID so you can retrieve it when scheduling future charges.

Step 4 – Charge the Token (Future Payments)

Use the stored cardToken to charge the customer for future payments. This call happens entirely server-to-server, with no checkout UI required.

Token Lifecycle & Best Practices

1. One token per card per merchant: if the same customer tokenizes the same card twice, you get the same token.
2. Expired cards: the token becomes invalid when the underlying card expires. Re-collect card details from the customer and tokenize again.
3. Customer consent: always inform customers that you are saving their card for future charges. This is a regulatory and trust requirement.
4. Webhook on charge: Monnify sends a webhook notification for every token-based charge, just like a regular payment. See Webhooks.
5. Verify every charge: always call the Verify Transactions API after a token charge before delivering value.

Sample Error Messages