API Documentation

# Single country
curl "https://engine.billioncore.tech/api/bin/lookup?bin=453998&country=US" \
  -H "X-API-Key: bc_live_yourkey"

# All country rules
curl "https://engine.billioncore.tech/api/bin/lookup?bin=453998" \
  -H "X-API-Key: bc_live_yourkey"

<?php

function billioncore_lookup(string $bin, string $country = ''): array
{
    $url = 'https://engine.billioncore.tech/api/bin/lookup?bin=' . urlencode($bin);
    if ($country !== '') {
        $url .= '&country=' . urlencode($country);
    }

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL            => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'X-API-Key: ' . $_ENV['BILLIONCORE_API_KEY'],
            'Accept: application/json',
        ],
        CURLOPT_TIMEOUT        => 5,
    ]);
    $body = curl_exec($ch);
    curl_close($ch);

    return json_decode($body, true);
}

// Usage
$result = billioncore_lookup('453998', 'US');

if ($result['success']) {
    $data = $result['data'];
    echo "Action: " . $data['action'] . PHP_EOL;          // "FORCE"
    echo "Trial:  $" . $data['trial_price'] . " / " . $data['trial_period'] . " days" . PHP_EOL;
    echo "Rebill: $" . $data['rebill_price'] . " / " . $data['rebill_period'] . " days" . PHP_EOL;
    echo "Brand:  " . ($data['issuer']['card_brand'] ?? 'unknown') . PHP_EOL;
    echo "Bank:   " . ($data['issuer']['issuer_name'] ?? 'unknown') . PHP_EOL;
    echo "Risk:   " . ($data['bin_performance']['risk_score'] ?? 'n/a') . "/100" . PHP_EOL;
}

<?php

return [
    // ...

    'billioncore' => [
        'key'      => env('BILLIONCORE_API_KEY'),
        'base_url' => env('BILLIONCORE_BASE_URL', 'https://engine.billioncore.tech'),
    ],
];

const BILLIONCORE_KEY  = process.env.BILLIONCORE_API_KEY;
const BILLIONCORE_BASE = 'https://engine.billioncore.tech';

async function lookupBin(bin, country) {
  const url = new URL('/api/bin/lookup', BILLIONCORE_BASE);
  url.searchParams.set('bin', bin);
  if (country) url.searchParams.set('country', country);

  const res = await fetch(url.toString(), {
    headers: { 'X-API-Key': BILLIONCORE_KEY },
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error ?? 'BillionCore error');
  }

  return res.json().then(r => r.data);
}

// Usage
const data = await lookupBin('453998', 'US');

if (data.action === 'FORCE') {
  console.log('Trial: $' + data.trial_price + ' / ' + data.trial_period + ' days');
  console.log('Brand:', data.issuer?.card_brand);    // "visa"
  console.log('Risk: ', data.bin_performance?.risk_score); // 8
}

import os
import requests
from typing import Optional

BILLIONCORE_KEY  = os.environ["BILLIONCORE_API_KEY"]
BILLIONCORE_BASE = "https://engine.billioncore.tech"


def lookup_bin(bin: str, country: Optional[str] = None) -> dict:
    params = {"bin": bin}
    if country:
        params["country"] = country

    resp = requests.get(
        f"{BILLIONCORE_BASE}/api/bin/lookup",
        params=params,
        headers={"X-API-Key": BILLIONCORE_KEY},
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json()["data"]


data = lookup_bin("453998", "US")

if data["action"] == "FORCE":
    print(f"Trial:  {data['trial_price']{'}'} / {'{'}data['trial_period']{'}'} days")
    print(f"Brand:  {'{'}data.get('issuer', {'{}'}).get('card_brand', 'n/a'){'}'}")
    print(f"Risk:   {'{'}data.get('bin_performance', {'{}'}).get('risk_score', 'n/a'){'}'}/100")

package billioncore

import (
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "os"
    "time"
)

type Client struct {
    apiKey  string
    baseURL string
    http    *http.Client
}

type LookupData struct {
    Bin          string          `json:"bin"`
    Country      string           `json:"country,omitempty"`
    Action       string           `json:"action"`
    TrialPrice   float64          `json:"trial_price"`
    TrialPeriod  int              `json:"trial_period"`
    RebillPrice  float64          `json:"rebill_price"`
    RebillPeriod int              `json:"rebill_period"`
    XSellStatus  string           `json:"x_sell_status"`
    Performance  *BinPerformance  `json:"bin_performance,omitempty"`
    Issuer       *Issuer          `json:"issuer,omitempty"`
    Rules        map[string]Rule  `json:"rules,omitempty"`
}

type Rule struct {
    Action      string  `json:"action"`
    TrialPrice  float64 `json:"trial_price"`
    RebillPrice float64 `json:"rebill_price"`
}

type BinPerformance struct {
    GrossProfit float64 `json:"gross_profit"`
    RiskScore   int     `json:"risk_score"`
}

type Issuer struct {
    CardBrand  string `json:"card_brand"`
    CardType   string `json:"card_type"`
    IssuerName string `json:"issuer_name"`
    Country    string `json:"country"`
}

func NewClient() *Client {
    return &Client{
        apiKey:  os.Getenv("BILLIONCORE_API_KEY"),
        baseURL: "https://engine.billioncore.tech",
        http:    &http.Client{Timeout: 5 * time.Second},
    }
}

func (c *Client) Lookup(ctx context.Context, bin, country string) (*LookupData, error) {
    u, _ := url.Parse(c.baseURL + "/api/bin/lookup")
    q := u.Query()
    q.Set("bin", bin)
    if country != "" {
        q.Set("country", country)
    }
    u.RawQuery = q.Encode()

    req, _ := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)
    req.Header.Set("X-API-Key", c.apiKey)

    resp, err := c.http.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        var errResp struct{ Error string `json:"error"` }
        json.NewDecoder(resp.Body).Decode(&errResp)
        return nil, fmt.Errorf("billioncore: %s", errResp.Error)
    }

    var result struct {
        Data LookupData `json:"data"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }
    return &result.Data, nil
}