Developer Tools (Public APIs)

Revtain exposes a small set of free public endpoints that your team can call from anywhere — debugging tools, internal dashboards, fraud screens, support tools. They’re the same endpoints that power the live tools at revtain.com/tools. No authentication. No API key. CORS is open so you can call them from a browser as well as a server.

BIN Lookup

Identify the issuing bank, country, network, and card type from any 4 to 8 digit Bank Identification Number (BIN).

GET https://api.revtain.com/api/lookup/bin/{prefix}

Example:

curl https://api.revtain.com/api/lookup/bin/414720

Response:

{
  "prefix": "414720",
  "issuerName": "Chase",
  "issuerCountry": "US",
  "cardNetwork": "visa",
  "cardType": "credit"
}

Response fields:

Field	Type	Description
`prefix`	string	The BIN prefix you queried (4–8 digits).
`issuerName`	string	The bank that issued the card, e.g. `Chase`, `Barclays`, `Nubank`. `Unknown` when not identifiable.
`issuerCountry`	string	ISO-3166-1 alpha-2 country code, e.g. `US`, `GB`, `BR`. `Unknown` when not identifiable.
`cardNetwork`	string	One of `visa`, `mastercard`, `amex`, `discover`, `unknown`.
`cardType`	string	One of `credit`, `debit`, `prepaid`, `unknown`.

Errors:

400 Bad Request — prefix is not 4–8 digits.

Decline Code Lookup

Translate any gateway-specific decline code into Revtain’s canonical taxonomy with a plain-English explanation.

GET https://api.revtain.com/api/lookup/decline/{gateway}/{code}

{gateway} must be one of: stripe, braintree, adyen, checkout, authnet, dlocal, worldpay, razorpay, paystack, cybersource, paypal, gocardless, mollie. Example:

curl https://api.revtain.com/api/lookup/decline/braintree/2010

Response:

{
  "gateway": "braintree",
  "gatewayLabel": "Braintree",
  "rawCode": "2010",
  "canonicalCode": "insufficient_funds",
  "category": "soft",
  "plainEnglish": "The customer's account is short on funds. Retry near payday (typically the 1st or 15th of the month).",
  "variantsOnOtherGateways": [
    { "gateway": "stripe", "gatewayLabel": "Stripe", "rawCode": "insufficient_funds" },
    { "gateway": "adyen", "gatewayLabel": "Adyen", "rawCode": "Not enough balance" },
    { "gateway": "authnet", "gatewayLabel": "Authorize.net", "rawCode": "51" }
  ]
}

Response fields:

Field	Type	Description
`gateway`	string	The gateway slug you queried.
`rawCode`	string	The raw code you queried.
`canonicalCode`	string	Revtain’s canonical taxonomy code (e.g. `insufficient_funds`, `do_not_honor`, `expired_card`).
`category`	string	One of `hard`, `soft`, `fraud`, `technical`, `auth_required`, `unknown`.
`plainEnglish`	string	A short, merchant-facing explanation of what this decline means.
`variantsOnOtherGateways`	array	The same decline reason as it appears on other gateways. Useful for cross-gateway debugging.

Full Decline Code Dictionary

Pull the entire decline-code dictionary in one call — 500+ codes across 13 gateways, grouped by canonical category.

GET https://api.revtain.com/api/lookup/decline-codes

Response (truncated):

{
  "canonicalCount": 43,
  "variantCount": 500,
  "gatewayCount": 13,
  "gatewayCounts": {
    "stripe": 65,
    "braintree": 62,
    "adyen": 88,
    "authnet": 89,
    "checkout": 75,
    "dlocal": 35,
    "worldpay": 34,
    "razorpay": 24,
    "paystack": 10,
    "cybersource": 5,
    "paypal": 5,
    "gocardless": 3,
    "mollie": 5
  },
  "codes": [
    {
      "canonicalCode": "insufficient_funds",
      "category": "soft",
      "plainEnglish": "The customer's account is short on funds...",
      "variants": [
        { "gateway": "stripe", "gatewayLabel": "Stripe", "rawCode": "insufficient_funds" },
        { "gateway": "braintree", "gatewayLabel": "Braintree", "rawCode": "2010" },
        { "gateway": "gocardless", "gatewayLabel": "GoCardless", "rawCode": "insufficient_funds" }
      ]
    }
  ]
}

Best fetched once on app startup and cached client-side — the dictionary changes infrequently.

Use cases

Internal debug dashboards — show your support team a plain-English meaning for every decline the gateway returned.
Customer support scripts — let agents type in a raw code from a transaction log and immediately see what to tell the customer.
Fraud / risk screens — enrich a transaction view with issuerName and issuerCountry without integrating a paid BIN service.
Engineering — wire the canonical decline taxonomy into your own retry logic if you don’t use Revtain for everything.

Rate limits

There are no per-key rate limits on these endpoints (they take no auth). We ask that you cache responses where reasonable — the underlying data updates infrequently:

BIN responses can be safely cached for 24 hours per prefix.
Decline-code responses can be safely cached indefinitely; the dictionary changes only when we add new gateway support.

If you anticipate calling at high volume (above a few requests per second sustained), get in touch so we can plan capacity.

Get Started

Integration

Dashboard

Concepts

Developer Tools (Public APIs)

BIN Lookup

Decline Code Lookup

Full Decline Code Dictionary

Use cases

Rate limits

​BIN Lookup

​Decline Code Lookup

​Full Decline Code Dictionary

​Use cases

​Rate limits

BIN Lookup

Decline Code Lookup

Full Decline Code Dictionary

Use cases

Rate limits