> ## Documentation Index > Fetch the complete documentation index at: https://docs.caratuva.com/llms.txt > Use this file to discover all available pages before exploring further. # Start buyer KYC via the settlement partner > Submit an individual KYC or business KYB dossier for the buyer (identified by email; the Buyer record is upserted). The dossier is forwarded to our settlement partner for verification and a submission in the `verifying` state is returned. If the buyer is already `verifying` or `approved`, the existing submission is returned unchanged. File fields take pre-hosted HTTPS URLs (mint them via `/buyer-kyc/{buyerId}/upload-url`). ## OpenAPI ````yaml https://api.caratuva.com/docs-json post /v1/buyer-kyc openapi: 3.0.0 info: title: Caratuva API description: >- Cross-border B2B payments. Fiat on-ramp → USDC → PIX off-ramp. Every request runs in **test** or **live** mode on this single host — there is no separate sandbox URL. API keys carry the mode in their prefix (`pk_test_…` / `pk_live_…`); dashboard JWTs start in test and re-mint via `POST /v1/auth/switch-mode`. Test mode runs the full pipeline against a sandbox payment instance (KYB/KYC auto-approve, no real money); live runs on real rails and requires approved KYB. Test and live data are fully isolated. Check readiness with `GET /v1/onboarding/status`. version: 1.0.0 contact: {} servers: [] security: [] tags: - name: Invoices description: Create and manage invoices that collect for one of your sellers. - name: Payments description: Create a payment (keep your own checkout), fetch it, or cancel it. - name: Accounts description: >- Onboard and manage your sellers, buyers, and your own (self) account at the settlement partner. - name: Webhooks description: Subscribe to outbound event notifications and manage signing secrets. - name: API keys description: Issue, list, and revoke the API keys that authenticate your integration. - name: Access description: Request and check production (live-mode) access for your organization. - name: Reports description: Pull settlement and transfer-pricing reports. paths: /v1/buyer-kyc: post: tags: - Accounts summary: Start buyer KYC via the settlement partner description: >- Submit an individual KYC or business KYB dossier for the buyer (identified by email; the Buyer record is upserted). The dossier is forwarded to our settlement partner for verification and a submission in the `verifying` state is returned. If the buyer is already `verifying` or `approved`, the existing submission is returned unchanged. File fields take pre-hosted HTTPS URLs (mint them via `/buyer-kyc/{buyerId}/upload-url`). operationId: BuyerKycController_initiate parameters: [] requestBody: required: true content: application/json: schema: type: object properties: entityType: type: string enum: - individual - business buyerEmail: type: string format: email buyerName: type: string minLength: 1 maxLength: 200 buyerCountry: type: string minLength: 2 maxLength: 2 phone: type: string minLength: 3 maxLength: 32 invoiceId: type: string minLength: 1 tosId: type: string minLength: 1 kycTier: type: string enum: - standard - enhanced firstName: type: string minLength: 1 maxLength: 100 lastName: type: string minLength: 1 maxLength: 100 dateOfBirth: type: string taxId: type: string minLength: 1 maxLength: 64 addressLine1: type: string minLength: 1 maxLength: 200 addressLine2: type: string maxLength: 200 city: type: string minLength: 1 maxLength: 120 stateProvinceRegion: type: string minLength: 1 maxLength: 120 postalCode: type: string minLength: 1 maxLength: 32 idDocCountry: type: string minLength: 2 maxLength: 2 idDocType: type: string enum: - PASSPORT - ID_CARD - DRIVERS idDocNumber: type: string minLength: 1 maxLength: 64 selfieFile: type: string format: uri idDocFrontFile: type: string format: uri idDocBackFile: type: string format: uri legalName: type: string minLength: 1 maxLength: 200 formationDate: type: string website: type: string format: uri incorporationDocFile: type: string format: uri proofOfOwnershipDocFile: type: string format: uri proofOfAddressDocType: type: string enum: - UTILITY_BILL - BANK_STATEMENT - RENTAL_AGREEMENT - TAX_DOCUMENT - GOVERNMENT_CORRESPONDENCE proofOfAddressDocFile: type: string format: uri owners: type: array items: type: object properties: role: type: string enum: - beneficial_controlling - beneficial_owner - controlling_person firstName: type: string minLength: 1 maxLength: 100 lastName: type: string minLength: 1 maxLength: 100 dateOfBirth: type: string pattern: ^\d{4}-\d{2}-\d{2}$ taxId: type: string minLength: 1 maxLength: 64 taxType: type: string enum: - SSN - ITIN addressLine1: type: string minLength: 1 maxLength: 200 addressLine2: type: string maxLength: 200 city: type: string minLength: 1 maxLength: 120 stateProvinceRegion: type: string minLength: 1 maxLength: 120 postalCode: type: string minLength: 1 maxLength: 32 country: type: string minLength: 2 maxLength: 2 phone: type: string minLength: 3 maxLength: 32 idDocCountry: type: string minLength: 2 maxLength: 2 idDocType: type: string enum: - PASSPORT - ID_CARD - DRIVERS idDocNumber: type: string minLength: 1 maxLength: 64 selfieFile: type: string format: uri idDocFrontFile: type: string format: uri idDocBackFile: type: string format: uri proofOfAddressDocType: type: string enum: - UTILITY_BILL - BANK_STATEMENT - RENTAL_AGREEMENT - TAX_DOCUMENT - GOVERNMENT_CORRESPONDENCE proofOfAddressDocFile: type: string format: uri required: - role - firstName - lastName - dateOfBirth - taxId - addressLine1 - city - stateProvinceRegion - postalCode - country - idDocCountry - idDocType - selfieFile - idDocFrontFile - proofOfAddressDocType - proofOfAddressDocFile additionalProperties: false minItems: 1 maxItems: 10 required: - buyerEmail additionalProperties: false examples: default: value: entityType: individual buyerEmail: buyer@acme.com firstName: Ana lastName: Silva buyerCountry: BR dateOfBirth: '1990-04-12' taxId: '12345678900' addressLine1: Rua das Flores 123 city: Florianópolis stateProvinceRegion: SC postalCode: 88000-000 idDocCountry: BR idDocType: PASSPORT selfieFile: https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg idDocFrontFile: https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg responses: '201': description: >- Buyer KYC submission created (or the in-flight submission if one already exists) content: application/json: schema: type: object properties: id: type: string buyerId: type: string receiverId: type: string status: type: string enum: - not_started - pending - verifying - approved - rejected hostedFlowUrl: type: string nullable: true submittedAt: type: string approvedAt: type: string nullable: true rejectedAt: type: string nullable: true required: - id - buyerId - receiverId - status - hostedFlowUrl - submittedAt - approvedAt - rejectedAt additionalProperties: false examples: default: value: id: ckkyc001 buyerId: ckbuy001 receiverId: rcv_8f1a2b3c status: verifying hostedFlowUrl: null submittedAt: '2026-06-30T12:00:00.000Z' approvedAt: null rejectedAt: null '400': description: >- TosIdMismatch — tosId does not match the value previously recorded for this buyer (also: missing required fields for the entityType). content: application/json: schema: type: object properties: statusCode: type: integer example: 400 error: type: string example: TosIdMismatch message: type: string example: >- tosId does not match the value previously recorded for this buyer (also: missing required fields for the entityType). security: - apiKey: [] - bearer: [] components: securitySchemes: apiKey: type: apiKey in: header name: X-API-Key bearer: scheme: bearer bearerFormat: JWT type: http ````