Creating tokens

Save a shopper's payment method with Adyen.

Overview

Tokens are created as a result of submitting a payment request that successfully authorizes. This ensures that the payment details correspond to an active account and are chargeable. 

For card payments, you have the choice to submit the payment with an amount of 0 (zero-value authorization). The card details will be validated but the shopper's account will not show a charge.

When tokenizing a shopper's payment method, you will need to include a unique id for the shopper, called a shopperReference. This id is provided by you and acts as the container for that shopper's tokenized payment methods. All tokens are stored underneath a shopper. The shopperReference will be stored upon the first successful token creation.

You can store maximum 50 payment details associated with the same shopperReference value.

The tokenized payment detail is called a recurringDetailReference. You will use both the shopperReference and the associated recurringDetailReference in order to make future payments.

Tokenize with an authorization

If you are tokenizing shopper details collected by our SDKs, refer to the Web SDK, iOS SDK, or Android SDK pages for tokenization steps.

  1. Make a normal /payments request and include the following values:

    • shopperReference: your unique id for the shopper.
    • paymentMethod.storeDetails as true.

    You can tokenize card information using the Secured Fields or submitting the raw card data. This example uses raw card information with the /payments call.

    Specifying an amount of 0 will ensure the card information is validated but a charge isn't made on this card.

    curl https://checkout-test.adyen.com/v40/payments \
    -H "X-API-key: [Your API Key here]" \
    -H "Content-Type: application/json" \
    -d '{
       "amount":{
          "value":0,
          "currency":"USD"
       },
       "paymentMethod":{
          "type":"scheme",
          "number":"4111111111111111",
          "expiryMonth":"10",
          "expiryYear":"2020",
          "cvc":"737",
          "holderName":"John Smith",
          "storeDetails":true
       },
       "reference":"Your order number",
       "merchantAccount":"TestMerchant",
       "shopperReference":"yourShopperId_IOfW3k9G2PvXFu2j",
       "returnUrl":"https://your-company.com/..."
    }'
    # Set your X-API-KEY with the API key from the Customer Area.
    adyen = Adyen::Client.new
    adyen.api_key = "YOUR X-API-KEY"
     
    response = adyen.checkout.payments({
      :amount => {
        :currency => "USD",
        :value => 0
      },
      :reference => "Your order number",
      :paymentMethod => {
        :type => "scheme",
        :number => "4111111111111111",
        :expiryMonth => "10",
        :expiryYear => "2020",
        :cvc => "737",
        :storeDetails => true
      },
      :shopperReference => "yourShopperId_IOfW3k9G2PvXFu2j",
      :returnUrl => "https://your-company.com/...",
      :merchantAccount => "YourMerchantAccount"
    })
    // Set your X-API-KEY with the API key from the Customer Area.
    Config config = new Config();
    config.setApiKey("Your X-API-KEY"));
    Client client = new Client(config);
     
    Checkout checkout = new Checkout(client);
    PaymentsRequest paymentsRequest = new PaymentsRequest();
    Amount amount = new Amount();
    amount.setCurrency("USD");
    amount.setValue(0L);
    paymentsRequest.setAmount(amount);
    paymentsRequest.setReference("Your order number");
    paymentsRequest.setPaymentMethod(new HashMap<String, String>());
    paymentsRequest.putPaymentMethodItem("type","scheme");
    paymentsRequest.putPaymentMethodItem("number", "4111111111111111");
    paymentsRequest.putPaymentMethodItem("expiryMonth", "10");
    paymentsRequest.putPaymentMethodItem("expiryYear", "2020");
    paymentsRequest.putPaymentMethodItem("cvc", "737");
    paymentsRequest.putPaymentMethodItem("storeDetails", "true");
    paymentsRequest.setShopperReference("yourShopperId_IOfW3k9G2PvXFu2j");
    paymentsRequest.setReturnUrl("https://your-company.com/...");
    paymentsRequest.setMerchantAccount("YourMerchantAccount");
    PaymentsResponse response = checkout.payments(paymentsRequest);
    // Set your X-API-KEY with the API key from the Customer Area.
    $client = new \Adyen\Client();
    $client->setXApiKey("YOUR X-API-KEY");
    $service = new \Adyen\Service\Checkout($client);
    
    $params = array(
      "amount" => array(
        "currency" => "USD",
        "value" => 0
      ),
      "reference" => "Your order number",
      "paymentMethod" => array(
        "type" => "scheme",
        "number" => "4111111111111111",
        "expiryMonth" => "10",
        "expiryYear" => "2020",
        "cvc" => "737",
        "holderName" => "John Smith",
        "storeDetails" => true
      ),
      "returnUrl" => "https://your-company.com/checkout/",
      "merchantAccount" => "YourMerchantAccount",
      "reference" => "Your Reference Here",
      "shopperReference" => "yourShopperId_IOfW3k9G2PvXFu2j",
      "returnUrl" => "https://your-company.com/..."
    );
    $result = $service->payments($params);

    If the payment is successful, the resultCode will be Authorised, the payment detail will be tokenized, and a recurringDetailReference will be returned in the response.

    The recurringDetailReference is not returned synchronously by default. Reach out to Support Team to enable synchronous tokens.

    {
       "pspReference":"8814689190961342",
       "resultCode":"Authorised",
       "authCode":"83152",
       "additionalData":{
          "recurring.recurringDetailReference":"7219687191761347", 
          "recurring.shopperReference": "yourShopperId_IOfW3k9G2PvXFu2j"
       }
    }
  2. Save the recurringDetailReference. You will use the recurringDetailReference and the originally provided shopperReference to make future payments.

Pending and Refusal result codes

For some payment methods, you might not receive an Authorised immediately and instead receive a Pending status. In these cases, the payment details have not yet been tokenized. Instead, they will be tokenized once the payment as reached the Authorised status. You will receive this updated status via a webhook from our Notification service.

If you receive a resultCode with Refused, then the details were not tokenized and you need to submit another payment request in order to try tokenizing again.

Next steps

Make a payment

Use tokenized payment information for recurring and subscription payments.

link

Manage tokens

Retrieve, update, and disable tokens you stored with Adyen.

link