From 7a6399e7084bc7d05bf01bb44c0d66ab529255e2 Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Wed, 25 Mar 2026 14:49:01 -0700 Subject: [PATCH] feat: updating document missing errors to be more specific --- mintlify/openapi.yaml | 46 +++++++++++++------ openapi.yaml | 46 +++++++++++++------ .../schemas/common/NgnAccountInfo.yaml | 2 +- .../schemas/common/PhpAccountInfo.yaml | 2 +- .../schemas/common/SgdAccountInfo.yaml | 2 +- .../schemas/documents/DocumentType.yaml | 26 ++++++++++- .../verifications/VerificationError.yaml | 24 +++++++++- .../verifications/VerificationErrorType.yaml | 12 ++++- openapi/paths/customers/customers.yaml | 2 +- .../paths/verifications/verifications.yaml | 4 +- openapi/webhooks/verification-update.yaml | 4 +- 11 files changed, 128 insertions(+), 42 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 7863d0d8..764518dd 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -296,7 +296,7 @@ paths: taxId: 47-1234567 countriesOfOperation: - US - businessType: FINTECH + businessType: INFORMATION purposeOfAccount: CONTRACTOR_PAYOUTS sourceOfFunds: Funds derived from customer payments for software services expectedMonthlyTransactionCount: COUNT_100_TO_500 @@ -1611,11 +1611,9 @@ paths: field: customer.address.line1 reason: Business address line 1 is required - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001 - type: MISSING_DOCUMENT + type: MISSING_PROOF_OF_ADDRESS_DOCUMENT acceptedDocumentTypes: - PROOF_OF_ADDRESS - - UTILITY_BILL - - BANK_STATEMENT reason: Proof of address document is required - resourceId: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002 type: MISSING_FIELD @@ -4565,11 +4563,9 @@ webhooks: verificationStatus: RESOLVE_ERRORS errors: - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001 - type: MISSING_DOCUMENT + type: MISSING_PROOF_OF_ADDRESS_DOCUMENT acceptedDocumentTypes: - PROOF_OF_ADDRESS - - UTILITY_BILL - - BANK_STATEMENT reason: Proof of address document is required createdAt: '2025-08-15T14:00:00Z' responses: @@ -6003,7 +5999,7 @@ components: description: Nigerian bank account number minLength: 10 maxLength: 10 - example: 123456789 + example: '0123456789' pattern: ^[0-9]{10}$ bankName: type: string @@ -6309,7 +6305,7 @@ components: description: Bank account number minLength: 1 maxLength: 34 - example: 1234567890 + example: '001234567890' PaymentPhpAccountInfo: title: PHP Account allOf: @@ -6355,7 +6351,7 @@ components: description: Bank account number minLength: 1 maxLength: 34 - example: 123456789 + example: '0123456789' swiftCode: type: string description: The SWIFT/BIC code of the bank @@ -9220,7 +9216,14 @@ components: - UTILITY_BILL - SELFIE - OTHER - description: Type of identity or business verification document + description: |- + Type of identity or business verification document. Document types are grouped by verification category: + **Identity** — PASSPORT, DRIVERS_LICENSE, NATIONAL_ID + **Business — Legal presence** — CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT + **Business — Company details** — INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE + **Business — Control structure** — ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT + **Business — Ownership structure** — SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION + **Proof of address** — PROOF_OF_ADDRESS example: PASSPORT Document: type: object @@ -9330,11 +9333,16 @@ components: enum: - MISSING_FIELD - INVALID_FIELD - - MISSING_DOCUMENT + - MISSING_LEGAL_PRESENCE_DOCUMENT + - MISSING_COMPANY_DETAILS_DOCUMENT + - MISSING_CONTROL_STRUCTURE_DOCUMENT + - MISSING_OWNERSHIP_STRUCTURE_DOCUMENT + - MISSING_PROOF_OF_ADDRESS_DOCUMENT + - MISSING_IDENTITY_DOCUMENT - INVALID_DOCUMENT - EXPIRED_DOCUMENT - MISSING_BENEFICIAL_OWNER - description: Type of verification error + description: Type of verification error. The category-specific MISSING_*_DOCUMENT types indicate which document category is needed and determine the accepted document types returned in acceptedDocumentTypes. example: MISSING_FIELD VerificationError: type: object @@ -9357,7 +9365,17 @@ components: type: array items: $ref: '#/components/schemas/DocumentType' - description: Document types that would satisfy this requirement. The integrator can upload any one of the listed types. Present when type is MISSING_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT. + description: |- + Document types that would satisfy this requirement. The integrator can upload any one of the listed types. Present when type is MISSING_LEGAL_PRESENCE_DOCUMENT, MISSING_COMPANY_DETAILS_DOCUMENT, MISSING_CONTROL_STRUCTURE_DOCUMENT, MISSING_OWNERSHIP_STRUCTURE_DOCUMENT, MISSING_PROOF_OF_ADDRESS_DOCUMENT, MISSING_IDENTITY_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT. + + | Error Type | Accepted Document Types | + |---|---| + | MISSING_LEGAL_PRESENCE_DOCUMENT | CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT | + | MISSING_COMPANY_DETAILS_DOCUMENT | INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE | + | MISSING_CONTROL_STRUCTURE_DOCUMENT | ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT | + | MISSING_OWNERSHIP_STRUCTURE_DOCUMENT | SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION | + | MISSING_PROOF_OF_ADDRESS_DOCUMENT | PROOF_OF_ADDRESS | + | MISSING_IDENTITY_DOCUMENT | PASSPORT, DRIVERS_LICENSE, NATIONAL_ID | reason: type: string description: Human-readable description of the issue diff --git a/openapi.yaml b/openapi.yaml index 7863d0d8..764518dd 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -296,7 +296,7 @@ paths: taxId: 47-1234567 countriesOfOperation: - US - businessType: FINTECH + businessType: INFORMATION purposeOfAccount: CONTRACTOR_PAYOUTS sourceOfFunds: Funds derived from customer payments for software services expectedMonthlyTransactionCount: COUNT_100_TO_500 @@ -1611,11 +1611,9 @@ paths: field: customer.address.line1 reason: Business address line 1 is required - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001 - type: MISSING_DOCUMENT + type: MISSING_PROOF_OF_ADDRESS_DOCUMENT acceptedDocumentTypes: - PROOF_OF_ADDRESS - - UTILITY_BILL - - BANK_STATEMENT reason: Proof of address document is required - resourceId: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002 type: MISSING_FIELD @@ -4565,11 +4563,9 @@ webhooks: verificationStatus: RESOLVE_ERRORS errors: - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001 - type: MISSING_DOCUMENT + type: MISSING_PROOF_OF_ADDRESS_DOCUMENT acceptedDocumentTypes: - PROOF_OF_ADDRESS - - UTILITY_BILL - - BANK_STATEMENT reason: Proof of address document is required createdAt: '2025-08-15T14:00:00Z' responses: @@ -6003,7 +5999,7 @@ components: description: Nigerian bank account number minLength: 10 maxLength: 10 - example: 123456789 + example: '0123456789' pattern: ^[0-9]{10}$ bankName: type: string @@ -6309,7 +6305,7 @@ components: description: Bank account number minLength: 1 maxLength: 34 - example: 1234567890 + example: '001234567890' PaymentPhpAccountInfo: title: PHP Account allOf: @@ -6355,7 +6351,7 @@ components: description: Bank account number minLength: 1 maxLength: 34 - example: 123456789 + example: '0123456789' swiftCode: type: string description: The SWIFT/BIC code of the bank @@ -9220,7 +9216,14 @@ components: - UTILITY_BILL - SELFIE - OTHER - description: Type of identity or business verification document + description: |- + Type of identity or business verification document. Document types are grouped by verification category: + **Identity** — PASSPORT, DRIVERS_LICENSE, NATIONAL_ID + **Business — Legal presence** — CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT + **Business — Company details** — INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE + **Business — Control structure** — ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT + **Business — Ownership structure** — SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION + **Proof of address** — PROOF_OF_ADDRESS example: PASSPORT Document: type: object @@ -9330,11 +9333,16 @@ components: enum: - MISSING_FIELD - INVALID_FIELD - - MISSING_DOCUMENT + - MISSING_LEGAL_PRESENCE_DOCUMENT + - MISSING_COMPANY_DETAILS_DOCUMENT + - MISSING_CONTROL_STRUCTURE_DOCUMENT + - MISSING_OWNERSHIP_STRUCTURE_DOCUMENT + - MISSING_PROOF_OF_ADDRESS_DOCUMENT + - MISSING_IDENTITY_DOCUMENT - INVALID_DOCUMENT - EXPIRED_DOCUMENT - MISSING_BENEFICIAL_OWNER - description: Type of verification error + description: Type of verification error. The category-specific MISSING_*_DOCUMENT types indicate which document category is needed and determine the accepted document types returned in acceptedDocumentTypes. example: MISSING_FIELD VerificationError: type: object @@ -9357,7 +9365,17 @@ components: type: array items: $ref: '#/components/schemas/DocumentType' - description: Document types that would satisfy this requirement. The integrator can upload any one of the listed types. Present when type is MISSING_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT. + description: |- + Document types that would satisfy this requirement. The integrator can upload any one of the listed types. Present when type is MISSING_LEGAL_PRESENCE_DOCUMENT, MISSING_COMPANY_DETAILS_DOCUMENT, MISSING_CONTROL_STRUCTURE_DOCUMENT, MISSING_OWNERSHIP_STRUCTURE_DOCUMENT, MISSING_PROOF_OF_ADDRESS_DOCUMENT, MISSING_IDENTITY_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT. + + | Error Type | Accepted Document Types | + |---|---| + | MISSING_LEGAL_PRESENCE_DOCUMENT | CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT | + | MISSING_COMPANY_DETAILS_DOCUMENT | INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE | + | MISSING_CONTROL_STRUCTURE_DOCUMENT | ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT | + | MISSING_OWNERSHIP_STRUCTURE_DOCUMENT | SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION | + | MISSING_PROOF_OF_ADDRESS_DOCUMENT | PROOF_OF_ADDRESS | + | MISSING_IDENTITY_DOCUMENT | PASSPORT, DRIVERS_LICENSE, NATIONAL_ID | reason: type: string description: Human-readable description of the issue diff --git a/openapi/components/schemas/common/NgnAccountInfo.yaml b/openapi/components/schemas/common/NgnAccountInfo.yaml index 3f6feeaa..fe0565ab 100644 --- a/openapi/components/schemas/common/NgnAccountInfo.yaml +++ b/openapi/components/schemas/common/NgnAccountInfo.yaml @@ -20,7 +20,7 @@ properties: description: Nigerian bank account number minLength: 10 maxLength: 10 - example: 0123456789 + example: '0123456789' pattern: ^[0-9]{10}$ bankName: type: string diff --git a/openapi/components/schemas/common/PhpAccountInfo.yaml b/openapi/components/schemas/common/PhpAccountInfo.yaml index 1d3f38b7..5d433a2f 100644 --- a/openapi/components/schemas/common/PhpAccountInfo.yaml +++ b/openapi/components/schemas/common/PhpAccountInfo.yaml @@ -26,4 +26,4 @@ properties: description: Bank account number minLength: 1 maxLength: 34 - example: 001234567890 + example: '001234567890' diff --git a/openapi/components/schemas/common/SgdAccountInfo.yaml b/openapi/components/schemas/common/SgdAccountInfo.yaml index f775c995..423e544c 100644 --- a/openapi/components/schemas/common/SgdAccountInfo.yaml +++ b/openapi/components/schemas/common/SgdAccountInfo.yaml @@ -29,7 +29,7 @@ properties: description: Bank account number minLength: 1 maxLength: 34 - example: 0123456789 + example: '0123456789' swiftCode: type: string description: The SWIFT/BIC code of the bank diff --git a/openapi/components/schemas/documents/DocumentType.yaml b/openapi/components/schemas/documents/DocumentType.yaml index f2be3bc1..895c04a8 100644 --- a/openapi/components/schemas/documents/DocumentType.yaml +++ b/openapi/components/schemas/documents/DocumentType.yaml @@ -19,5 +19,29 @@ enum: - UTILITY_BILL - SELFIE - OTHER -description: Type of identity or business verification document +description: >- + Type of identity or business verification document. Document types are + grouped by verification category: + + **Identity** — PASSPORT, DRIVERS_LICENSE, NATIONAL_ID + + **Business — Legal presence** — CERTIFICATE_OF_INCORPORATION, + ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, + STATE_REGISTRY_EXCERPT + + **Business — Company details** — INFORMATION_STATEMENT, + STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, + ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, + INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE + + **Business — Control structure** — ARTICLES_OF_INCORPORATION, + ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, + INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT + + **Business — Ownership structure** — SHAREHOLDER_REGISTER, + INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, + STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, + ARTICLES_OF_ASSOCIATION + + **Proof of address** — PROOF_OF_ADDRESS example: PASSPORT diff --git a/openapi/components/schemas/verifications/VerificationError.yaml b/openapi/components/schemas/verifications/VerificationError.yaml index af397641..58add0d5 100644 --- a/openapi/components/schemas/verifications/VerificationError.yaml +++ b/openapi/components/schemas/verifications/VerificationError.yaml @@ -24,7 +24,29 @@ properties: description: >- Document types that would satisfy this requirement. The integrator can upload any one of the listed types. Present when type is - MISSING_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT. + MISSING_LEGAL_PRESENCE_DOCUMENT, + MISSING_COMPANY_DETAILS_DOCUMENT, + MISSING_CONTROL_STRUCTURE_DOCUMENT, + MISSING_OWNERSHIP_STRUCTURE_DOCUMENT, + MISSING_PROOF_OF_ADDRESS_DOCUMENT, + MISSING_IDENTITY_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT. + + + | Error Type | Accepted Document Types | + + |---|---| + + | MISSING_LEGAL_PRESENCE_DOCUMENT | CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT | + + | MISSING_COMPANY_DETAILS_DOCUMENT | INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE | + + | MISSING_CONTROL_STRUCTURE_DOCUMENT | ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT | + + | MISSING_OWNERSHIP_STRUCTURE_DOCUMENT | SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION | + + | MISSING_PROOF_OF_ADDRESS_DOCUMENT | PROOF_OF_ADDRESS | + + | MISSING_IDENTITY_DOCUMENT | PASSPORT, DRIVERS_LICENSE, NATIONAL_ID | reason: type: string description: Human-readable description of the issue diff --git a/openapi/components/schemas/verifications/VerificationErrorType.yaml b/openapi/components/schemas/verifications/VerificationErrorType.yaml index 0f6421b8..383b9f0d 100644 --- a/openapi/components/schemas/verifications/VerificationErrorType.yaml +++ b/openapi/components/schemas/verifications/VerificationErrorType.yaml @@ -2,9 +2,17 @@ type: string enum: - MISSING_FIELD - INVALID_FIELD - - MISSING_DOCUMENT + - MISSING_LEGAL_PRESENCE_DOCUMENT + - MISSING_COMPANY_DETAILS_DOCUMENT + - MISSING_CONTROL_STRUCTURE_DOCUMENT + - MISSING_OWNERSHIP_STRUCTURE_DOCUMENT + - MISSING_PROOF_OF_ADDRESS_DOCUMENT + - MISSING_IDENTITY_DOCUMENT - INVALID_DOCUMENT - EXPIRED_DOCUMENT - MISSING_BENEFICIAL_OWNER -description: Type of verification error +description: >- + Type of verification error. The category-specific MISSING_*_DOCUMENT + types indicate which document category is needed and determine the + accepted document types returned in acceptedDocumentTypes. example: MISSING_FIELD diff --git a/openapi/paths/customers/customers.yaml b/openapi/paths/customers/customers.yaml index 454a9833..fedb5733 100644 --- a/openapi/paths/customers/customers.yaml +++ b/openapi/paths/customers/customers.yaml @@ -38,7 +38,7 @@ post: taxId: 47-1234567 countriesOfOperation: - US - businessType: FINTECH + businessType: INFORMATION purposeOfAccount: CONTRACTOR_PAYOUTS sourceOfFunds: Funds derived from customer payments for software services expectedMonthlyTransactionCount: COUNT_100_TO_500 diff --git a/openapi/paths/verifications/verifications.yaml b/openapi/paths/verifications/verifications.yaml index c8b41203..55927258 100644 --- a/openapi/paths/verifications/verifications.yaml +++ b/openapi/paths/verifications/verifications.yaml @@ -41,11 +41,9 @@ post: field: customer.address.line1 reason: Business address line 1 is required - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001 - type: MISSING_DOCUMENT + type: MISSING_PROOF_OF_ADDRESS_DOCUMENT acceptedDocumentTypes: - PROOF_OF_ADDRESS - - UTILITY_BILL - - BANK_STATEMENT reason: Proof of address document is required - resourceId: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002 type: MISSING_FIELD diff --git a/openapi/webhooks/verification-update.yaml b/openapi/webhooks/verification-update.yaml index 4328ad00..b4dcdc7c 100644 --- a/openapi/webhooks/verification-update.yaml +++ b/openapi/webhooks/verification-update.yaml @@ -61,11 +61,9 @@ post: verificationStatus: RESOLVE_ERRORS errors: - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001 - type: MISSING_DOCUMENT + type: MISSING_PROOF_OF_ADDRESS_DOCUMENT acceptedDocumentTypes: - PROOF_OF_ADDRESS - - UTILITY_BILL - - BANK_STATEMENT reason: Proof of address document is required createdAt: '2025-08-15T14:00:00Z' responses: