{ "openapi": "3.0.0", "info": { "title": "Fin Codes API — x402 Pay-per-Request API", "description": "Pay-per-request banking data API for AI agents and automated systems. Validate and look up IBANs and BIC/SWIFT codes using maintained banking reference data, perform Verification of Payee checks for supported SEPA accounts, and screen names against official sanctions lists. No account, API key or subscription required. x402-compatible clients handle payments automatically in USDC using x402 v2. Every operation is a POST to a fixed URL with a JSON body; identifiers never appear in URLs. Send a request without PAYMENT-SIGNATURE to receive the payment terms. Malformed request bodies are rejected with HTTP 400 before any payment is verified or settled.", "contact": { "email": "support@fincodesapi.com" }, "version": "2.0", "x-guidance": "Every operation is a POST to a fixed URL with a JSON body; identifiers never go in the URL. Use POST /x402/iban/lookup with {\"iban\"} to validate an IBAN and get its bank, branch codes and BIC ($0.04). Use POST /x402/bic/lookup with {\"bic\"} for the bank, branch and address behind a BIC/SWIFT code ($0.04). Use POST /x402/iban/verify-payee with {\"iban\", \"payee_name\"} to check that a name matches the holder of a SEPA account (Verification of Payee, $0.20); read payee_name_match (MATCH, CLOSE_MATCH, NO_MATCH, NOT_APPLICABLE, BANK_UNAVAILABLE). Use POST /x402/sanctions-screening with {\"name\"} to screen a person, entity, vessel or aircraft against the EU, UK, UN, OFAC, Swiss, Australian and Canadian sanctions lists ($0.01); matches are name similarity and need review. Pay with x402 v2, exact scheme, USDC on Base: a request without PAYMENT-SIGNATURE returns the 402 terms. Malformed bodies get HTTP 400 before any payment; invalid IBANs/BICs are reported after payment." }, "servers": [ { "url": "https://api.fincodesapi.com/" } ], "paths": { "/x402/bic/lookup": { "post": { "tags": [ "bic", "swift", "banking", "bank-data", "financial-data" ], "summary": "BIC/SWIFT lookup - $0.04 USDC", "description": "Look up a BIC/SWIFT using maintained financial-institution reference data. Returns bank, branch, location and country information where available. No account, API key or subscription required; x402 clients handle USDC payment automatically. Requests missing the bic field are rejected with HTTP 400 before payment. Price: $0.04 USDC per request.", "operationId": "lookupBic", "parameters": [ { "$ref": "#/components/parameters/X402PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "bic" ], "properties": { "bic": { "description": "8- or 11-character BIC/SWIFT code to validate and look up.", "type": "string", "example": "SOGEDEFF" } }, "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "BIC/SWIFT lookup completed successfully after x402 payment settlement.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PAYMENT-RESPONSE" } }, "content": { "application/json": { "schema": { "properties": { "success": { "$ref": "#/components/schemas/success" }, "data": { "$ref": "#/components/schemas/Bic" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "402": { "$ref": "#/components/responses/402" }, "404": { "description": "BIC/SWIFT not found. Charged: payment settles before the lookup." }, "409": { "$ref": "#/components/responses/409" }, "502": { "$ref": "#/components/responses/502" }, "503": { "$ref": "#/components/responses/503" } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.04" }, "protocols": [ { "x402": {} } ] } } }, "/x402/iban/lookup": { "post": { "tags": [ "iban", "banking", "bank-data", "payments", "financial-data" ], "summary": "IBAN validation and bank lookup - $0.04 USDC", "description": "Validate and look up an IBAN using maintained banking reference data. Returns account structure, country, national bank/branch codes and the associated BIC/SWIFT where available. No account, API key or subscription required; x402 clients handle USDC payment automatically. Requests missing the iban field or containing other fields are rejected with HTTP 400 before payment. Price: $0.04 USDC per request.", "operationId": "lookupIban", "parameters": [ { "$ref": "#/components/parameters/X402PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "iban" ], "properties": { "iban": { "description": "International Bank Account Number (IBAN) to validate and look up.", "type": "string", "example": "DE75512108001245126199" } }, "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "IBAN lookup completed successfully after x402 payment settlement.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PAYMENT-RESPONSE" } }, "content": { "application/json": { "schema": { "properties": { "success": { "$ref": "#/components/schemas/success" }, "data": { "$ref": "#/components/schemas/Iban" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "502": { "$ref": "#/components/responses/502" }, "503": { "$ref": "#/components/responses/503" } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.04" }, "protocols": [ { "x402": {} } ] } } }, "/x402/iban/verify-payee": { "post": { "tags": [ "verification-of-payee", "vop", "iban", "payments", "banking" ], "summary": "Verification of Payee (VoP) - $0.20 USDC", "description": "Verify whether a payee name matches the account holder for a supported SEPA IBAN. Returns MATCH, CLOSE_MATCH, NO_MATCH, NOT_APPLICABLE or BANK_UNAVAILABLE together with IBAN and bank information enriched using maintained banking reference data. No account, API key or subscription required; x402 clients handle USDC payment automatically. Requests missing the iban or payee_name field are rejected with HTTP 400 before payment. Price: $0.20 USDC per request.", "operationId": "verifyPayee", "parameters": [ { "$ref": "#/components/parameters/X402PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "iban", "payee_name" ], "properties": { "iban": { "description": "SEPA IBAN whose account holder name should be verified.", "type": "string", "example": "DE75512108001245126199" }, "payee_name": { "description": "Expected payee/account-holder name to verify.", "type": "string", "example": "John Doe" } }, "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Verification of Payee completed successfully after x402 payment settlement. Inspect payee_name_match: successful execution does not necessarily mean a name match.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PAYMENT-RESPONSE" } }, "content": { "application/json": { "schema": { "properties": { "success": { "$ref": "#/components/schemas/success" }, "data": { "$ref": "#/components/schemas/IbanVop" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "502": { "$ref": "#/components/responses/502" }, "503": { "$ref": "#/components/responses/503" } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.20" }, "protocols": [ { "x402": {} } ] } } }, "/x402/sanctions-screening": { "post": { "tags": [ "sanctions", "sanctions-screening", "compliance", "aml", "kyc" ], "summary": "Sanctions screening - $0.01 USDC", "description": "Screen a person, entity, vessel or aircraft name against the EU, UK, UN, OFAC (SDN and Consolidated), Swiss, Australian and Canadian sanctions lists, refreshed daily. Returns the matching sanctioned parties with match scores, programs, birth dates and list references, best match first; matches are name similarity and should be reviewed. No account, API key or subscription required; x402 clients handle USDC payment automatically. Requests missing the name field or containing other fields are rejected with HTTP 400 before payment. Price: $0.01 USDC per request.", "operationId": "sanctionsScreening", "parameters": [ { "$ref": "#/components/parameters/X402PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Name to screen.", "type": "string", "example": "Sadam Husein", "maxLength": 255, "minLength": 2 }, "type": { "description": "Only match parties of this type.", "type": "string", "example": "INDIVIDUAL", "enum": [ "INDIVIDUAL", "ENTITY", "VESSEL", "AIRCRAFT" ] }, "sources": { "description": "Only screen against these sanctions lists. All lists by default.", "type": "array", "items": { "type": "string", "enum": [ "EU", "UK", "UN", "OFAC_SDN", "OFAC_CONS", "CH", "AU", "CA" ] }, "example": [ "EU", "OFAC_SDN" ] }, "min_score": { "description": "Minimum match score from 70 to 100.", "type": "integer", "example": 90, "default": 90, "maximum": 100, "minimum": 70 } }, "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Screening completed successfully after x402 payment settlement. An empty matches array means no sanctioned party matched.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PAYMENT-RESPONSE" } }, "content": { "application/json": { "schema": { "properties": { "success": { "$ref": "#/components/schemas/success" }, "data": { "$ref": "#/components/schemas/SanctionsScreening" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "502": { "$ref": "#/components/responses/502" }, "503": { "$ref": "#/components/responses/503" } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": {} } ] } } } }, "components": { "schemas": { "success": { "description": "Success", "type": "boolean", "example": true }, "X402Resource": { "required": [ "url", "description", "mimeType" ], "properties": { "url": { "description": "Absolute URL of the x402-protected resource.", "type": "string", "example": "https://api.fincodesapi.com/x402/bic/lookup" }, "description": { "type": "string", "example": "Look up a BIC/SWIFT using maintained financial-institution reference data." }, "mimeType": { "type": "string", "example": "application/json" }, "serviceName": { "type": "string", "example": "Fin Codes API" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "swift", "bic", "banking", "bank-data", "financial-data" ] } }, "type": "object" }, "X402PaymentRequirements": { "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds" ], "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "description": "CAIP-2 network identifier used for payment settlement.", "type": "string", "example": "eip155:8453" }, "asset": { "description": "USDC token contract address on the selected network.", "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "amount": { "description": "Payment amount in USDC atomic units (6 decimals). For example, 40000 = $0.04 USDC.", "type": "string", "example": "40000" }, "payTo": { "description": "Wallet address that receives the payment.", "type": "string", "example": "0x1111111111111111111111111111111111111111" }, "maxTimeoutSeconds": { "description": "Maximum time allowed for the payment authorization.", "type": "integer", "example": 60 }, "extra": { "properties": { "name": { "type": "string", "example": "USD Coin" }, "version": { "type": "string", "example": "2" } }, "type": "object" } }, "type": "object" }, "X402PaymentRequired": { "required": [ "x402Version", "error", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "example": 2 }, "error": { "type": "string", "example": "Payment required" }, "resource": { "$ref": "#/components/schemas/X402Resource" }, "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/X402PaymentRequirements" } }, "extensions": { "description": "Optional x402 protocol extensions, including Bazaar machine-discovery metadata.", "type": "object" } }, "type": "object" }, "X402PaymentError": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Payment authorization already claimed; do not resubmit for settlement." } }, "type": "object" }, "Bic": { "properties": { "id": { "description": "BIC code", "type": "string", "example": "SOGEDEFF" }, "bank": { "$ref": "#/components/schemas/Bank" }, "country": { "$ref": "#/components/schemas/Country" }, "city": { "$ref": "#/components/schemas/City" }, "branch_name": { "description": "Branch name", "type": "string", "example": "SOGEBANK Frankfurt Main" }, "branch_code": { "description": "Branch code", "type": "string", "example": "" }, "address": { "description": "Address", "type": "string", "example": "NEUE MAINZER STRASSE 46-50" }, "postcode": { "description": "Postcode", "type": "string", "example": "60311" } }, "type": "object" }, "Iban": { "properties": { "id": { "description": "IBAN code", "type": "string", "example": "DE75512108001245126199" }, "account_number": { "description": "Account number", "type": "string", "example": "1245126199" }, "national_bank_code": { "description": "National bank code", "type": "string", "example": "51210800" }, "national_branch_code": { "description": "National branch code", "type": "string", "example": "" }, "bic": { "$ref": "#/components/schemas/Bic" }, "country": { "$ref": "#/components/schemas/Country" } }, "type": "object" }, "IbanVop": { "allOf": [ { "properties": { "payee_name_match": { "description": "Payee name match result", "type": "string", "example": "MATCH", "nullable": true, "enum": [ "MATCH", "CLOSE_MATCH", "NO_MATCH", "NOT_APPLICABLE", "BANK_UNAVAILABLE" ] }, "matched_payee_name": { "description": "Matched payee name returned by the bank for a CLOSE_MATCH result", "type": "string", "nullable": true } }, "type": "object" }, { "$ref": "#/components/schemas/Iban" } ] }, "Bank": { "properties": { "id": { "description": "Bank ID", "type": "string", "example": "cfb1758f-1195-4be9-b981-3fc63da7306b" }, "country_id": { "description": "ISO 3166-1 alpha-2 country code", "type": "string", "example": "DE" }, "code": { "description": "4 letters bank code", "type": "string", "example": "SOGE" }, "name": { "description": "Bank name", "type": "string", "example": "SOCIETE GENERALE S.A." } }, "type": "object" }, "City": { "properties": { "id": { "description": "City ID", "type": "string", "example": "c3eb05ae-2709-45c7-9799-d5e2fee08946" }, "country_id": { "description": "ISO 3166-1 alpha-2 country code", "type": "string", "example": "DE" }, "name": { "description": "City name", "type": "string", "example": "Frankfurt Am Main" } }, "type": "object" }, "Country": { "properties": { "id": { "description": "ISO 3166-1 alpha-2 country code", "type": "string", "example": "DE" }, "name": { "description": "Country name", "type": "string", "example": "Germany" } }, "type": "object" }, "SanctionMatch": { "properties": { "id": { "description": "Sanctioned party ID", "type": "string", "format": "uuid", "example": "ef947777-8b4c-4859-b07b-042be956bf4a" }, "source": { "description": "Sanctions list code", "type": "string", "example": "EU", "enum": [ "EU", "UK", "UN", "OFAC_SDN", "OFAC_CONS", "CH", "AU", "CA" ] }, "source_reference": { "description": "Reference of the party in the sanctions list", "type": "string", "example": "EU.27.28" }, "type": { "description": "Party type", "type": "string", "example": "INDIVIDUAL", "enum": [ "INDIVIDUAL", "ENTITY", "VESSEL", "AIRCRAFT" ] }, "name": { "description": "Primary name of the party", "type": "string", "example": "Saddam Hussein Al-Tikriti" }, "matched_name": { "description": "Name or alias of the party that matched", "type": "string", "example": "Saddam Hussein Al-Tikriti" }, "score": { "description": "Match score from 0 to 100", "type": "integer", "example": 90 }, "programs": { "description": "Sanctions programs or regimes", "type": "array", "items": { "type": "string" }, "example": [ "IRQ" ] }, "birth_dates": { "description": "Known birth dates: YYYY, YYYY-MM or YYYY-MM-DD", "type": "array", "items": { "type": "string" }, "example": [ "1937-04-28" ] }, "listed_on": { "description": "Date the party was listed", "type": "string", "format": "date", "example": "2003-07-08", "nullable": true } }, "type": "object" }, "SanctionsScreening": { "properties": { "name": { "description": "Screened name", "type": "string", "example": "Sadam Husein" }, "matches": { "description": "Matching sanctioned parties, best match first. Empty if the name matches no sanctioned party", "type": "array", "items": { "$ref": "#/components/schemas/SanctionMatch" } } }, "type": "object" } }, "responses": { "400": { "description": "Invalid request body (missing, blank, unknown or wrongly typed fields), rejected before payment verification or settlement with no charge; or an invalid IBAN, BIC or option value, reported by the operation after settlement and charged." }, "402": { "description": "Payment required. The response advertises the exact USDC amount, network and receiving wallet. Sign the x402 v2 payment authorization and retry with PAYMENT-SIGNATURE.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded copy of this challenge body", "schema": { "type": "string", "format": "byte" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } } }, "409": { "description": "Payment authorization already claimed or settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentError" } } } }, "502": { "description": "Payment settlement failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentError" } } } }, "503": { "description": "Payment verification or settlement unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentError" } } } } }, "parameters": { "X402PaymentSignature": { "name": "PAYMENT-SIGNATURE", "in": "header", "description": "Base64-encoded x402 v2 payment authorization. Omit this header to receive HTTP 402 with the exact USDC payment requirements.", "required": false, "schema": { "type": "string", "format": "byte" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded x402 settlement receipt returned after successful payment settlement and API execution.", "schema": { "type": "string", "format": "byte" } } } }, "tags": [ { "name": "bic", "description": "bic" }, { "name": "swift", "description": "swift" }, { "name": "banking", "description": "banking" }, { "name": "bank-data", "description": "bank-data" }, { "name": "financial-data", "description": "financial-data" }, { "name": "iban", "description": "iban" }, { "name": "payments", "description": "payments" }, { "name": "verification-of-payee", "description": "verification-of-payee" }, { "name": "vop", "description": "vop" }, { "name": "sanctions", "description": "sanctions" }, { "name": "sanctions-screening", "description": "sanctions-screening" }, { "name": "compliance", "description": "compliance" }, { "name": "aml", "description": "aml" }, { "name": "kyc", "description": "kyc" } ] }