Raw card data

Use our APIs to accept card payments with raw card data, and build your own UI to have full control over the look and feel of your checkout page.

Before you begin

These instructions explain how to add card payments to your existing API-only integration. The API-only integration works the same way for all payment methods. If you haven't done this integration yet, refer to our API-only integration guide.

Before starting your integration:

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

Build your payment form for cards

When making a card payment, collect the following shopper details:

Card details	Example input	Required
Card number	"4111111111111111"
Card expiry month	"03"
Card expiry year	"30"
Card security code (CVV / CVC)	"737"
Cardholder name	"S. Hopper"

Showing co-branded cards

For cards issued in Europe, EU IFR Regulation 2015/751 article 8 says that if a shopper uses a co-branded card, and you support both brands, you must let them choose the brand to pay with.

Use the /cardDetails endpoint to identify the brands on the shopper's card. To identify the brands, start making /cardDetails requests while the shopper is entering the card number. You need a minimum of the first 6 digits, but 11 digits give the best result.

If the /cardDetails endpoint identifies two brands and you support both, you must let the shopper choose which brand to pay with. If you only support one brand, let the shopper pay with it.

1. Make a POST /cardDetails request including the following:

   Parameter	Description	Required
   merchantAccount	Your merchant account.
   cardNumber	A minimum of the first 6 digits of the card number and a maximum of the full card number.
   countryCode	The shopper's two-character ISO-3166-1 alpha-2 country code.
   supportedBrands	The array of the card brands that you support. This is the brands array from your /paymentMethods response. If not provided, we assume that you support all card brands.

   /cardDetails request

   curl https://checkout-test.adyen.com/v69/cardDetails \
   -H "X-API-key: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
       "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
       "cardNumber": "40355014",
       "supportedBrands": ["visa", "mc", "amex"]
       }'

   https://docs.adyen.com/payment-methods/cards/raw-card-data#card-details-request

2. The response has a brands array containing the brands on the card. If you included supportedBrands in the request, the response shows the ones you support.

   The following example shows a response where:

   • The brands on the card are visa and cartebancaire.
   • The merchant account only supports visa.
   response to a request with supportedBrands

   {
      "brands": [
          {
              "type": "visa",
              "supported" : "true"
          },
          {
              "type": "cartebancaire",
              "supported" : "false"
          }
      ]
   }

   https://docs.adyen.com/payment-methods/cards/raw-card-data#response-to-a-request-with-supportedbrands

3. If you support both brands, you must let the shopper choose their preferred brand. Render brand logos and names in the payment form for the shopper to choose one and include the brand when making a payment.

Make a payment

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

Field	Description	Required
paymentMethod.type	scheme
paymentMethod.number	The card number (without separators).
paymentMethod.expiryMonth	The card expiry month.
paymentMethod.expiryYear	The card expiry year.
paymentMethod.cvc	The card verification code.
paymentMethod.holderName	The name of the cardholder.
paymentMethod.brand	If the card is co-branded, this is the brand that the shopper choose to pay with. This is the brands.type from the /cardDetails response that matches the shopper's preferred brand.

curl https://checkout-test.adyen.com/v68/payments \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
    "amount": {
      "currency": "USD",
      "value": 1000
    },
    "reference": "YOUR_ORDER_NUMBER",
    "paymentMethod": {
      "type": "scheme",
      "number": "4111111111111111",
      "expiryMonth": "10",
      "expiryYear": "2020",
      "cvc": "737",
      "holderName": "S. Hopper"
    },
    "returnUrl": "https://your-company.com/...",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
  }'

# 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 => 1000
  },
  :reference => "YOUR_ORDER_NUMBER",
  :paymentMethod => {
    :type => "scheme",
    :number => "4111111111111111",
    :expiryMonth => "10",
    :expiryYear => "2020",
    :cvc => "737",
    :holderName => "S. Hopper"
  },
  :returnUrl => "https://your-company.com/...",
  :merchantAccount => "YOUR_MERCHANT_ACCOUNT"
})

// Set your X-API-KEY with the API key from the Customer Area.
Client client = new Client(xApiKey,Environment.TEST);

Checkout checkout = new Checkout(client);
PaymentsRequest paymentsRequest = new PaymentsRequest();
paymentsRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
Amount amount = new Amount();
amount.setCurrency("USD");
amount.setValue(1000L);
paymentsRequest.setAmount(amount);
String number = "4111111111111111";
String expiryMonth = "10";
String expiryYear = "2020";
String cvc = "737";
String holderName = "S. Hopper";
paymentsRequest.setReference("YOUR_ORDER_NUMBER");
paymentsRequest.addCardData(number,expiryMonth, expiryYear, cvc, holderName);
paymentsRequest.setStorePaymentMethod(true);
paymentsRequest.setReturnUrl("https://your-company.com/...");
PaymentsResponse paymentsResponse = 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" => 1000
  ),
  "reference" => "YOUR_ORDER_NUMBER",
  "paymentMethod" => array(
    "type" => "scheme",
    "number" => "4111111111111111",
    "expiryMonth" => "10",
    "expiryYear" => "2020",
    "cvc" => "737",
    "holderName" => "S. Hopper"
  ),
  "returnUrl" => "https://your-company.com/...",
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->payments($params);

#Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

result = adyen.checkout.payments({
   'amount': {
      'value': 1000,
      'currency': 'USD'
   },
   'reference': 'YOUR_ORDER_NUMBER',
   'paymentMethod': {
      'type': 'scheme',
      'number': '4111111111111111',
      'expiryMonth': '10',
      'expiryYear': '2020',
      'cvc': '737',
      'holderName': 'S. Hopper'
   },
   'returnUrl': 'https://your-company.com/checkout/',
   'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
})

// Set your X-API-KEY with the API key from the Customer Area.
var client = new Client ("YOUR_X-API-KEY", Environment.Test);
var checkout = new Checkout(client);

var amount = new Adyen.Model.Checkout.Amount("USD", 1000);
var details = new CardDetails{
  Type = "scheme",
  Number = "4111111111111111",
  ExpiryMonth = "10",
  ExpiryYear = "2020",
  Cvc = "737",
  HolderName = "S. Hopper"
};
var paymentsRequest = new Adyen.Model.Checkout.PaymentRequest
{
  Reference = "YOUR_ORDER_NUMBER",
  Amount = amount,
  ReturnUrl = @"https://your-company.com/...",
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  PaymentMethod = details
};

var paymentResponse = checkout.Payments(paymentsRequest);

// Set your X-API-KEY with the API key from the Customer Area.
const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[API_KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
    amount: { currency: "USD", value: 1000 },
    paymentMethod: {
        type: 'scheme',
        number: "4111111111111111",
        expiryMonth: "10",
        expiryYear: "2020",
        cvc: "737",
        holderName: "S. Hopper"
    },
    reference: "YOUR_ORDER_NUMBER",
    merchantAccount: config.merchantAccount,
    returnUrl: "https://your-company.com/..."
}).then(res => res);

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 settings.

{
  "additionalData": {
    "cardSummary": "1111"
  },
  "pspReference": "851572424333194G",
  "resultCode": "Authorised",
  "merchantReference": "YOUR_ORDER_NUMBER"
}

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:

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 you would get the available payment methods for a shopper in the Netherlands, making a 47.00 EUR payment.

   /paymentMethods request

   curl https://checkout-test.adyen.com/v68/paymentMethods \
   -H "x-API-key: YOUR_X-API-KEY" \
   -H "content-type: application/json" \
   -d '{
     "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
     "countryCode": "NL",
     "amount": {
       "currency": "EUR",
       "value": 4700
     },
     "splitCardFundingSources": true
   }'

   https://docs.adyen.com/payment-methods/cards/raw-card-data#-paymentmethods-request

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

   Response

   {
      ...
      "paymentMethods": [
          {
              "brands": [
                  "mc",
                  "visa",
                  "amex"
              ],
              ...
              "fundingSource": "credit",
              "name": "Credit Card",
              "type": "scheme"
          },
          {
              "brands": [
                  "mc",
                  "visa",
                  "amex"
              ],
              "fundingSource": "debit",
              "name": "Debit Card",
              "type": "scheme"
          }
      ]
   }

   https://docs.adyen.com/payment-methods/cards/raw-card-data#response

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.

   /payments request

   curl https://checkout-test.adyen.com/v68/payments \
   -H "X-API-key: [Your API Key here]" \
   -H "Content-Type: application/json" \
   -d '{
     "amount":{
       "currency":"EUR",
       "value":4700
     },
     "reference":"YOUR_ORDER_NUMBER",
     "paymentMethod": {
       "type": "scheme",
       "number": "4111111111111111",
       "expiryMonth": "10",
       "expiryYear": "2020",
       "cvc": "737",
       "holderName": "S.Hopper",
       "fundingSource": "debit"
     },
     "returnUrl": "https://your-company.com/...",
     "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
   }'

   https://docs.adyen.com/payment-methods/cards/raw-card-data#-payments-request

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.

Recurring 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.

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. Collect the following card details from the shopper in your payment form:

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

3. Next, proceed to submit a payment request from your server.

Make a payment with a token

To make a payment with the token, include in your /payments request:

• paymentMethod.storedPaymentMethodId: The id from the the /paymentMethods response. This is the recurringDetailReference that you received when creating the token.
• paymentMethod.cvc: The security code that you collected from the shopper.
• shopperReference: The unique shopper identifier that you specified when creating the token.
• shopperInteraction: ContAuth.
• recurringProcessingModel: CardOnFile.

{
   "amount":{
      "currency":"USD",
      "value":1000
   },
   "reference":"YOUR_ORDER_NUMBER",
   "paymentMethod":{
      "type":"scheme",
      "storedPaymentMethodId":"8415718415172204",
      "cvc":"737"
   },
   "shopperReference":"YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
   "returnUrl":"https://your-company.com/...",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}

The /payments response contains:

• resultCode: Use this to present the payment result to your shopper.

{
   "pspReference": "8815329842815468",
   "resultCode": "Authorised"
}

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

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 D document. For more information, refer to PCI DSS compliance guide.

See also