Card Details

When making API requests, you can optionally provide card details to override automatic BIN lookup. This is useful when you have more accurate card information.

Structure

{
  "card_details": {
    "scheme": "VISA",
    "bin": "453212",
    "currency": "EUR",
    "issuer_country": "CZ",
    "product_category": "Credit",
    "product": "VISA_CREDIT"
  }
}

Required Fields (when providing card_details)

Field	Type	Values
scheme	string	VISA, MASTERCARD, AMEX, DINERS, JCB, UNIONPAY
currency	string	3-letter ISO currency code (e.g. "EUR")
issuer_country	string	2-letter ISO country code (e.g. "GB")
product_category	string	DEBIT, CREDIT, PREPAID, DEFERRED, CHARGE

Optional Fields

Field	Type	Description
bin	string	Bank Identification Number (6-8 digits)
type	string	"debit", "credit", "prepaid"
issuer_name	string	Name of the card-issuing bank
product	string	Product name for fee rule matching (e.g. "VISA_DEBIT")

Examples

Visa Credit Card

{
  "card_details": {
    "scheme": "VISA",
    "bin": "453212",
    "currency": "USD",
    "issuer_country": "US",
    "product_category": "CREDIT",
    "product": "VISA_CREDIT"
  }
}

Mastercard Debit Card

{
  "card_details": {
    "scheme": "MASTERCARD",
    "bin": "555555",
    "currency": "EUR",
    "issuer_country": "DE",
    "product_category": "DEBIT",
    "type": "debit",
    "issuer_name": "Deutsche Bank",
    "product": "MASTERCARD_DEBIT"
  }
}

Prepaid Card

{
  "card_details": {
    "scheme": "VISA",
    "bin": "411111",
    "currency": "GBP",
    "issuer_country": "GB",
    "product_category": "PREPAID",
    "type": "prepaid"
  }
}

Response Card Details

The API response always includes resolved card details — from your override or from BIN lookup:

{
  "card_details": {
    "bin": "536354",
    "scheme": "mastercard",
    "type": "debit",
    "product_category": "Debit",
    "issuer_name": "Sample Bank",
    "issuer_country": "US",
    "product": "MASTERCARD_DEBIT"
  }
}

Field	Type	Description
bin	string	Bank Identification Number
scheme	string	Card scheme (lowercase in response)
type	string | null	Funding source / account type
product_category	string | null	Product category
issuer_name	string | null	Issuing bank name
issuer_country	string | null	Issuer country (ISO 2-letter)
product	string | null	Card product identifier

Behavior

When provided:

1. Your details take precedence over BIN lookup
2. Fee calculation uses your card details
3. All fields are validated

When omitted:

1. Automatic BIN lookup using card_range
2. Fallback to default values if BIN lookup fails
3. Response includes all resolved fields

Error Handling

• Invalid scheme: 400 error with valid scheme options
• Invalid currency: 400 error with currency format requirements
• Invalid country: 400 error with country code format
• Invalid category: 400 error with valid category options

Best Practices

1. Only provide card_details when you're confident about the values
2. Ensure issuer_country matches the actual card issuer
3. Align currency with the card's primary currency
4. Verify scheme matches the actual card brand
5. Include product for more accurate fee matching