Adyen BinLookup API
The BIN Lookup API provides endpoints for retrieving information, such as cost estimates, and 3D Secure supported version based on a given BIN.
OpenAPI Specification
openapi: 3.1.0
servers:
- url: https://pal-test.adyen.com/pal/servlet/BinLookup/v54
info:
version: '54'
x-publicVersion: true
title: Adyen BinLookup API
description: >-
The BIN Lookup API provides endpoints for retrieving information, such as
cost estimates, and 3D Secure supported version based on a given BIN.
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
tags:
- name: get3dsAvailability
- name: getCostEstimate
paths:
/get3dsAvailability:
post:
tags:
- get3dsAvailability
summary: Adyen Check if 3D Secure is Available
description: >-
Verifies whether 3D Secure is available for the specified BIN or card
brand. For 3D Secure 2, this endpoint also returns device fingerprinting
keys.
For more information, refer to [3D Secure
2](https://docs.adyen.com/online-payments/3d-secure/native-3ds2).
x-addedInVersion: '1'
operationId: post-get3dsAvailability
x-sortIndex: 0
x-methodName: get3dsAvailability
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
get3dsAvailability:
$ref: >-
#/components/examples/post-get3dsAvailability-get3dsAvailability
schema:
$ref: '#/components/schemas/ThreeDSAvailabilityRequest'
responses:
'200':
content:
application/json:
examples:
get3dsAvailability:
$ref: >-
#/components/examples/post-get3dsAvailability-get3dsAvailability-200
schema:
$ref: '#/components/schemas/ThreeDSAvailabilityResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-get3dsAvailability401Example:
summary: Default post-get3dsAvailability 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-get3dsAvailability403Example:
summary: Default post-get3dsAvailability 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-get3dsAvailability422Example:
summary: Default post-get3dsAvailability 422 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-get3dsAvailability500Example:
summary: Default post-get3dsAvailability 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/getCostEstimate:
post:
tags:
- getCostEstimate
summary: Adyen Get a Fees Cost Estimate
description: >-
>This API is available only for merchants operating in Australia, the
EU, and the UK.
Use the Adyen Cost Estimation API to pre-calculate interchange and
scheme fee costs. Knowing these costs prior actual payment authorisation
gives you an opportunity to charge those costs to the cardholder, if
necessary.
To retrieve this information, make the call to the `/getCostEstimate`
endpoint. The response to this call contains the amount of the
interchange and scheme fees charged by the network for this transaction,
and also which surcharging policy is possible (based on current
regulations).
> Since not all information is known in advance (for example, if the
cardholder will successfully authenticate via 3D Secure or if you also
plan to provide additional Level 2/3 data), the returned amounts are
based on a set of assumption criteria you define in the `assumptions`
parameter.
operationId: post-getCostEstimate
x-sortIndex: 0
x-methodName: getCostEstimate
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
getCostEstimate:
$ref: '#/components/examples/post-getCostEstimate-getCostEstimate'
getCostEstimateEncryptedCard:
$ref: >-
#/components/examples/post-getCostEstimate-getCostEstimateEncryptedCard
getCostEstimateMinimal:
$ref: >-
#/components/examples/post-getCostEstimate-getCostEstimateMinimal
getCostEstimateMinimal3DS:
$ref: >-
#/components/examples/post-getCostEstimate-getCostEstimateMinimal3DS
getCostEstimateRecurringContract:
$ref: >-
#/components/examples/post-getCostEstimate-getCostEstimateRecurringContract
schema:
$ref: '#/components/schemas/CostEstimateRequest'
responses:
'200':
content:
application/json:
examples:
getCostEstimate:
$ref: >-
#/components/examples/post-getCostEstimate-getCostEstimate-200
getCostEstimateEncryptedCard:
$ref: >-
#/components/examples/post-getCostEstimate-getCostEstimateEncryptedCard-200
getCostEstimateMinimal:
$ref: >-
#/components/examples/post-getCostEstimate-getCostEstimateMinimal-200
getCostEstimateMinimal3DS:
$ref: >-
#/components/examples/post-getCostEstimate-getCostEstimateMinimal3DS-200
schema:
$ref: '#/components/schemas/CostEstimateResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getCostEstimate401Example:
summary: Default post-getCostEstimate 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getCostEstimate403Example:
summary: Default post-getCostEstimate 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getCostEstimate422Example:
summary: Default post-getCostEstimate 422 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-getCostEstimate500Example:
summary: Default post-getCostEstimate 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
Amount:
properties:
currency:
description: >-
The three-character [ISO currency
code](https://docs.adyen.com/development-resources/currency-codes).
maxLength: 3
minLength: 3
type: string
value:
description: >-
The amount of the transaction, in [minor
units](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
- value
- currency
type: object
BinDetail:
properties:
issuerCountry:
description: The country where the card was issued.
type: string
type: object
CardBin:
properties:
bin:
description: >-
The first 6 digit of the card number. Enable this field via merchant
account settings.
type: string
commercial:
description: >-
If true, it indicates a commercial card. Enable this field via
merchant account settings.
type: boolean
fundingSource:
description: |-
The card funding source. Valid values are:
* CHARGE
* CREDIT
* DEBIT
* DEFERRED_DEBIT
* PREPAID
* PREPAID_RELOADABLE
* PREPAID_NONRELOADABLE
> Enable this field via merchant account settings.
type: string
fundsAvailability:
description: >-
Indicates availability of funds.
Visa:
* "I" (fast funds are supported)
* "N" (otherwise)
Mastercard:
* "I" (product type is Prepaid or Debit, or issuing country is in
CEE/HGEM list)
* "N" (otherwise)
> Returned when you verify a card BIN or estimate costs, and only if
`payoutEligible` is different from "N" or "U".
type: string
issuerBin:
x-addedInVersion: '54'
description: >-
The first 8 digit of the card number. Enable this field via merchant
account settings.
type: string
issuingBank:
description: The issuing bank of the card.
type: string
issuingCountry:
description: The country where the card was issued from.
type: string
issuingCurrency:
description: The currency of the card.
type: string
paymentMethod:
description: >-
The payment method associated with the card (e.g. visa, mc, or
amex).
type: string
payoutEligible:
description: >-
Indicates whether a payout is eligible or not for this card.
Visa:
* "Y"
* "N"
Mastercard:
* "Y" (domestic and cross-border)
* "D" (only domestic)
* "N" (no MoneySend)
* "U" (unknown)
> Returned when you verify a card BIN or estimate costs, and only if
`payoutEligible` is different from "N" or "U".
type: string
summary:
description: The last four digits of the card number.
type: string
type: object
CostEstimateAssumptions:
properties:
assume3DSecureAuthenticated:
description: >-
If true, the cardholder is expected to successfully authorise via 3D
Secure.
type: boolean
assumeLevel3Data:
description: If true, the transaction is expected to have valid Level 3 data.
type: boolean
installments:
description: If not zero, the number of installments.
format: int32
type: integer
type: object
CostEstimateRequest:
properties:
amount:
description: The transaction amount used as a base for the cost estimation.
$ref: '#/components/schemas/Amount'
assumptions:
description: >-
Assumptions made for the expected characteristics of the
transaction, for which the charges are being estimated.
$ref: '#/components/schemas/CostEstimateAssumptions'
cardNumber:
description: >-
The card number (4-19 characters) for PCI compliant use cases. Do
not use any separators.
> Either the `cardNumber` or `encryptedCardNumber` field must be
provided in a payment request.
maxLength: 19
minLength: 4
type: string
encryptedCardNumber:
description: >-
Encrypted data that stores card information for non PCI-compliant
use cases. The encrypted data must be created with the Checkout Card
Component or Secured Fields Component, and must contain the
`encryptedCardNumber` field.
> Either the `cardNumber` or `encryptedCardNumber` field must be
provided in a payment request.
type: string
merchantAccount:
description: >-
The merchant account identifier you want to process the
(transaction) request with.
type: string
merchantDetails:
description: >-
Additional data for merchants who don't use Adyen as the payment
authorisation gateway.
$ref: '#/components/schemas/MerchantDetails'
recurring:
description: >-
The recurring settings for the payment. Use this property when you
want to enable [recurring
payments](https://docs.adyen.com/online-payments/tokenization).
$ref: '#/components/schemas/Recurring'
selectedRecurringDetailReference:
description: >-
The `recurringDetailReference` you want to use for this cost
estimate. The value `LATEST` can be used to select the most recently
stored recurring detail.
type: string
shopperInteraction:
description: >-
Specifies the sales channel, through which the shopper gives their
card details, and whether the shopper is a returning customer.
For the web service API, Adyen assumes Ecommerce shopper interaction
by default.
This field has the following possible values:
* `Ecommerce` - Online transactions where the cardholder is present
(online). For better authorisation rates, we recommend sending the
card security code (CSC) along with the request.
* `ContAuth` - Card on file and/or subscription transactions, where
the card holder is known to the merchant (returning customer). If
the shopper is present (online), you can supply also the CSC to
improve authorisation (one-click payment).
* `Moto` - Mail-order and telephone-order transactions where the
shopper is in contact with the merchant via email or telephone.
* `POS` - Point-of-sale transactions where the shopper is physically
present to make a payment using a secure payment terminal.
enum:
- Ecommerce
- ContAuth
- Moto
- POS
type: string
shopperReference:
description: >-
Required for recurring payments.
Your reference to uniquely identify this shopper, for example user
ID or account ID. Minimum length: 3 characters.
> Your reference must not include personally identifiable
information (PII), for example name or email address.
type: string
required:
- amount
- merchantAccount
type: object
CostEstimateResponse:
properties:
cardBin:
description: Card BIN details.
$ref: '#/components/schemas/CardBin'
costEstimateAmount:
description: >-
The estimated cost (scheme fee + interchange) in the settlement
currency. If the settlement currency cannot be determined, the fee
in EUR is returned.
$ref: '#/components/schemas/Amount'
costEstimateReference:
x-addedInVersion: '52'
description: Adyen's 16-character reference associated with the request.
type: string
resultCode:
description: The result of the cost estimation.
type: string
surchargeType:
description: >-
Indicates the way the charges can be passed on to the cardholder.
The following values are possible:
* `ZERO` - the charges are not allowed to pass on
* `PASSTHROUGH` - the charges can be passed on
* `UNLIMITED` - there is no limit on how much surcharge is passed on
type: string
type: object
DSPublicKeyDetail:
properties:
brand:
description: Card brand.
type: string
directoryServerId:
description: Directory Server (DS) identifier.
type: string
fromSDKVersion:
description: >-
The version of the mobile 3D Secure 2 SDK. For the possible values,
refer to the versions in [Adyen 3DS2
Android](https://github.com/Adyen/adyen-3ds2-android/releases) and
[Adyen 3DS2 iOS](https://github.com/Adyen/adyen-3ds2-ios/releases).
type: string
publicKey:
description: >-
Public key. The 3D Secure 2 SDK encrypts the device information by
using the DS public key.
format: byte
type: string
rootCertificates:
description: >-
Directory Server root certificates. The 3D Secure 2 SDK verifies the
ACS signed content using the rootCertificates.
type: string
type: object
MerchantDetails:
properties:
countryCode:
description: >-
2-letter ISO 3166 country code of the card acceptor location.
> This parameter is required for the merchants who don't use Adyen
as the payment authorisation gateway.
maxLength: 2
minLength: 2
type: string
enrolledIn3DSecure:
description: >-
If true, indicates that the merchant is enrolled in 3D Secure for
the card network.
type: boolean
mcc:
description: >-
The merchant category code (MCC) is a four-digit number which
relates to a particular market segment. This code reflects the
predominant activity that is conducted by the merchant.
The list of MCCs can be found
[here](https://en.wikipedia.org/wiki/Merchant_category_code).
type: string
type: object
Recurring:
properties:
contract:
description: >-
The type of recurring contract to be used.
Possible values:
* `ONECLICK` – Payment details can be used to initiate a one-click
payment, where the shopper enters the [card security code
(CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).
* `RECURRING` – Payment details can be used without the card
security code to initiate [card-not-present
transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).
* `ONECLICK,RECURRING` – Payment details can be used regardless of
whether the shopper is on your site or not.
* `PAYOUT` – Payment details can be used to [make a
payout](https://docs.adyen.com/online-payments/online-payouts).
enum:
- ONECLICK
- RECURRING
- PAYOUT
type: string
recurringDetailName:
description: A descriptive name for this detail.
type: string
recurringExpiry:
x-addedInVersion: '40'
description: >-
Date after which no further authorisations shall be performed. Only
for 3D Secure 2.
format: date-time
type: string
recurringFrequency:
x-addedInVersion: '40'
description: Minimum number of days between authorisations. Only for 3D Secure 2.
type: string
tokenService:
x-addedInVersion: '25'
description: The name of the token service.
enum:
- VISATOKENSERVICE
- MCTOKENSERVICE
- AMEXTOKENSERVICE
- TOKEN_SHARING
type: string
type: object
ServiceError:
properties:
additionalData:
x-addedInVersion: '46'
additionalProperties:
type: string
description: >-
Contains additional information about the payment. Some data fields
are included only if you select them first. Go to **Customer Area**
> **Developers** > **Additional data**.
type: object
errorCode:
description: The error code mapped to the error message.
type: string
errorType:
description: The category of the error.
type: string
message:
description: A short explanation of the issue.
type: string
pspReference:
description: The PSP reference of the payment.
type: string
status:
description: The HTTP response status.
format: int32
type: integer
type: object
ThreeDS2CardRangeDetail:
properties:
acsInfoInd:
x-addedInVersion: '51'
description: |-
Provides additional information to the 3DS Server.
Possible values:
- 01 (Authentication is available at ACS)
- 02 (Attempts supported by ACS or DS)
- 03 (Decoupled authentication supported)
- 04 (Whitelisting supported)
items:
type: string
type: array
brandCode:
description: Card brand.
type: string
endRange:
description: BIN end range.
type: string
startRange:
description: BIN start range.
type: string
threeDS2Versions:
x-addedInVersion: '53'
description: Supported 3D Secure protocol versions
items:
type: string
type: array
threeDSMethodURL:
description: >-
In a 3D Secure 2 browser-based flow, this is the URL where you
should send the device fingerprint to.
type: string
type: object
ThreeDSAvailabilityRequest:
properties:
additionalData:
additionalProperties:
type: string
description: >-
This field contains additional data, which may be required for a
particular request.
The `additionalData` object consists of entries, each of which
includes the key and value.
type: object
brands:
description: List of brands.
items:
type: string
type: array
cardNumber:
description: Card number or BIN.
type: string
merchantAccount:
description: The merchant account identifier.
type: string
recurringDetailReference:
description: A recurring detail reference corresponding to a card.
type: string
shopperReference:
description: >-
The shopper's reference to uniquely identify this shopper (e.g. user
ID or account ID).
type: string
required:
- merchantAccount
type: object
ThreeDSAvailabilityResponse:
properties:
binDetails:
x-addedInVersion: '50'
description: Bin Group Details
$ref: '#/components/schemas/BinDetail'
dsPublicKeys:
description: List of Directory Server (DS) public keys.
items:
$ref: '#/components/schemas/DSPublicKeyDetail'
type: array
threeDS1Supported:
description: Indicator if 3D Secure 1 is supported.
type: boolean
threeDS2CardRangeDetails:
description: List of brand and card range pairs.
items:
$ref: '#/components/schemas/ThreeDS2CardRangeDetail'
type: array
threeDS2supported:
description: Indicator if 3D Secure 2 is supported.
type: boolean
type: object
securitySchemes:
ApiKeyAuth:
in: header
name: X-API-Key
type: apiKey
BasicAuth:
scheme: basic
type: http
examples:
generic-400:
summary: Response code 400. Bad Request.
value:
status: 400
errorCode: '702'
message: 'Unexpected input: I'
errorType: validation
post-get3dsAvailability-get3dsAvailability:
summary: Get 3D Secure availability
description: Example request to check 3D Secure availability
value:
merchantAccount: YOUR_MERCHANT_ACCOUNT
cardNumber: '4111111111111111'
post-get3dsAvailability-get3dsAvailability-200:
summary: Example response for request 'get3dsAvailability'
value:
threeDS1Supported: true
threeDS2CardRangeDetails: []
threeDS2supported: false
post-getCostEstimate-getCostEstimate:
summary: Estimate the transaction cost
description: Example request to get the estimated cost of a transaction
value:
amount:
value: 1234
currency: EUR
assumptions:
assumeLevel3Data: true
assume3DSecureAuthenticated: true
cardNumber: '5101180000000007'
merchantAccount: YOUR_MERCHANT_ACCOUNT
merchantDetails:
countryCode: NL
mcc: '7411'
enrolledIn3DSecure: true
shopperInteraction: Ecommerce
post-getCostEstimate-getCostEstimate-200:
summary: Example response for request 'getCostEstimate'
value:
costEstimateAmount:
currency: EUR
value: 12
resultCode: Success
surchargeType: PASSTHROUGH
post-getCostEstimate-getCostEstimateEncryptedCard:
summary: Estimate the transaction cost using an encrypted card number
description: Example request to get the estimated cost of a transaction
value:
amount:
value: 1234
currency: EUR
assumptions:
assumeLevel3Data: true
assume3DSecureAuthenticated: true
encryptedCardNumber: test_5101180000000007
merchantAccount: YOUR_MERCHANT_ACCOUNT
merchantDetails:
countryCode: NL
mcc: '7411'
enrolledIn3DSecure: true
shopperInteraction: Ecommerce
post-getCostEstimate-getCostEstimateEncryptedCard-200:
summary: Example response for request 'getCostEstimateEncryptedCard'
value:
costEstimateAmount:
currency: EUR
value: 12
resultCode: Success
surchargeType: PASSTHROUGH
post-getCostEstimate-getCostEstimateMinimal:
summary: Estimate the transaction cost (minimal)
description: >-
Example request to get the estimated cost of a transaction with minimum
details
value:
amount:
value: 1234
currency: EUR
cardNumber: '5101180000000007'
merchantAccount: YOUR_MERCHANT_ACCOUNT
post-getCostEstimate-getCostEstimateMinimal-200:
summary: Example response for request 'getCostEstimateMinimal'
value:
costEstimateAmount:
currency: EUR
value: 12
resultCode: Success
surchargeType: PASSTHROUGH
post-getCostEstimate-getCostEstimateMinimal3DS:
summary: Estimate the transaction cost (minimal with 3DSecure)
description: >-
Example request to get the estimated cost of a 3D Secure transaction
with minimum details
value:
amount:
value: 1234
currency: EUR
assumptions:
assumeLevel3Data: true
assume3DSecureAuthenticated: true
cardNumber: '5101180000000007'
merchantAccount: YOUR_MERCHANT_ACCOUNT
post-getCostEstimate-getCostEstimateMinimal3DS-200:
summary: Example response for request 'getCostEstimateMinimal3DS'
value:
costEstimateAmount:
currency: EUR
value: 12
resultCode: Success
surchargeType: PASSTHROUGH
post-getCostEstimate-getCostEstimateRecurringContract:
summary: Estimate the transaction cost (recurring contract)
description: Example request to get the estimated cost of a recurring transaction
value:
amount:
value: 1234
currency: EUR
assumptions:
assumeLevel3Data: true
assume3DSecureAuthenticated: true
merchantAccount: YOUR_MERCHANT_ACCOUNT
merchantDetails:
countryCode: NL
mcc: '7411'
enrolledIn3DSecure: true
selectedRecurringDetailReference: '1234567890123456'
shopperInteraction: Ecommerce