Payment Token

Magento does not store any private credit card details. It only stores the data received from the payment provider: payment processor token and credit card details without sensitive data.

This information is stored in Payment Token.

The basic interface for Payment Token is PaymentTokenInterface.

To retrieve and store token details, you need to implement a response handler. In the response handler a Payment Token entity is created and stored in the payment extension attributes.

Following sample is an example of the response handler implementation:

use Magento\Vault\Api\Data\PaymentTokenFactoryInterface;
use Magento\Vault\Api\Data\PaymentTokenInterface;

class VaultDetailsHandler implements HandlerInterface
     * @inheritdoc
    public function handle(array $handlingSubject, array $response)
        $paymentDO = $this->subjectReader->readPayment($handlingSubject);
        $transaction = $this->subjectReader->readTransaction($response);
        $payment = $paymentDO->getPayment();

        // add vault payment token entity to extension attributes
        $paymentToken = $this->getVaultPaymentToken($transaction);
        if (null !== $paymentToken) {
            $extensionAttributes = $this->getExtensionAttributes($payment);

     * Get vault payment token entity
     * @param \Braintree\Transaction $transaction
     * @return PaymentTokenInterface|null
    protected function getVaultPaymentToken(Transaction $transaction)
        // Check token existing in gateway response
        $token = $transaction->creditCardDetails->token;
        if (empty($token)) {
            return null;

        /** @var PaymentTokenInterface $paymentToken */
        $paymentToken = $this->paymentTokenFactory->create(PaymentTokenFactoryInterface::TOKEN_TYPE_CREDIT_CARD);

            'type' => $this->getCreditCardType($transaction->creditCardDetails->cardType),
            'maskedCC' => $transaction->creditCardDetails->last4,
            'expirationDate' => $transaction->creditCardDetails->expirationDate

        return $paymentToken;

There are two available types of payment tokens:

  • \Magento\Vault\Api\Data\PaymentTokenFactoryInterface::TOKEN_TYPE_CREDIT_CARD is used for credit cards
  • \Magento\Vault\Api\Data\PaymentTokenFactoryInterface::TOKEN_TYPE_ACCOUNT is used for payment accounts like PayPal

Depending on your payment integration, you need to specify one of them to create a payment token.

Also, you can create own type of payment token. But in that case you must re-define the tokenTypes argument for \Magento\Vault\Model\PaymentTokenFactory in di.xml (not just replacing with argument but appending your token type to existing to avoid breaking existing functionality) or provide own preference for \Magento\Vault\Api\Data\PaymentTokenFactoryInterface.

The important thing is the setGatewayToken() method. This method gets the gateway token: a hashed value based on some credit card details. Different payment providers use different algorithms to create this hash. In most cases, exactly this token is used to perform place order actions.

The created response handler must be added to the handler chain in the DI configuration file di.xml.

Example of the Braintriee di.xml:

<virtualType name="BraintreeAuthorizationHandler" type="Magento\Payment\Gateway\Response\HandlerChain">
        <argument name="handlers" xsi:type="array">
            <item name="vault_details" xsi:type="string">Magento\Braintree\Gateway\Response\VaultDetailsHandler</item>

The persistence layer for Payment Token is implemented in the Vault Module.

What’s next

Adding and using UI_Vault component to place orders on the storefront.