API only with encrypted card data

To ensure PCI compliance when you build your own cards payment form, use our client-side solutions to help encrypt card details.

Before you begin

Before starting your integration:

1. Make sure that you have set up your server-side implementation.
2. Add the cards that you want to support in your test Customer Area.

Show the available cards in your payment form

Specify in your /paymentMethods request a combination of countryCode and amount.currency, and use the /paymentMethods response to determine which cards are available to the shopper. For more information, refer to our API-only integration guide.

Next, use our client-side solutions to validate and encrypt your shopper's card details. Select the platform below:

Make a payment

From your server, make a POST /payments request, specifying:

• paymentMethod: Object that contains the encrypted card details from the client side, the card holder's name (if you collected it), and a type parameter set to scheme.

The /payments response contains:

• pspReference: Our unique identifier for the transaction.
• resultCode: Use this to present the payment result to your shopper.
• merchantReference: The reference from the /payments request.
• additionalData: Additional information about the transaction.
  To specify the fields that you want to receive in additionalData, log in to your Customer Area, and go to Developers > Additional data.

Present the payment result

Use the  resultCode from the /payments response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a webhook.

For card payments, you can receive the following resultCode values:

resultCode	Description	Action to take
Authorised	The payment was successful.	Inform the shopper that the payment has been successful. If you are using manual capture, you also need to capture the payment.
Cancelled	The shopper cancelled the payment.	Ask the shopper whether they want to continue with the order, or ask them to select a different payment method.
Error	There was an error when the payment was being processed. For more information, check the refusalReason field.	Inform the shopper that there was an error processing their payment.
Refused	The payment was refused. For more information, check the refusalReason field.	Ask the shopper to try the payment again using a different payment method.

Showing co-badged cards

Regulatory guidelines for some regions require the following:

• When a shopper presents a co-badged card, they must be allowed to select their preferred brand.
• If the shopper selected a preferred brand, the payment must be completed with this brand.

To comply with these guidelines:

1. Use the onBinLookup event to detect if a card is co-badged.
2. If a card is co-badged, present all supported brands to the shopper, allowing them to click on the brand they want to pay with. Each of the presented brands should have an alt or a data-value attribute.
3. If the shopper makes a choice, pass the corresponding event to the dualBrandingChangeHandler function.
   The shopper's selected brand will then be included in the state.data from the Component.

The following example shows how to present brand logos for a co-badged Bancontact/Maestro card:

function onBinLookup(pCallbackObj) {
    // Handle a dual branded result
    if (pCallbackObj.supportedBrandsRaw?.length > 1) {
        onDualBrand(pCallbackObj);
    }
}
// Implement dual branding
function onDualBrand(pCallbackObj) {
  const logoOne = document.getElementById('pmImageDual1');
  const logoTwo = document.getElementById('pmImageDual2');
  const supportedBrands = pCallbackObj.supportedBrandsRaw;

  //Set one brand icon, add alt or data-value attributes; add an event listener
  logoOne.setAttribute('src', supportedBrands[0].brandImageUrl);
  logoOne.setAttribute('alt', supportedBrands[0].brand);
  logoOne.setAttribute('data-value', supportedBrands[0].brand);
  logoOne.addEventListener('click', dualBrandListener);

  // Set the other brand icon, add alt or data-value attributes; add an event listener
  logoTwo.setAttribute('src', supportedBrands[1].brandImageUrl);
  logoTwo.setAttribute('alt', supportedBrands[1].brand);
  logoTwo.setAttribute('data-value', supportedBrands[1].brand);
  logoTwo.addEventListener('click', dualBrandListener);
}

Implementing dualBrandListener to pass the selected attributes to to dualBrandingChangeHandler:

function dualBrandListener(e) {
    securedFields.dualBrandingChangeHandler(e);
}

Present debit and credit cards separately

In some scenarios, you may want to present your shoppers with separate payment forms for debit cards and credit cards. Some examples include:

• If you accept payments in Sweden, you need to present debit cards before credit cards in order to comply with local legislation.
• In Brazil, many shoppers use Combo cards, allowing for both debit and credit transactions. Having a separate form for Debit Card and Credit Card gives your shoppers a clear indication of whether they are making a debit or credit transaction.

For more details, see the corresponding sections about Brazil and Sweden.

