BIN data and card verification

You may want to verify card validity and BIN data, for example before a sale to apply credit/debit surcharges or promotional offers based on BIN codes.

Submit a BIN or card verification request

Submit an authorisation request with a currency value amounting to 0 (zero-value auth). The currency should match the eventual transaction currency.

A zero-value auth requests the Adyen payments platform to submit a card verification call to the acquirer. The call returns a resultCode whose value can be AuthorisedRefused or Error.

Not all acquirers and issuers support card verification through zero-value auth. When your transactions are routed to an acquirer or issuer that does not support this feature, the Adyen payments platform automatically submits a EUR 1 authorisation, which is immediately followed by an automatic authorisation cancellation. For other currencies, an approximate value equivalent to EUR 1 is used. For example, 1000 Korean Won (KRW), as 1 KRW is too low an amount to be authorised. In this case, the notification message you receive after the authorisation request includes the additionalAmount field to notify the amount used for the card verification (for example, 1000 Korean Won).

If you want to force a card verification request to use a non-zero value, you need to include the additionalAmount field to specify the amount to use. The standard amount field value still needs to be 0 (zero) to allow the Adyen payments platform to recognize the transaction as a non-zero amount validation, instead of an actual low-value transaction authorisation. This action triggers an automatic cancellation by the Adyen payments platform, following the authorisation. To be accepted by the schemes, the value specified in the additionalAmount field needs to be higher than the currency equivalent of 0.02 USD.

If a card issuer always requires 3D Secure to confirm every payment and also doesn't support zero-value authorisations (for example, Bancontact), Adyen can not automatically submit a EUR 1 authorisation instead of zero-value auth. In this case, you need to submit a non-zero value authorisation request.

Receive a BIN or card verification response

A zero-value auth response includes, among others, the following details:

  • The authorisation request outcome (successful/failed).
  • If the authorisation request failed, an error message is included in the response.

An additionalData container object can also be included. This can contain information such as the: 

  • cardBin field holding BIN information
  • authorisedAmountValue and authorisedAmountCurrency fields which hold the amount and currency of the authorisation

The additionalData object needs to be configured to include this data in the response. For more information, refer to this FAQ article.

After enabling it, you will be able to receive the PaymentResult.additionalData fields as child elements of the additionalData container object.

The system sends the information as a notification message following a zero-value auth request.

Code examples: Request

Examples of BIN data/card verification request (zero value authorisation):

{
    "card" : {
        "number" : "4111111111111111",
        "expiryMonth" : "8",
        "expiryYear" : "2018",
        "cvc" : "737",
        "holderName" : "Adyen Test"
    },
    
    "amount" : {
        "value" : 0,
        "currency" : "EUR"
    },
    
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "Simon Hopper"
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance">
  <soap:Body>
    <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
      <ns1:paymentRequest>
        <amount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">0</value>
        </amount>
        <card xmlns="http://payment.services.adyen.com">
          <cvc>737</cvc>
          <expiryMonth>08</expiryMonth>
          <expiryYear>2018</expiryYear>
          <holderName>Adyen Test</holderName>
          <number>4111111111111111</number>
        </card>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference>
        <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail>
        <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>
merchantAccount=TestMerchant&amount.value=0&card.expiryYear=2018&amount.currency=EUR&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=08&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com

Code examples: Request with additional amount

Examples of BIN data/card verification request (non-zero value authorisation) with additionalAmount:

{
    "card" : {
        "number" : "4111111111111111",
        "expiryMonth" : "8",
        "expiryYear" : "2018",
        "cvc" : "737",
        "holderName" : "Adyen Test"
    },
    
    "amount" : {
        "value" : 0,
        "currency" : "EUR"
    },

    "additionalAmount" : {
        "value" : 100,
        "currency" : "EUR"
    },
    
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "Simon Hopper"
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance">
  <soap:Body>
    <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
      <ns1:paymentRequest>
        <amount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">0</value>
        </amount>
        <additionalAmount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">100</value>
        </additionalAmount>
        <card xmlns="http://payment.services.adyen.com">
          <cvc>737</cvc>
          <expiryMonth>08</expiryMonth>
          <expiryYear>2018</expiryYear>
          <holderName>Adyen Test</holderName>
          <number>4111111111111111</number>
        </card>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference>
        <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail>
        <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>
merchantAccount=TestMerchant&amount.value=0&amount.currency=EUR&additionalAmount.value=100&additionalAmount.currency=EUR&card.expiryYear=2018&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=08&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com

Code examples: Response

Examples of JSON BIN data/card verification response (non-zero value authorisation) with additionalAmount:

{
   "additionalData":{
      "cardPaymentMethod":"amex",
      "cardIssuingBank":"American Express US Consumer",
      "cardIssuingCountry":"US",
      "cardIssuingCurrency":"USD",
      "cardBin":"373731",
      "authorisedAmountValue":"1000",
      "authorisedAmountCurrency":"EUR",
      "fundingSource":"CREDIT",
      "payoutEligible":"Y",
      "fundsAvailability":"I"
   },
   "pspReference":"9914229541655140",
   "refusalReason":"Acquirer Error",
   "resultCode":"Error"
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:authoriseResponse xmlns:ns1="http://payment.services.adyen.com">
      <ns1:paymentResult>
        <additionalData xmlns="http://payment.services.adyen.com">
          <entry>
            <key xsi:type="xsd:string">cardPaymentMethod</key>
            <value xsi:type="xsd:string">amex</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">cardIssuingBank</key>
            <value xsi:type="xsd:string">American Express US Consumer</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">cardIssuingCountry</key>
            <value xsi:type="xsd:string">US</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">cardIssuingCurrency</key>
            <value xsi:type="xsd:string">USD</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">cardBin</key>
            <value xsi:type="xsd:string">373731</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">authorisedAmountValue</key>
            <value xsi:type="xsd:string">1000</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">authorisedAmountCurrency</key>
            <value xsi:type="xsd:string">EUR</value>
          </entry>
		  <entry>
            <key xsi:type="xsd:string">fundingSource</key>
            <value xsi:type="xsd:string">CREDIT</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">payoutEligible</key>
            <value xsi:type="xsd:string">Y</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">fundsAvailability</key>
            <value xsi:type="xsd:string">I</value>
          </entry>
        </additionalData>
        <authCode xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
        <dccAmount xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
        <dccSignature xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
        <fraudResult xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
        <issuerUrl xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
        <md xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
        <paRequest xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
        <pspReference xmlns="http://payment.services.adyen.com">9914229541655140</pspReference>
        <refusalReason xmlns="http://payment.services.adyen.com">Acquirer Error</refusalReason>
        <resultCode xmlns="http://payment.services.adyen.com">Error</resultCode>
      </ns1:paymentResult>
    </ns1:authoriseResponse>
  </soap:Body>
</soap:Envelope>
additionalData.cardPaymentMethod=amex&additionalData.cardIssuingBank=American+Express+US+Consumer&additionalData.cardIssuingCountry=US&additionalData.cardIssuingCurrency=USD&additionalData.cardBin=373731&additionalData.authorisedAmountValue=1000&additionalData.authorisedAmountCurrency=EUR&additionalData.fundingSource=CREDIT&payoutEligible=Y&fundsAvailability=I&pspReference=9914229541655140&refusalReason=Acquirer+Error&resultCode=Error