Procare Pay Integration Service

Complete API Documentation for Payment Processing

Get Multiple BINs Information (Bulk Lookup)

GET /v1/rest/bins?binIds={binIds}

Description: Retrieves Bank Identification Number (BIN) information for multiple credit cards in a single request. This is more efficient than making individual requests when you need to look up several BINs at once.

What is this endpoint used for?

This endpoint is the bulk version of the single BIN lookup, perfect for scenarios where you need information about multiple cards:

  • Batch Processing: Look up BIN information for a list of saved payment methods
  • Reporting: Generate reports showing card types across all transactions
  • Merchant Dashboard: Display card brand distribution for analytics
  • Multi-Card Checkout: Support split payments with multiple cards
  • Performance: Reduce API calls by bundling multiple lookups into one request
  • Payment Method Management: Update card brand logos for all saved payment methods

Query Parameters

binIds (required)
Type: string (comma-separated list)
Description: A comma-delimited list of BIN IDs or the first 6-8 digits of card numbers
Format: bin1,bin2,bin3,...
Example: 411111,540123,378282
Limit: Recommended maximum of 50-100 BINs per request for optimal performance

Authentication

This endpoint requires bearer token authentication using the Authorization header.

Note: The bearer token must be a valid Cognito token obtained through the OAuth2 authentication flow.

Code Examples

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class IssuerInformation
{
    [JsonProperty("name")]
    public string Name { get; set; }

    [JsonProperty("country")]
    public string Country { get; set; }

    [JsonProperty("phoneNumber")]
    public string PhoneNumber { get; set; }
}

public class BinResponse
{
    [JsonProperty("binId")]
    public string BinId { get; set; }

    [JsonProperty("cardType")]
    public string CardType { get; set; }

    [JsonProperty("brandName")]
    public string BrandName { get; set; }

    [JsonProperty("fundingSource")]
    public string FundingSource { get; set; }

    [JsonProperty("bin")]
    public string Bin { get; set; }

    [JsonProperty("issuerInformation")]
    public IssuerInformation IssuerInformation { get; set; }

    [JsonProperty("surcharge")]
    public string Surcharge { get; set; }
}

public class BinBulkClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://your-api-domain.com";

    public BinBulkClient()
    {
        _httpClient = new HttpClient();
        _httpClient.BaseAddress = new Uri(_baseUrl);
    }

    public async Task<List<BinResponse>> GetMultipleBinInfoAsync(List<string> binIds)
    {
        try
        {
            // Validate input
            if (binIds == null || !binIds.Any())
            {
                throw new ArgumentException("BIN IDs list cannot be empty", nameof(binIds));
            }

            // Validate each BIN
            foreach (var bin in binIds)
            {
                if (string.IsNullOrEmpty(bin) || bin.Length < 6)
                {
                    throw new ArgumentException($"Invalid BIN: {bin}. Must be at least 6 digits.");
                }
            }

            // Create comma-separated list
            string binIdsParam = string.Join(",", binIds);

            // Construct the endpoint URL with query parameter
            string endpoint = $"/v1/rest/bins?binIds={Uri.EscapeDataString(binIdsParam)}";

            // Make the GET request
            HttpResponseMessage response = await _httpClient.GetAsync(endpoint);

            // Ensure the request was successful
            response.EnsureSuccessStatusCode();

            // Read and deserialize the response
            string responseBody = await response.Content.ReadAsStringAsync();
            List<BinResponse> binInfoList =
                JsonConvert.DeserializeObject<List<BinResponse>>(responseBody);

            return binInfoList;
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request error: {e.Message}");
            throw;
        }
    }

    // Helper: Extract BINs from multiple card numbers
    public List<string> ExtractBins(List<string> cardNumbers, int binLength = 8)
    {
        return cardNumbers.Select(card =>
        {
            string cleaned = new string(card.Where(char.IsDigit).ToArray());
            return cleaned.Substring(0, Math.Min(binLength, cleaned.Length));
        }).Distinct().ToList();
    }
}

// Example usage:
var client = new BinBulkClient();

// Look up multiple BINs
var binIds = new List<string> { "411111", "540123", "378282", "601111" };

List<BinResponse> binInfoList = await client.GetMultipleBinInfoAsync(binIds);

