Secure Fields with stored cards

It is possible to use Secure Fields to collect card details on a profile page to store the card on a buyer’s account. Secure Fields can then be used to collect the security code at checkout, allowing a buyer to use a stored card together with a securely collected security code.

1. Store card for future use

The first step is to store the card data for future use. Use the checkout session as described in the quick-start to store the card details as a new payment method in the vault. This can be done either at the time of creating a transaction by setting the store property to true, or when creating a new payment method directly from the checkout session. Set store only when you first save the card. Storing the same card again creates a new payment method instead of reusing the existing one. The returned payment method includes details about the card that was used, as well as the id of the payment method that can be used in the next step.

{
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "method": "card",
    "scheme": "visa",
    "expiration_date": "07/24",
    ...
}

2. Collect the CVV

At checkout, Secure Fields can be used to collect the CVV for a previously stored card. When initializing Secure Fields, pass the paymentMethod object with both the id and scheme of the previously stored card. This enables proper validation for the security code based on the card scheme (for example, 3 or 4 digits) and provides the appropriate security code label (CVV, CVC, CID) in the field data.

<SecureFields
    gr4vyId="example"
    environment="sandbox"
    sessionId="332a6c3a-c4eb-45f6-9a4e-72af459535e2"
    paymentMethod={{
        id: "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
        scheme: "visa"
    }}
>
    <Form />
</SecureFields>
};

const secureFields = new SecureFields({
  gr4vyId: "example",
  environment: "sandbox",
  sessionId: "332a6c3a-c4eb-45f6-9a4e-72af459535e2",
  paymentMethod: {
    id: "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    scheme: "visa"
  }
});

The paymentMethodId prop is deprecated but still supported for backward compatibility. We recommend using the new paymentMethod prop to benefit from scheme-specific CVV validation.

With this ID in place, you capture the security code securely.

import {
  CardNumber,
  ExpiryDate,
  SecurityCode,
} from '@gr4vy/secure-fields-react'

const Form = () => {
  return (
    <> 
        <label htmlFor="cc-security-code">Security Code</label>
        <SecurityCode placeholder="Enter security code" />
        <button id='cc-button'>Store card data</button> 
    </>
  )
}

<label for="cc-security-code">Security Code</label>
<input id="cc-security-code" />

<button id="cc-button">Store</button>

<script>
  const securityCodeField = secureFields.addSecurityCodeField(
    "#cc-security-code",
    {
      placeholder: "Enter security code",
    }
  );
</script>

When using the paymentMethodId or paymentMethod object with Secure Fields, only the security code can be captured. Attempting to add any of the other fields (number, expiration date) will result in an error.

3. Create a transaction

When Secure Fields is submitted, it collects the security code for the stored payment method. You can then create a transaction with the checkout session much like a regular Secure Fields transaction.

Don’t set store to true on this transaction. The card is already stored. If you send store: true and the transaction is declined or fails, for example because 3-D Secure fails, Gr4vy can remove the stored payment method from the buyer.

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "USD",
        Country = "US",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                new CheckoutSessionWithUrlPaymentMethodCreate()
                {
                    Id = checkoutSession.Id,
                }
            ),
    }
);

amount := int64(1299)
currency := "USD"

checkoutSessionWithURLPaymentMethodCreate := components.CheckoutSessionWithURLPaymentMethodCreate{
    ID: checkoutSession.ID,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodCheckoutSessionWithURLPaymentMethodCreate(checkoutSessionWithURLPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
    Amount:        amount,
    Currency:      currency,
    PaymentMethod: &paymentMethod,
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)

// handle response

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
        .amount(1299L)
        .currency("USD")
        .paymentMethod(TransactionCreatePaymentMethod.of(CheckoutSessionWithUrlPaymentMethodCreate.builder()
            .id(checkoutSession.id())
            .build()))
        .build())
    .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

// handle response

$transactionCreate = new TransactionCreate(amount: 1299, currency: 'USD', paymentMethod: new CheckoutSessionWithUrlPaymentMethodCreate(id: $checkoutSession->id));
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="USD",
    payment_method={
        "method": "checkout-session",
        "id": checkout_session.id,
    }
)

const transaction = await gr4vy.transactions.create({
    amount: 1299,
    currency: "USD",
    paymentMethod: {
    method: "checkout-session",
    id: checkoutSession.id
    }
})

The returned transaction includes details about the payment method used, and the status of the transaction.

{
  "type": "transaction",
  "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "status": "authentication_succeeded",
  "amount": 1299,
  "currency": "AUD",
  "payment_method": {
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "method": "card",
    "scheme": "visa",
    "expiration_date": "07/24",
    ...
  },
  ...
}

3-D Secure with a stored card

Native 3-D Secure in Secure Fields also works with a stored card. Secure Fields runs 3-D Secure against the checkout session, which uses the stored card.

Create a checkout session with the transaction context, as described in Secure Fields and 3DS.
Initialize Secure Fields with the paymentMethod of the stored card, as described in collect the CVV.
Add the 3-D Secure component, as described in initialization.
Call submit(). Secure Fields runs 3-D Secure and fires the start and finish events.
Create a transaction with the checkout session.

If you don’t use Secure Fields, use hosted 3-D Secure instead.

Get started

Integration guides

Best Practices

Resources

Features

Other

Secure Fields with stored cards

1. Store card for future use

2. Collect the CVV

3. Create a transaction

3-D Secure with a stored card

​1. Store card for future use

​2. Collect the CVV

​3. Create a transaction

​3-D Secure with a stored card

1. Store card for future use

2. Collect the CVV

3. Create a transaction

3-D Secure with a stored card