Build your own payment form

Learn how to collect a shopper's payment details using your own payment form.


Before you can make a payment with our API integration, you need to collect any required payment details from your shopper. Here we describe how to do this by building your own payment form.

Building your own form gives you full control over the look and feel of your checkout. If you'd rather not build your own payment form, you can also collect the shopper's payment details using our pre-built JavaScript Components. These are available for many popular payment methods.

This guide assumes that you've already completed Step 1 of our API integration guide, and have presented a list of payment methods to the shopper.

To collect payment details from the shopper, your payment form can be either:

  • Hard-coded: After making a /paymentMethods call to determine the payment details you need to collect, you build a static form that collects them from the shopper.

    A hard-coded form is quicker to implement, but the payment details you need to collect from a shopper can change. You should regularly poll the /paymentMethods endpoint to check for any updates to required payment details. We recommend this approach if you're only working with a small number of payment methods or countries.

  • Dynamically generated: For each transaction, you make a /paymentMethods call to determine the payment details you need to collect. Then use the response to generate a form that collects them from the shopper.

    This takes more time to implement, but ensures that the required payment details you collect from the shopper are up-to-date.

After you decide which form you will build, follow the steps below to:

  1. Determine which shopper details you need to collect in your form. These are different for each payment method.
  2. Integrate Secured Fields. Secured Fields is our JavaScript library that you can use to collect and encrypt sensitive credit card details.

Step 1: Determine required shopper details

To determine what payment details you need to collect from the shopper:

  1. Make /paymentMethods call, providing:

    • countryCode: The shopper's country.
    • amount: The currency and value of the payment. 
    curl https://checkout-test.adyen.com/v41/paymentMethods \
    -H "X-API-key: [Your API Key here]" \
    -H "Content-Type: application/json" \
    -d '{
      "merchantAccount": "YourMerchantAccount",
      "countryCode": "NL",
      "amount": {
        "currency": "EUR",
        "value": 1000
      }
    }'
    # 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.payment_methods({
      :merchantAccount => 'YourMerchantAccount',
      :countryCode => 'NL',
      :amount => {
        :currency => 'EUR',
        :value => 1000
      }
    })
    // 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);
    PaymentMethodsRequest paymentMethodsRequest = new PaymentMethodsRequest();
    paymentMethodsRequest.setMerchantAccount("YourMerchantAccount");
    paymentMethodsRequest.setCountryCode("NL");
    Amount amount = new Amount();
    amount.setCurrency("EUR");
    amount.setValue(1000L);
    paymentMethodsRequest.setAmount(amount);
    PaymentMethodsResponse response = checkout.paymentMethods(paymentMethodsRequest);
    // 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(
      "merchantAccount" => "YourMerchantAccount",
      "countryCode" => "NL",
      "amount" => array(
        "currency" => "EUR",
        "value" => 1000
    );
    $result = $service->paymentMethods($params);

    A list of available paymentMethods will be returned in the response. Most of these will have a details array. 

    {
      "paymentMethods":[
        {
          "details":[{
              "key":"encryptedCardNumber",
              "type":"cardToken"
            },{
              "key":"encryptedExpiryMonth",
              "type":"cardToken"
            },{
              "key":"encryptedExpiryYear",
              "type":"cardToken"
            },{
              "key":"encryptedSecurityCode",
              "type":"cardToken"
            }
          ],
          "name":"Credit Card",
          "type":"scheme"
        },{
          "details":[{
              "key":"sepa.ownerName",
              "type":"text"
            },{
              "key":"sepa.ibanNumber",
              "type":"text"
            }
          ],
          "name":"SEPA Direct Debit",
          "type":"sepadirectdebit"
        },
        ...
      ]
    }
  2. Use the details array of each payment method to determine what you need to collect from the shopper:

    • key: Shopper detail you need to collect using your payments form.
    • type: Input type for collecting the payment detail from the shopper:

      Type Description
      cardToken Value that represents encrypted card data. Generate these values using our Secured Fields JavaScript library.
      emailAddress Email address.
      radio Radio buttons displaying the options specified within the items array.
      select A list displaying the options specified within the items array. Present each name in this array to the shopper.
      tel Telephone number.
      text Generic string.

    If a payment method does not have a details array, you do not need to collect any shopper details in your form.

    In the example below, for SEPA Direct Debit, you'd use text fields to collect:

    • sepa.ownerName: Name on the shopper's bank account.

    • sepa.ibanNumber: IBAN number of this account.
    /paymentMethods response
    {
      "paymentMethods":[
        ...
          {
          "details":[{
              "key":"sepa.ownerName",
              "type":"text"
            },{
              "key":"sepa.ibanNumber",
              "type":"text"
            }
          ],
          "name":"SEPA Direct Debit",
          "type":"sepadirectdebit"
        },
        ...
      ]
    }

Step 2: Collect shopper details with Secured Fields

Secured Fields is our JavaScript library that you can use to securely collect and encrypt your shopper's credit card details.

When the shopper enters their card details on your website, Secured Fields collects the sensitive data, and creates an encrypted version that you can safely transmit when you make the payment.

If you are PCI Level 1 or 2 certified you can alternatively collect and submit raw card data. See Collecting raw card data for more information.

To integrate Secured Fields in your payment form:

  1. Include the following script in the <head> of your payments page:

    <script type="text/javascript" src="https://checkoutshopper-test.adyen.com/checkoutshopper/assets/js/sdk/checkoutSecuredFields.1.5.0.min.js"></script>

    This will embed the Secured Fields library.

  2. Insert a <div> in the <body> of your payments page, with the following data-cse elements:

    • encryptedCardNumber: Card number.

    • For card expiration:
      • Collect as separate fields:
        • encryptedExpiryMonth: Card expiry month.

        • encryptedExpiryYear: Card expiry year.

      • Collect as a single field:
        • encryptedExpiryDate: Card expiry for both month and year.
    • encryptedSecurityCode: Card security code.
    <div class="cards-div">
    
        <div class="js-chckt-pm__pm-holder">
           <input type="hidden" name="txvariant" value="card" />
           <label>
               <span class="input-field" data-cse="encryptedCardNumber" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedExpiryMonth" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedExpiryYear" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedSecurityCode" />
           </label>
        </div>
    </div>

    These will render as iframes, where the shopper can securely enter their card details. 

  3. Add the following code to the bottom of the  <body>, specifying:

    <script type="text/javascript">
       var csfSetupObj = {
    	  rootNode: '.cards-div',
    	  configObject : {
    		originKey : "YOUR_ORIGIN_KEY"
            }
       };
       var securedFields = csf(csfSetupObj);
      </script>
  4. When the shopper enters their card details, Secured Fields will perform validation on the card details. When the shopper submits the payment, their card details are replaced by encrypted values. These are added to hidden <input> fields in the <div> that holds the data-cse elements. 

    <div id="pmHolder" class="js-chckt-pm__pm-holder">
    	<input type="hidden" name="txvariant" value="card">
        ...        
    	<input type="hidden" name="encryptedExpiryMonth" id="card-encrypted-month" value="adyenjs_0_1_18$MT6ppy0FAMVMLH...">
    	...
    </div>
  5. Loop through and collect the encrypted card details from the corresponding data-cse values. You'll use these to make the payment.

To configure how Secured Fields render in your payment form, see Configure Secured Fields.

Next steps

Make a payment

Make a payment with the shopper's payment details.

link

Add payment methods

Learn about payment methods and how to integrate them.

link