// Process results
foreach (var binInfo in binInfoList)
{
    Console.WriteLine($"BIN: {binInfo.Bin}");
    Console.WriteLine($"  Brand: {binInfo.BrandName}");
    Console.WriteLine($"  Type: {binInfo.CardType}");
    Console.WriteLine($"  Surcharge: {binInfo.Surcharge}");
    Console.WriteLine();
}

// Example: Get BINs from saved payment methods
var savedCards = new List<string>
{
    "4111111111111111",
    "5401234567890123",
    "378282246310005"
};

List<string> bins = client.ExtractBins(savedCards, 8);
List<BinResponse> results = await client.GetMultipleBinInfoAsync(bins);
Imports System.Collections.Generic
Imports System.Linq
Imports System.Net.Http
Imports System.Threading.Tasks
Imports Newtonsoft.Json

Public Class IssuerInformation
    <JsonProperty("name")>
    Public Property Name As String

    <JsonProperty("country")>
    Public Property Country As String

    <JsonProperty("phoneNumber")>
    Public Property PhoneNumber As String
End Class

Public Class BinResponse
    <JsonProperty("binId")>
    Public Property BinId As String

    <JsonProperty("cardType")>
    Public Property CardType As String

    <JsonProperty("brandName")>
    Public Property BrandName As String

    <JsonProperty("fundingSource")>
    Public Property FundingSource As String

    <JsonProperty("bin")>
    Public Property Bin As String

    <JsonProperty("issuerInformation")>
    Public Property IssuerInformation As IssuerInformation

    <JsonProperty("surcharge")>
    Public Property Surcharge As String
End Class

Public Class BinBulkClient
    Private ReadOnly _httpClient As HttpClient
    Private ReadOnly _baseUrl As String = "https://your-api-domain.com"

    Public Sub New()
        _httpClient = New HttpClient()
        _httpClient.BaseAddress = New Uri(_baseUrl)
    End Sub

    Public Async Function GetMultipleBinInfoAsync(binIds As List(Of String)) As Task(Of List(Of BinResponse))
        Try
            ' Validate input
            If binIds Is Nothing OrElse Not binIds.Any() Then
                Throw New ArgumentException("BIN IDs list cannot be empty", NameOf(binIds))
            End If

            ' Validate each BIN
            For Each bin In binIds
                If String.IsNullOrEmpty(bin) OrElse bin.Length < 6 Then
                    Throw New ArgumentException($"Invalid BIN: {bin}. Must be at least 6 digits.")
                End If
            Next

            ' Create comma-separated list
            Dim binIdsParam As String = String.Join(",", binIds)

            ' Construct the endpoint URL with query parameter
            Dim endpoint As String = $"/v1/rest/bins?binIds={Uri.EscapeDataString(binIdsParam)}"

            ' Make the GET request
            Dim response As HttpResponseMessage = Await _httpClient.GetAsync(endpoint)

            ' Ensure the request was successful
            response.EnsureSuccessStatusCode()

            ' Read and deserialize the response
            Dim responseBody As String = Await response.Content.ReadAsStringAsync()
            Dim binInfoList As List(Of BinResponse) = _
                JsonConvert.DeserializeObject(Of List(Of BinResponse))(responseBody)

            Return binInfoList
        Catch ex As HttpRequestException
            Console.WriteLine($"Request error: {ex.Message}")
            Throw
        End Try
    End Function

    ' Helper: Extract BINs from multiple card numbers
    Public Function ExtractBins(cardNumbers As List(Of String), Optional binLength As Integer = 8) As List(Of String)
        Return cardNumbers.Select(Function(card)
                                      Dim cleaned As String = New String(card.Where(AddressOf Char.IsDigit).ToArray())
                                      Return cleaned.Substring(0, Math.Min(binLength, cleaned.Length))
                                  End Function).Distinct().ToList()
    End Function
End Class

' Example usage:
Dim client As New BinBulkClient()

' Look up multiple BINs
Dim binIds As New List(Of String) From {"411111", "540123", "378282", "601111"}

Dim binInfoList As List(Of BinResponse) = Await client.GetMultipleBinInfoAsync(binIds)

' Process results
For Each binInfo In binInfoList
    Console.WriteLine($"BIN: {binInfo.Bin}")
    Console.WriteLine($"  Brand: {binInfo.BrandName}")
    Console.WriteLine($"  Type: {binInfo.CardType}")
    Console.WriteLine($"  Surcharge: {binInfo.Surcharge}")
    Console.WriteLine()
