{ "openapi": "3.0.1", "info": { "title": "Account Verification API", "description": "Spare account verification API documentation", "termsOfService": "https://terms.tryspare.com/en", "contact": { "name": "Spare Arabian Financial Co.", "email": "hello@tryspare.com" }, "license": { "name": "Spare Arabian Financial Co." }, "version": "2.1" }, "paths": { "/api/v2.1/av/AccountVerificationPro/Match": { "post": { "tags": [ "AccountVerificationPro" ], "summary": "Verifies if the provided IBAN and ID match and retrieves the beneficiary name associated with the IBAN.", "description": "**Unique resource name :** av.v2.1.account_verification_pro.match\r\n \r\n**Important!:**\r\n- The IBAN must be a valid KSA IBAN.\r\n- The `idValue` must be valid according to the required format (e.g., National ID, Iqama number, or Registration number).\r\n- The request validates the IBAN and ID match and also fetches the associated beneficiary name.", "requestBody": { "description": "The model containing the IBAN and ID for verification, along with any other necessary information.\r\nIt also includes details for retrieving the associated beneficiary name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonAccountVerificationRequest" } } }, "required": true }, "responses": { "200": { "description": "Verification was successful. The response includes details of the matched account and the beneficiary name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonAccountVerificationResponseAccountVerificationApiResponse" } } } }, "400": { "description": "Bad Request. This response is returned if:\r\n- The provided request model is invalid.\r\n- The IBAN is not a valid KSA IBAN.\r\n- The `idValue` does not meet the required validation criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error" } } } }, "/api/v2.1/av/AccountVerificationPro/Corporate": { "post": { "tags": [ "AccountVerificationPro" ], "summary": "Verifies a corporate account by matching the IBAN with the provided Company Registration (CR) or Unified National Number (UNN)\r\nand combines it with Beneficiary Verification.", "description": "**Unique resource name :** av.v2.1.account_verification_pro.corporate\r\n \r\n**Important!:**\r\n- The IBAN must be a valid KSA IBAN.\r\n- The CR or UNN must be valid 10-digit numbers.\r\n- The beneficiaryName will be verified against the account holder name.", "requestBody": { "description": "The model containing the corporate verification request details with beneficiary information.\r\nThis includes the IBAN, CR, UNN, and beneficiary name to be validated in this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorporateBeneficiaryVerificationRequest" } } }, "required": true }, "responses": { "200": { "description": "Verification was successful. The response includes the verification details for both the corporate ID and beneficiary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonCorporateVerificationResponseAccountVerificationApiResponse" } } } }, "400": { "description": "Bad Request. This response is returned if:\r\n- The provided request model is invalid.\r\n- The IBAN, CR, or UNN does not meet the required format or validation criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal Server Error" } } } } }, "components": { "schemas": { "AccountVerificationApiError": { "enum": [ "INVALID_DATA", "ACCOUNT_VERIFICATION_FAILED", "SERVER_ERROR", "SUBSCRIPTION_EXPIRED" ], "type": "string" }, "AccountVerificationIdType": { "enum": [ "NATIONAL_ID", "COMPANY_REGISTRATION_NUMBER", "IQAMA", "UNN", "UNKNOWN" ], "type": "string" }, "ApiError": { "enum": [ "INVALID_DATA", "INVALID_SIGNATURE", "RESOURCE_LOCKED", "COUNTRY_NOT_FOUND", "CURRENCY_NOT_FOUND", "PROVIDER_NOT_FOUND", "CONNECTION_NOT_FOUND", "INSUFFICIENT_CONSENT_PERMISSIONS", "CONSENT_EXPIRED", "CONSENT_REVOKED", "CONSENT_UNAUTHORIZED", "CONSENT_NOT_FOUND", "ACCOUNT_INFORMATION_REPORT_NOT_FOUND", "MULTIPLE_CURRENCY_NOT_ALLOWED", "MULTIPLE_CONSENT_DATE_NOT_ALLOWED", "PAYMENT_NOT_FOUND", "CONSENT_REJECTED", "PAYMENT_REQUEST_NOT_FOUND", "CUSTOMER_NOT_FOUND", "REAL_ESTATE_VERIFY_NOT_FOUND", "REAL_ESTATE_VALIDATE_NOT_FOUND", "REAL_ESTATE_SEARCH_NOT_FOUND", "CUSTOMER_ALREADY_EXISTS", "BANK_ACCOUNT_NOT_FOUND", "SERVER_ERROR", "PROVIDER_CONNECTION_FAILURE", "TRANSACTION_NOT_FOUND", "ACCOUNT_INFORMATION_ACCESS_REQUEST_NOT_FOUND", "CONSENT_REVOCATION_FAILED", "CONSENT_REVOKED_OR_EXPIRED", "SUBSCRIPTION_EXPIRED", "NOT_SUBSCRIBED_TO_SERVICE", "BENEFICIARY_NOT_FOUND", "PARTIES_NOT_FOUND", "DIRECT_DEBIT_NOT_FOUND", "SCHEDULED_PAYMENT_NOT_FOUND", "DEBTOR_ACCOUNT_NOT_FOUND", "CREDITOR_ACCOUNT_NOT_FOUND", "UNAUTHORIZED_IP_ADDRESS", "REAL_ESTATE_FAILED" ], "type": "string" }, "Bank": { "type": "object", "properties": { "englishName": { "type": "string", "nullable": true }, "arabicName": { "type": "string", "nullable": true }, "bankCode": { "type": "string", "nullable": true }, "swiftCode": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CommonAccountVerificationRequest": { "required": [ "iban", "idValue" ], "type": "object", "properties": { "iban": { "minLength": 1, "type": "string", "description": "Account IBAN.", "example": "SA0380000000608010167519" }, "idType": { "$ref": "#/components/schemas/AccountVerificationIdType" }, "beneficiaryName": { "maxLength": 255, "type": "string", "nullable": true, "description": "Name of the beneficiary to verify or pay." }, "idValue": { "minLength": 1, "type": "string", "description": "Identification value, matching the selected ID type." } }, "additionalProperties": false }, "CommonAccountVerificationResponse": { "type": "object", "properties": { "requestId": { "type": "string", "nullable": true }, "inputBeneficiaryName": { "type": "string", "nullable": true }, "accountStatus": { "type": "string", "nullable": true }, "accountIdentifier": { "type": "string", "nullable": true }, "result": { "$ref": "#/components/schemas/VerificationResult" }, "bank": { "$ref": "#/components/schemas/Bank" }, "errorDescription": { "type": "string", "nullable": true }, "idType": { "$ref": "#/components/schemas/AccountVerificationIdType" }, "idValue": { "type": "string", "nullable": true, "description": "Identification value, matching the selected ID type." }, "beneficiaryName": { "type": "string", "nullable": true, "description": "Name of the beneficiary to verify or pay." }, "executionDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Format: ISO 8601 date-time (e.g. `2025-01-01T00:00:00Z`).", "example": "2025-01-01T00:00:00Z" } }, "additionalProperties": false }, "CommonAccountVerificationResponseAccountVerificationApiResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/AccountVerificationApiError" }, "errorDescription": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "nullable": true }, "nullable": true }, "data": { "$ref": "#/components/schemas/CommonAccountVerificationResponse" } }, "additionalProperties": false }, "CommonCorporateVerificationResponse": { "type": "object", "properties": { "requestId": { "type": "string", "nullable": true }, "inputBeneficiaryName": { "type": "string", "nullable": true }, "accountStatus": { "type": "string", "nullable": true }, "result": { "$ref": "#/components/schemas/VerificationResult" }, "bank": { "$ref": "#/components/schemas/Bank" }, "errorDescription": { "type": "string", "nullable": true }, "idType": { "$ref": "#/components/schemas/AccountVerificationIdType" }, "idValue": { "type": "string", "nullable": true, "description": "Identification value, matching the selected ID type." }, "beneficiaryName": { "type": "string", "nullable": true, "description": "Name of the beneficiary to verify or pay." }, "executionDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Format: ISO 8601 date-time (e.g. `2025-01-01T00:00:00Z`).", "example": "2025-01-01T00:00:00Z" } }, "additionalProperties": false }, "CommonCorporateVerificationResponseAccountVerificationApiResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/AccountVerificationApiError" }, "errorDescription": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "nullable": true }, "nullable": true }, "data": { "$ref": "#/components/schemas/CommonCorporateVerificationResponse" } }, "additionalProperties": false }, "CorporateBeneficiaryVerificationRequest": { "required": [ "iban" ], "type": "object", "properties": { "beneficiaryName": { "maxLength": 255, "type": "string", "nullable": true, "description": "Name of the beneficiary to verify or pay." }, "iban": { "minLength": 1, "type": "string", "description": "Account IBAN.", "example": "SA0380000000608010167519" }, "unn": { "type": "string", "nullable": true, "description": "Company or entity registration identifier." }, "companyRegistrationNumber": { "type": "string", "nullable": true, "description": "Company registration number." } }, "additionalProperties": false }, "ObjectApiResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" }, "errorDescription": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "nullable": true }, "nullable": true }, "data": { "nullable": true } }, "additionalProperties": false }, "VerificationResult": { "enum": [ "MATCH", "NO_MATCH", "ERROR" ], "type": "string" } }, "securitySchemes": { "Bearer": { "type": "apiKey", "description": "Please enter into field the word 'Bearer' followed by a space and JWT", "name": "Authorization", "in": "header" } } }, "security": [ { "Bearer": [] } ], "servers": [ { "url": "https://sandbox.sparefinancial.sa", "description": "Sandbox" } ] }