{"openapi":"3.1.0","info":{"title":"verza: South African identity, VAT and credit agreement verification API","version":"0.1.0","description":"Verify South African identity numbers, VAT numbers and credit agreements. Validates a 13-digit South African ID number and decodes date of birth, gender and citizenship, validates a South African VAT number, checks whether a loan agreement's interest rate is lawful under National Credit Act Regulation 42, and validates up to 50 identifiers in one settled call. Invalid input is rejected free with a 400 before any payment challenge. No accounts and no API keys: payment is the authentication, in USDC on Base via the x402 protocol. Independent verification service over public data and standard checksum algorithms. Structural validation does not confirm registration with SARS, Home Affairs or any authority. No identity data is stored; identity query parameters are never logged.","x-guidance":"South African verification checks for agents. GET /v1/vat-validate?vat= structurally validates a VAT number (free). GET /v1/id-validate?id= validates a 13-digit SA identity number and safely decodes date of birth, gender and citizenship; it is stateless and the identity is never stored or logged. GET /v1/loan-check verifies whether a credit agreement's interest rate is lawful under National Credit Act Regulation 42, using the repo rate in force on the date the agreement was concluded, and returns a lawful or unlawful verdict with the exact cap and full workings. POST /v1/bulk-validate checks up to 50 identity or VAT numbers in one settled call. Every check states what it does and does not confirm; invalid input is rejected with a free 400 before any payment is requested. Typical jobs this API is bought for: onboard or KYC a South African customer by validating their ID number; check a South African VAT number before invoicing or claiming input VAT; derive date of birth, age, gender or citizenship from an SA ID number without storing it; verify that a loan or credit agreement's interest rate is lawful under the National Credit Act before signing or disputing it; work out the maximum lawful interest rate for a South African credit agreement concluded on a given date; screen a batch of customer records for invalid South African identifiers; and check a lender's quoted rate against the Regulation 42 caps.","contact":{"email":"spookynakamoto@gmail.com"}},"servers":[{"url":"https://verza.dev"}],"paths":{"/catalog":{"get":{"operationId":"getCatalog","summary":"Free catalog of every South African verification and KYB check verza offers: 4 checks covering identity number validation, VAT number validation, National Credit Act loan-agreement lawfulness verdicts and bulk validation, with prices and exactly what each check does and does not confirm","description":"Free discovery endpoint: what verza verifies, what each check costs and the limits of each verdict. Start here before any paid request.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/vat-validate":{"get":{"operationId":"verify_vat_validate","summary":"Structural validation of a South African VAT registration number (VAT vendor number): 10 digits, leading 4, check digit","description":"Structural validation of a South African VAT registration number (VAT vendor number): 10 digits, leading 4, check digit. Use it to screen a supplier or customer VAT number before invoicing or claiming input VAT. Free. Confirms format only, not active SARS registration. Example: /v1/vat-validate?vat=4012345676","tags":["Verification"],"parameters":[{"name":"vat","in":"query","required":true,"description":"string, required: the VAT number to validate","schema":{"type":"string"}}],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing parameter (rejected free, before any payment challenge)"}}}},"/v1/id-validate":{"get":{"operationId":"verify_id_validate","summary":"Structural validation of a South African identity number with safe decode: Luhn check digit, birth date, gender and citizenship segments (citizen or permanent resident)","description":"Structural validation of a South African identity number with safe decode: Luhn check digit, birth date, gender and citizenship segments (citizen or permanent resident). The structural step in KYC, KYB and customer onboarding or due diligence workflows: derive date of birth, age, gender and citizenship without storing the identity. Stateless, never stored or logged (POPIA-conscious by construction). Confirms structure only, not registration with Home Affairs. Also callable as /v1/id-validate/{id}. Example: /v1/id-validate?id=8001015009087","tags":["Verification"],"parameters":[{"name":"id","in":"query","required":true,"description":"string, required: the 13-digit SA identity number","schema":{"type":"string","pattern":"^\\d{13}$"}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing parameter (rejected free, before any payment challenge)"},"402":{"description":"Payment Required (x402: $0.01 USDC on Base)"}}}},"/v1/loan-check":{"get":{"operationId":"verify_loan_check","summary":"Independent lawfulness check of a South African credit agreement's interest rate against the National Credit Act (NCA) Regulation 42 maximum rate caps, the statutory interest rate cap that replaced the old usury limits: the maximum rate is fixed at the repo rate on the date the agreement was concluded","description":"Independent lawfulness check of a South African credit agreement's interest rate against the National Credit Act (NCA) Regulation 42 maximum rate caps, the statutory interest rate cap that replaced the old usury limits: the maximum rate is fixed at the repo rate on the date the agreement was concluded. Covers every Reg 42 credit type including mortgage agreements, credit facilities, unsecured credit, short-term credit and developmental credit. Verdict, exact cap, excess and full workings, from daily-audited SARB and gazette data, for credit providers, compliance teams and the interest-rate limb of a reckless-lending or affordability review. Covers every agreement under the current Regulation 42 table (concluded 2016-05-06 or later). Also callable as /v1/loan-check/{credit_type}/{annual_rate_percent}/{date_concluded}. Example: /v1/loan-check?credit_type=unsecured&annual_rate_percent=28.5&date_concluded=2024-03-15","tags":["Verification"],"parameters":[{"name":"credit_type","in":"query","required":true,"description":"string, required: unsecured | mortgage | credit_facility | developmental | other | short_term | incidental","schema":{"type":"string","enum":["unsecured","mortgage","credit_facility","developmental","other","short_term","incidental"]}},{"name":"annual_rate_percent","in":"query","required":true,"description":"number, required for repo-linked types (unsecured, mortgage, credit_facility, developmental, other): the annual interest rate charged","schema":{"type":"number"}},{"name":"date_concluded","in":"query","required":true,"description":"date YYYY-MM-DD, required for repo-linked types: the date the agreement was entered into","schema":{"type":"string","format":"date"}},{"name":"monthly_rate_percent","in":"query","required":false,"description":"number, for monthly-capped types (short_term, incidental): the monthly interest rate charged","schema":{"type":"number"}},{"name":"subsequent_loan","in":"query","required":false,"description":"true or false, short_term only: a subsequent loan in the same calendar year (3% per month cap instead of 5%)","schema":{"type":"string"}},{"name":"monthly_service_fee_zar","in":"query","required":false,"description":"number, optional: the monthly service fee charged, checked against the cap","schema":{"type":"number"}}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.250000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing parameter (rejected free, before any payment challenge)"},"402":{"description":"Payment Required (x402: $0.25 USDC on Base)"}}}},"/v1/bulk-validate":{"post":{"operationId":"verify_bulk_validate","summary":"Validate up to 50 South African identifiers in one settled call: ID numbers, VAT numbers, or a mix","description":"Validate up to 50 South African identifiers in one settled call: ID numbers, VAT numbers, or a mix. Batch screening of a customer or supplier list for structurally invalid South African identifiers, for onboarding, KYC and KYB compliance clean-ups. Same checks and same honest scope as the single endpoints, with a summary of how many passed. Cheaper than five individual ID checks and a single round trip instead of fifty. Example body: {\"ids\":[\"8001015009087\",\"0501015009084\"],\"vats\":[\"4012345676\"]}","tags":["Verification"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"array of 13-digit SA ID numbers, optional: up to 50 combined with vats"},"vats":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"array of SA VAT numbers, optional: up to 50 combined with ids"}},"additionalProperties":false},"example":{"ids":["8001015009087","0501015009084"],"vats":["4012345676"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing parameter (rejected free, before any payment challenge)"},"402":{"description":"Payment Required (x402: $0.05 USDC on Base)"},"405":{"description":"Non-POST method"}}}}}}