Next
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
import com.google.gson.Gson;
import com.google.gson.annotations.SerializedName;
import com.google.gson.reflect.TypeToken;

class IssuerInformation {
    @SerializedName("name")
    private String name;

    @SerializedName("country")
    private String country;

    @SerializedName("phoneNumber")
    private String phoneNumber;

    // Getters
    public String getName() { return name; }
    public String getCountry() { return country; }
    public String getPhoneNumber() { return phoneNumber; }
}

class BinResponse {
    @SerializedName("binId")
    private String binId;

    @SerializedName("cardType")
    private String cardType;

    @SerializedName("brandName")
    private String brandName;

    @SerializedName("fundingSource")
    private String fundingSource;

    @SerializedName("bin")
    private String bin;

    @SerializedName("issuerInformation")
    private IssuerInformation issuerInformation;

    @SerializedName("surcharge")
    private String surcharge;

    // Getters
    public String getBinId() { return binId; }
    public String getCardType() { return cardType; }
    public String getBrandName() { return brandName; }
    public String getFundingSource() { return fundingSource; }
    public String getBin() { return bin; }
    public IssuerInformation getIssuerInformation() { return issuerInformation; }
    public String getSurcharge() { return surcharge; }
}

public class BinBulkClient {
    private final HttpClient httpClient;
    private final String baseUrl;
    private final Gson gson;

    public BinBulkClient() {
        this.baseUrl = "https://your-api-domain.com";
        this.httpClient = HttpClient.newHttpClient();
        this.gson = new Gson();
    }

    public List<BinResponse> getMultipleBinInfo(List<String> binIds) throws Exception {
        // Validate input
        if (binIds == null || binIds.isEmpty()) {
            throw new IllegalArgumentException("BIN IDs list cannot be empty");
        }

        // Validate each BIN
        for (String bin : binIds) {
            if (bin == null || bin.length() < 6) {
                throw new IllegalArgumentException("Invalid BIN: " + bin + ". Must be at least 6 digits.");
            }
        }

        // Create comma-separated list
        String binIdsParam = String.join(",", binIds);

        // URL encode the parameter
        String encodedBinIds = URLEncoder.encode(binIdsParam, StandardCharsets.UTF_8);

        // Construct the endpoint URL
        String endpoint = baseUrl + "/v1/rest/bins?binIds=" + encodedBinIds;

        // Build the HTTP request
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(endpoint))
            .header("Accept", "application/json")
            .GET()
            .build();