To show debit and credit cards separately:

1. If you're using the /paymentMethods endpoint to get a list of payment methods to present on the client side, include:

   • splitCardFundingSources: Set this to true to receive separate objects for credit and debit cards in the response.
     
     

   The following example shows how to get the available payment methods for a shopper in the Netherlands, making a EUR 47.00 payment.

   The response includes the list of available payment methods, with debit and credit cards split into separate objects.

2. When the shopper selects to pay with either a debit or credit card, proceed to make a POST /payments request and include:

   • paymentMethod.fundingSource: Set this to either credit or debit.
     
     

   The following example shows how you can make a payment request for a debit card.

Brazil

For debit transactions, we highly recommend using 3D Secure and Automatic Capture due to some issuers' restrictions.

Sweden

When accepting payments in Sweden, present debit before credit cards, and label the forms clearly in order to comply with Swedish legislations.

Stored card payments

Adyen's tokenization service allows you to securely store shopper's card details for recurring payments. To make recurring payments, you first need to create a shopper token, and then use the token to make future payments for the shopper.

Create a token

To store shopper's card details, include in your /payments request:

• storePaymentMethod: true
• shopperReference: Your unique identifier for the shopper.
• recurringProcessingModel: Defines the recurring payment type.

The /payments response contains:

• recurringDetailReference: This is the token that you'll need to make recurring payments for this shopper.

Show a stored card in your payment form

1. To get the stored payment methods for a shopper, include in your /paymentMethods request:

   • shopperReference: The unique shopper identifier that you specified when creating the token.

     The /paymentMethods response includes a storedPaymentMethods array containing the stored payment methods for this shopper. The storedPaymentMethods array contains the id that you need when making the payment.

   If your Components version is 3.2.0 or lower, use the oneClickPaymentMethods array and the recurringDetailReference instead.

            {
            ...
            "storedPaymentMethods":[
                {
                   "brand":"visa",
                   "expiryMonth":"10",
                   "expiryYear":"2020",
                   "holderName":"John Smith",
                   "id":"8415718415172204",
                   "lastFour":"1111",
                   "name":"VISA",
                   "supportedShopperInteractions":[
                      "Ecommerce",
                      "ContAuth"
                   ],
                   "type":"scheme"
                },
                {
                   "brand":"visa",
                   "expiryMonth":"08",
                   "expiryYear":"2018",
                   "holderName":"John Smith",
                   "id":"8315720121476805",
                   "lastFour":"0008",
                   "name":"VISA",
                   "supportedShopperInteractions":[
                      "ContAuth",
                      "Ecommerce"
                   ],
                   "type":"scheme"
                }
   ]
            ...
            }

2. Use the Custom Card Component to collect the following details from the shopper:

   Card details	Example input
   The security code (CVV / CVC)	"737"

   When onSubmit callback is triggered and if state.isValid is true, get the encrypted values from state.data and pass these values to your server.

3. Proceed to submit a payment request from your server.

Make a payment with a token

When the shopper selects to pay, the Component calls the onSubmit event, which contains a state.data.

1. Pass the state.data to your server.

2. From your server, make a /payments request, specifying:

   • paymentMethod.storedPaymentMethodId: The id from the the /paymentMethods response. This is the recurringDetailReference that you received when creating the token.
   • paymentMethod.encryptedSecurityCode: The state.data.paymentMethod.encryptedSecurityCode from the onSubmit event.
   • shopperReference: The unique shopper identifier that you specified when creating the token.
   • shopperInteraction: ContAuth.
   • recurringProcessingModel: CardOnFile.

The /payments response contains:

• resultCode: Use this to inform the shopper about the payment status.

You can also use tokens to make shopper-not-present payments for subscriptions or contracts. For more information, refer to Making a payment for a subscription or contract.

Test and go live

If your client-side integration isn't ready, you can test API requests with encrypted card details by adding a test_ prefix to the test card details.

Before making live card payments:

1. Test your integration using our test card numbers. You can check the status of test payments in your Customer Area > Transactions > Payments.

2. Add the cards that you want to accept in your live Customer Area.

3. Before you can start accepting card payments in the live environment, you need to assess your PCI DSS compliance and submit the required Self-Assessment Questionnaire A document. For more information, refer to PCI DSS compliance guide.

See also