> ## 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. # Create a payment > Integrator-facing: keep your own CMS and push a thin intent describing what to collect, where to settle, and what to render on the hosted buyer-portal page. Caratuva runs the payment, mandatory buyer KYC, on-chain transfer, and PIX off-ramp. Name the seller with `sellerExternalId` (a ready-to-collect connected account) and the buyer with either `buyerExternalId` (a pre-created account, KYC reused) or a `buyer` object (`email` required, KYC'd at pay-time). Send an `Idempotency-Key` header to make retries safe. Returns the `hostedPaymentUrl` to forward to your customer. ## OpenAPI ````yaml https://api.caratuva.com/docs-json post /v1/payments 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/payments: post: tags: - Payments summary: Create a payment description: >- Integrator-facing: keep your own CMS and push a thin intent describing what to collect, where to settle, and what to render on the hosted buyer-portal page. Caratuva runs the payment, mandatory buyer KYC, on-chain transfer, and PIX off-ramp. Name the seller with `sellerExternalId` (a ready-to-collect connected account) and the buyer with either `buyerExternalId` (a pre-created account, KYC reused) or a `buyer` object (`email` required, KYC'd at pay-time). Send an `Idempotency-Key` header to make retries safe. Returns the `hostedPaymentUrl` to forward to your customer. operationId: PaymentIntentsController_create parameters: - name: Idempotency-Key in: header required: false schema: type: string requestBody: required: true content: application/json: schema: type: object properties: externalId: type: string minLength: 1 maxLength: 200 amount: type: string pattern: ^\d+(\.\d{1,2})?$ currency: type: string minLength: 3 maxLength: 3 default: USD buyerExternalId: type: string minLength: 1 maxLength: 200 buyer: type: object properties: email: type: string format: email name: type: string minLength: 1 maxLength: 200 country: type: string minLength: 2 maxLength: 2 phone: type: string minLength: 1 maxLength: 40 required: - email additionalProperties: false returnUrl: type: string format: uri metadata: type: object additionalProperties: {} display: type: object properties: title: type: string minLength: 1 maxLength: 200 notes: type: string maxLength: 2000 lineItems: type: array items: type: object properties: description: type: string minLength: 1 maxLength: 500 quantity: type: string unitPrice: type: string subtotal: type: string required: - description additionalProperties: false maxItems: 500 additionalProperties: false expiresAt: type: string format: date-time sellerExternalId: type: string minLength: 1 maxLength: 200 affiliate: type: object properties: connectedAccountExternalId: type: string minLength: 1 shareBps: type: integer exclusiveMinimum: true minimum: 0 maximum: 10000 required: - connectedAccountExternalId - shareBps additionalProperties: false required: - externalId - amount - sellerExternalId additionalProperties: false examples: default: value: externalId: INV-2026-00042 amount: '12500.00' currency: USD sellerExternalId: seller-42 buyer: email: buyer@acme.com name: ACME Imports LLC country: US returnUrl: https://shop.example.com/orders/42/return metadata: orderId: order_42 source: storefront display: title: 'Order #42 — green coffee, 18t' lineItems: - description: Green coffee, 18t quantity: '1' unitPrice: '12500.00' subtotal: '12500.00' responses: '201': description: Payment created content: application/json: schema: type: object properties: id: type: string externalId: type: string status: type: string enum: - draft - awaiting_approval - approved - awaiting_buyer - buyer_kyc_pending - buyer_kyc_approved - buyer_kyc_rejected - fx_quoted - fx_expired - on_ramp_pending - on_ramp_failed - fiat_received - on_chain_confirmed - offramp_pending - offramp_failed - settled - partial_payment - expired - cancelled - restored - manual_review amount: type: string currency: type: string hostedPaymentUrl: type: string buyer: type: object properties: id: type: string email: type: string format: email name: type: string nullable: true country: type: string nullable: true kycStatus: type: string enum: - not_started - pending - verifying - approved - rejected required: - id - email - name - country - kycStatus additionalProperties: false returnUrl: type: string nullable: true metadata: type: object additionalProperties: {} nullable: true display: type: object properties: title: type: string minLength: 1 maxLength: 200 notes: type: string maxLength: 2000 lineItems: type: array items: type: object properties: description: type: string minLength: 1 maxLength: 500 quantity: type: string unitPrice: type: string subtotal: type: string required: - description additionalProperties: false maxItems: 500 additionalProperties: false nullable: true paymentChain: type: string nullable: true paymentAddress: type: string nullable: true brlSettledAmount: type: string nullable: true fxRateAtSettlement: type: string nullable: true expiresAt: type: string nullable: true cancelReason: type: string nullable: true createdAt: type: string updatedAt: type: string affiliate: type: object properties: connectedAccountExternalId: type: string shareBps: type: number feeAmount: type: string required: - connectedAccountExternalId - shareBps - feeAmount additionalProperties: false nullable: true required: - id - externalId - status - amount - currency - hostedPaymentUrl - buyer - returnUrl - metadata - display - paymentChain - paymentAddress - brlSettledAmount - fxRateAtSettlement - expiresAt - cancelReason - createdAt - updatedAt additionalProperties: false examples: default: value: id: ckxinv042 externalId: INV-2026-00042 status: awaiting_buyer amount: '12500.00' currency: USD hostedPaymentUrl: https://pay.caratuva.com/i/ckpub042 buyer: id: ckbuy001 email: buyer@acme.com name: ACME Imports LLC country: US kycStatus: not_started returnUrl: https://shop.example.com/orders/42/return metadata: orderId: order_42 source: storefront display: title: 'Order #42 — green coffee, 18t' lineItems: - description: Green coffee, 18t quantity: '1' unitPrice: '12500.00' subtotal: '12500.00' paymentChain: base paymentAddress: 0x5fbe…a91c brlSettledAmount: null fxRateAtSettlement: null expiresAt: null cancelReason: null createdAt: '2026-06-30T12:00:00.000Z' updatedAt: '2026-06-30T12:00:00.000Z' '400': description: >- AmountBelowMinimum — The amount is below the bank-transfer on-ramp minimum (also: the seller is not ready-to-collect, or neither buyerExternalId nor a buyer object was provided). content: application/json: schema: type: object properties: statusCode: type: integer example: 400 error: type: string example: AmountBelowMinimum message: type: string example: >- The amount is below the bank-transfer on-ramp minimum (also: the seller is not ready-to-collect, or neither buyerExternalId nor a buyer object was provided). security: - apiKey: [] - bearer: [] components: securitySchemes: apiKey: type: apiKey in: header name: X-API-Key bearer: scheme: bearer bearerFormat: JWT type: http ````