        // Send the request and get response
        HttpResponse<String> response = httpClient.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        // Check response status
        if (response.statusCode() == 200) {
            return gson.fromJson(response.body(), new TypeToken<List<BinResponse>>(){}.getType());
        } else if (response.statusCode() == 404) {
            throw new Exception("One or more BINs not found");
        } else {
            throw new Exception("Request failed with status: " + response.statusCode());
        }
    }

    // Helper: Extract BINs from multiple card numbers
    public List<String> extractBins(List<String> cardNumbers, int binLength) {
        return cardNumbers.stream()
            .map(card -> card.replaceAll("[^0-9]", ""))
            .map(cleaned -> cleaned.substring(0, Math.min(binLength, cleaned.length())))
            .distinct()
            .collect(Collectors.toList());
    }

    // Example usage
    public static void main(String[] args) {
        try {
            BinBulkClient client = new BinBulkClient();

            // Look up multiple BINs
            List<String> binIds = new ArrayList<>();
            binIds.add("411111");
            binIds.add("540123");
            binIds.add("378282");
            binIds.add("601111");

            List<BinResponse> binInfoList = client.getMultipleBinInfo(binIds);

            // Process results
            for (BinResponse binInfo : binInfoList) {
                System.out.println("BIN: " + binInfo.getBin());
                System.out.println("  Brand: " + binInfo.getBrandName());
                System.out.println("  Type: " + binInfo.getCardType());
                System.out.println("  Surcharge: " + binInfo.getSurcharge());
                System.out.println();
            }

            System.out.println("Total BINs processed: " + binInfoList.size());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
require 'net/http'
require 'uri'
require 'json'
require 'cgi'

class BinBulkClient
  def initialize(base_url = 'https://your-api-domain.com')
    @base_url = base_url
  end

  def get_multiple_bin_info(bin_ids)
    # Validate input
    raise ArgumentError, 'BIN IDs list cannot be empty' if bin_ids.nil? || bin_ids.empty?

    # Validate each BIN
    bin_ids.each do |bin|
      raise ArgumentError, "Invalid BIN: #{bin}. Must be at least 6 digits." if bin.nil? || bin.length < 6
    end

    # Create comma-separated list
    bin_ids_param = bin_ids.join(',')

    # URL encode the parameter
    encoded_bin_ids = CGI.escape(bin_ids_param)

    # Construct the endpoint URL
    uri = URI("#{@base_url}/v1/rest/bins?binIds=#{encoded_bin_ids}")

    # Create HTTP request
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true if uri.scheme == 'https'
    http.read_timeout = 30

    request = Net::HTTP::Get.new(uri.request_uri)
    request['Accept'] = 'application/json'

    # Send request and handle response
    response = http.request(request)

    case response.code.to_i
    when 200
      JSON.parse(response.body)
    when 404
      raise 'One or more BINs not found'
    else
      raise "Request failed with status: #{response.code} - #{response.message}"
    end
  rescue StandardError => e
    puts "Request error: #{e.message}"
    raise
  end

  # Helper: Extract BINs from multiple card numbers
  def extract_bins(card_numbers, bin_length = 8)
    card_numbers.map do |card|
      cleaned = card.gsub(/[^0-9]/, '')
      cleaned[0, [bin_length, cleaned.length].min]
    end.uniq
  end
end

# Example usage:
client = BinBulkClient.new

# Look up multiple BINs
bin_ids = ['411111', '540123', '378282', '601111']

bin_info_list = client.get_multiple_bin_info(bin_ids)

# Process results
bin_info_list.each do |bin_info|
  puts "BIN: #{bin_info['bin']}"
  puts "  Brand: #{bin_info['brandName']}"
  puts "  Type: #{bin_info['cardType']}"
  puts "  Surcharge: #{bin_info['surcharge']}"
  puts
end

puts "Total BINs processed: #{bin_info_list.length}"

# Example: Get BINs from saved payment methods
saved_cards = [
  '4111111111111111',
  '5401234567890123',
  '378282246310005',
  '6011111111111117'
]

bins = client.extract_bins(saved_cards, 8)
puts "\nLooking up #{bins.length} unique BINs..."
results = client.get_multiple_bin_info(bins)

Response Structure

The response is an array of BIN information objects. Each object has the same structure as the single BIN lookup endpoint:

Field Type Description
binId string The URL Base64 encoded BIN ID (internal identifier)
cardType string The card type: Unknown, Credit, Debit, Prepaid, or Charge
brandName string The card brand name (Visa, Mastercard, American Express, Discover)
fundingSource string The funding source: Unknown, Credit, Debit, Prepaid, or Charge
bin string The actual BIN number (first 6-8 digits)
issuerInformation object Information about the issuing bank (name, country, phone)
surcharge string Surcharge eligibility: Unknown, Allowed, or NotAllowed

Example Response

[
  {
    "binId": "YWJjMTIzNDU2Nzg5MGRlZg==",
    "cardType": "Credit",
    "brandName": "Visa",
    "fundingSource": "Credit",
    "bin": "411111",
    "issuerInformation": {
      "name": "Chase Bank USA, N.A.",
      "country": "US",
      "phoneNumber": "1-800-555-0100"
    },
    "surcharge": "NotAllowed"
  },
  {
    "binId": "eHl6OTg3NjU0MzIxMGFiYw==",
    "cardType": "Credit",
    "brandName": "Mastercard",
    "fundingSource": "Credit",
    "bin": "540123",
    "issuerInformation": {
      "name": "Bank of America, N.A.",
      "country": "US",
      "phoneNumber": "1-800-555-0200"
    },
    "surcharge": "Allowed"
  },
  {
    "binId": "cXJzNDU2Nzg5MDEyMzQ1Ng==",
    "cardType": "Charge",
    "brandName": "American Express",
    "fundingSource": "Charge",
    "bin": "378282",
    "issuerInformation": {
      "name": "American Express",
      "country": "US",
      "phoneNumber": "1-800-528-4800"
    },
    "surcharge": "Allowed"
  },
  {
    "binId": "bm5vMTIzNDU2Nzg5MGFiYw==",
    "cardType": "Debit",
    "brandName": "Discover",
    "fundingSource": "Debit",
    "bin": "601111",
    "issuerInformation": {
      "name": "Wells Fargo Bank",
      "country": "US",
      "phoneNumber": "1-800-555-0300"
    },
    "surcharge": "NotAllowed"
  }
]

HTTP Status Codes

Status Code Description
200 Success - BIN information retrieved for all or some of the requested BINs
400 Bad Request - Invalid binIds parameter format or missing
404 Not Found - None of the requested BINs were found in the database
500 Internal Server Error - Server encountered an unexpected error
Partial Success: If some BINs are found and others are not, the API returns 200 with only the found BINs. The response array will contain fewer elements than requested. You should check the response count against your request count to detect missing BINs.

Common Use Cases

1. Update Card Logos for All Saved Payment Methods

// Get all saved payment methods for a user
List<SavedPaymentMethod> savedMethods = GetSavedPaymentMethods(userId);

// Extract BINs from masked card numbers (first 6-8 digits are unmasked)
List<string> bins = savedMethods
    .Select(m => m.MaskedAccountNumber.Substring(0, 8))
    .ToList();

// Look up all BINs in one request
List<BinResponse> binInfoList = await client.GetMultipleBinInfoAsync(bins);

// Update UI with card brand logos
for (int i = 0; i < savedMethods.Count; i++)
{
    savedMethods[i].CardBrand = binInfoList[i].BrandName;
    savedMethods[i].CardType = binInfoList[i].CardType;
}

2. Generate Transaction Report with Card Types

// Get transactions for reporting period
List<Transaction> transactions = GetTransactions(startDate, endDate);

// Extract unique BINs
List<string> uniqueBins = transactions
    .Select(t => ExtractBin(t.MaskedCardNumber, 8))
    .Distinct()
    .ToList();

// Look up all BINs at once
List<BinResponse> binInfoList = await client.GetMultipleBinInfoAsync(uniqueBins);

// Create lookup dictionary
Dictionary<string, BinResponse> binLookup = binInfoList.ToDictionary(b => b.Bin);

// Enrich transactions with BIN data
foreach (var txn in transactions)
{
    string bin = ExtractBin(txn.MaskedCardNumber, 8);
    if (binLookup.ContainsKey(bin))
    {
        txn.CardBrand = binLookup[bin].BrandName;
        txn.CardType = binLookup[bin].CardType;
    }
}

// Generate report: "X% Visa, Y% Mastercard, Z% debit cards, etc."

3. Batch Validation for Compliance

// Check if any saved payment methods are prepaid cards (for compliance)
List<string> bins = GetAllSavedPaymentMethodBins();
List<BinResponse> binInfoList = await client.GetMultipleBinInfoAsync(bins);

List<string> prepaidCards = binInfoList
    .Where(b => b.CardType == "Prepaid")
    .Select(b => b.Bin)
    .ToList();

if (prepaidCards.Any())
{
    Console.WriteLine($"Warning: {prepaidCards.Count} prepaid cards found");
    // Take appropriate action per business rules
}

4. Initialize Checkout Page with Multiple Cards

// For split payment checkout: look up all cards at page load
List<string> cardNumbers = new List<string>
{
    "4111111111111111",
    "5401234567890123"
};

List<string> bins = cardNumbers.Select(c => ExtractBin(c, 8)).ToList();
List<BinResponse> binInfoList = await client.GetMultipleBinInfoAsync(bins);

// Display each card with appropriate logo and surcharge info
for (int i = 0; i < cardNumbers.Count; i++)
{
    DisplayCard(
        cardNumbers[i],
        binInfoList[i].BrandName,
        binInfoList[i].Surcharge == "Allowed"
    );
}

5. Analytics Dashboard: Card Distribution

// Monthly dashboard showing payment method breakdown
List<string> allBins = GetMonthlyTransactionBins(month, year);
List<BinResponse> binInfoList = await client.GetMultipleBinInfoAsync(allBins);

// Group by card brand
var brandDistribution = binInfoList
    .GroupBy(b => b.BrandName)
    .Select(g => new { Brand = g.Key, Count = g.Count() })
    .OrderByDescending(x => x.Count);

// Group by card type
var typeDistribution = binInfoList
    .GroupBy(b => b.CardType)
    .Select(g => new { Type = g.Key, Count = g.Count() })
    .OrderByDescending(x => x.Count);

// Display charts/graphs

Best Practices

  • Batch requests: When looking up multiple BINs, always use this endpoint instead of multiple single-BIN requests
  • Remove duplicates: De-duplicate your BIN list before calling the API to avoid unnecessary lookups
  • Reasonable batch size: Keep requests to 50-100 BINs for best performance; split larger lists into multiple requests
  • Handle partial results: Check if response count matches request count; missing BINs may not be in database
  • Cache results: BIN data rarely changes; cache results for 24+ hours keyed by BIN
  • Async processing: For very large lists, consider background processing rather than blocking the user
  • Error handling: If the bulk request fails, fall back to individual lookups for critical BINs

Performance Considerations

Scenario Approach Performance
5 BINs Single bulk request ⚡ Fast - Use this endpoint
50 BINs Single bulk request ⚡ Fast - Optimal batch size
500 BINs 10 bulk requests of 50 each 🔄 Moderate - Split into batches
5000 BINs Background job with batching ⏱️ Slow - Use async processing

Example: Batching Large Lists

public async Task<List<BinResponse>> GetAllBinsWithBatching(List<string> allBins)
{
    const int batchSize = 50;
    var allResults = new List<BinResponse>();

    // Split into batches
    for (int i = 0; i < allBins.Count; i += batchSize)
    {
        var batch = allBins.Skip(i).Take(batchSize).ToList();

        try
        {
            var batchResults = await client.GetMultipleBinInfoAsync(batch);
            allResults.AddRange(batchResults);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Batch {i / batchSize + 1} failed: {ex.Message}");
            // Continue with next batch
        }

        // Optional: Small delay between batches to avoid rate limiting
        await Task.Delay(100);
    }

    return allResults;
}

Handling Missing BINs

// Request 4 BINs
List<string> requestedBins = new List<string> { "411111", "540123", "999999", "378282" };
List<BinResponse> results = await client.GetMultipleBinInfoAsync(requestedBins);

// Check which BINs were returned
HashSet<string> returnedBins = results.Select(r => r.Bin).ToHashSet();
List<string> missingBins = requestedBins.Where(b => !returnedBins.Contains(b)).ToList();

if (missingBins.Any())
{
    Console.WriteLine($"Warning: {missingBins.Count} BINs not found:");
    foreach (var bin in missingBins)
    {
        Console.WriteLine($"  - {bin}");
    }
}

// Process results normally for BINs that were found
foreach (var binInfo in results)
{
    ProcessBinInfo(binInfo);
}

Troubleshooting

Fewer Results Than Expected

  • Some requested BINs may not be in the database (new or invalid BINs)
  • Compare request count with response count to identify missing BINs
  • Missing BINs are silently excluded from the response (no error thrown)
  • Consider falling back to single-BIN lookup for missing entries

400 Bad Request - Invalid Parameter

  • Ensure binIds query parameter is present
  • Check that BINs are comma-separated with no spaces
  • Verify each BIN is at least 6 digits
  • URL-encode the parameter value if it contains special characters

Request URL Too Long

  • URLs have a maximum length (~2000 characters for most browsers/servers)
  • With 6-digit BINs: approximately 250 BINs max per request
  • With 8-digit BINs: approximately 200 BINs max per request
  • Solution: Split large lists into multiple requests

Performance Issues

  • Keep batch size around 50 BINs for optimal response time
  • Add small delays between batches if making many sequential requests
  • Cache results to avoid repeated lookups for the same BINs
  • For very large lists, use background processing

Related Endpoints

  • GET /v1/rest/bins/{binId} - Look up a single BIN (use when you only need one)

Additional Notes

  • The response array order may not match the request order - match results by the bin field
  • Duplicate BINs in the request will return only one result per unique BIN
  • This endpoint is more efficient than multiple single-BIN calls (reduces network overhead)
  • BIN data is considered non-sensitive and safe to cache or log
  • The response may contain a mix of 6-digit and 8-digit BINs depending on your input
  • International BINs are included in the database but may have less complete information
  • Consider implementing client-side caching to avoid repeated API calls for the same BINs
  • For real-time card input validation, use the single-BIN endpoint; use bulk endpoint for batch operations