> ## Documentation Index > Fetch the complete documentation index at: https://docs.timbrix.mx/llms.txt > Use this file to discover all available pages before exploring further. # Register a payment of PPD invoices and stamp its Complemento de Pago (CFDI tipo P) > Send the paid invoices (`documents: [{ invoiceUuid, amount }]`, 1 to 50, same customer and currency). Timbrix computes the installment number, previous and remaining balances and proportional taxes, and stamps one Complemento de Pago 2.0. Each one counts as a CFDI of your plan. ## OpenAPI ````yaml https://api.timbrix.mx/api/openapi.json post /invoices/payments openapi: 3.0.0 info: title: Timbrix API description: >- API de facturación electrónica CFDI 4.0 para México, con servidor OAuth2 para gestionar organizaciones, miembros y webhooks. Compatible con agentes de IA — ver la extensión `x-ai-agent-friendly` en la raíz de esta spec. REST API with OAuth2 server for managing organizations, members, and webhooks. version: '1.0' contact: {} servers: [] security: [] tags: - name: organizations description: Organization management endpoints - name: oauth description: OAuth2 authentication and authorization - name: webhooks description: Webhook configuration and delivery - name: users description: User information endpoints - name: api-keys description: API Keys management and validation - name: request-logs description: API request log paths: /invoices/payments: post: tags: - invoices summary: >- Register a payment of PPD invoices and stamp its Complemento de Pago (CFDI tipo P) description: >- Send the paid invoices (`documents: [{ invoiceUuid, amount }]`, 1 to 50, same customer and currency). Timbrix computes the installment number, previous and remaining balances and proportional taxes, and stamps one Complemento de Pago 2.0. Each one counts as a CFDI of your plan. operationId: InvoicesController_registerPayment parameters: - name: x-timbrix-client required: true in: header schema: type: string - name: X-Timbrix-Client in: header description: 'Canal de origen del CFDI: web, api, sdk, cli o mcp.' required: false schema: type: string - name: X-Organization-Id in: header description: >- Required for Supabase session auth. Ignored when authenticating with an API key (the organization resolves from the key). required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterPaymentDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/InvoiceResponseDto' '400': description: Invalid payload, future payment date or SAT rejection '404': description: An invoice or customer was not found '409': description: >- An invoice is cancelled or being cancelled, or a stamp with this idempotencyKey is still being confirmed '422': description: >- Invoice is not PPD, amount exceeds the balance, different customer or currency security: - apiKey: [] - bearer: [] components: schemas: RegisterPaymentDto: type: object properties: customerId: type: string description: >- Cliente registrado. Si se omite, el receptor del complemento sale de la primera factura. Si se envía, su RFC debe ser el de todas las facturas. date: type: string example: '2026-10-15T12:00:00' description: Fecha y hora del pago en la Ciudad de México (sin zona horaria) paymentForm: type: string example: '03' description: Forma de pago del catálogo c_FormaPago del SAT (sin 99) currency: type: string example: MXN description: 'Default: MXN. Debe ser la moneda de las facturas.' exchange: type: number example: 18.5 description: >- Tipo de cambio a MXN. Obligatorio si `currency` no es MXN; se ignora con MXN. operationNumber: type: string example: SPEI-123 description: Número o referencia de la operación payerBankRfc: type: string description: RFC del banco del que paga payerAccount: type: string description: Cuenta del que paga payeeBankRfc: type: string description: RFC del banco que recibe payeeAccount: type: string description: Cuenta que recibe series: type: string example: P description: 'Serie del complemento. Default: P' folioNumber: type: string example: '12' description: >- Folio del complemento. Si se omite, Timbrix usa el siguiente de la organización. documents: description: Facturas PPD que liquida este pago (1 a 50) type: array items: $ref: '#/components/schemas/PaymentDocumentDto' substitutes: type: string example: 5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a description: >- Folio fiscal (UUID) del complemento de pago que este sustituye (CfdiRelacionados 04). Debe liquidar las mismas facturas; cada una conserva su número de parcialidad. Si el original sigue vigente, cancélalo después con motivo 01. idempotencyKey: type: string example: pago-8421 description: Llave para reintentar sin timbrar dos veces el mismo complemento required: - date - paymentForm - documents InvoiceResponseDto: type: object properties: id: type: string description: Timbrix invoice record ID example: 0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab uuid: type: string description: Folio fiscal UUID asignado por el SAT vía PAC example: d3bfbc57-44af-4390-a064-f0afab85e5df status: type: string enum: - vigente - cancelado example: vigente description: >- Estado fiscal del CFDI registrado en Timbrix: vigente o cancelado. Antes de TIM-243 este campo era siempre "valid". Con una cancelación pendiente (cancellationStatus: pendiente) cuyo plazo de respuesta del receptor ya venció, el SAT pudo haberlo cancelado automáticamente; confírmalo en el portal del SAT. cancellationStatus: type: string enum: - pendiente - rechazada - en_proceso nullable: true description: >- Latest cancellation attempt's status, only while the invoice is still vigente. null if never attempted or already cancelado. A pendiente past the receptor's response deadline may already be cancelado at the SAT. en_proceso: the cancellation was sent and its outcome is being confirmed with the SAT; don't treat the CFDI as vigente yet. cancellationDesynced: type: boolean description: >- true when a cancellation was accepted but the invoice status update failed to apply — indicates the invoice may already be cancelled at the SAT even though it still shows vigente here; needs manual reconciliation. example: false type: type: string enum: - I - E - T - P example: I description: I = Ingreso, E = Egreso, T = Traslado, P = Pago series: type: string example: A folioNumber: type: string example: '1' total: type: number example: 116 date: type: string example: '2026-07-30T22:50:00' xml: type: string description: XML del CFDI timbrado (UTF-8) createdAt: type: string example: '2026-07-30T22:50:03.412Z' environment: type: string enum: - sandbox - production example: production description: >- Ambiente en el que se timbró el CFDI. Los CFDI de sandbox no tienen validez fiscal ante el SAT. channel: type: string enum: - web - api - sdk - cli - mcp nullable: true example: mcp description: >- Canal de origen declarado por el cliente con el header X-Timbrix-Client (api si no se envió). null para CFDI anteriores a este campo. rfcReceptor: type: string example: GODE561231GR8 description: RFC del receptor del CFDI relatedCfdis: description: >- Relaciones de este CFDI (CfdisRelacionados). Con tipo 04 apunta al CFDI que sustituye. type: array items: $ref: '#/components/schemas/RelatedCfdiResponseDto' substitutedBy: description: >- CFDI cuya relación 04 apunta a este comprobante (sustitutos emitidos). type: array items: $ref: '#/components/schemas/SubstituteSummaryResponseDto' paymentMethod: type: string enum: - PUE - PPD nullable: true example: PPD description: >- Método de pago; null en Traslado, Pago y facturas anteriores a este campo. balance: type: object nullable: true example: 160 description: >- Saldo pendiente de una factura PPD (total menos complementos de pago vigentes o en timbrado); null en las demás. payment: description: >- Solo en complementos de pago (type P): el pago y las facturas que liquida. allOf: - $ref: '#/components/schemas/InvoicePaymentDto' required: - id - uuid - status - cancellationStatus - cancellationDesynced - type - series - folioNumber - total - date - xml - createdAt - environment - channel - rfcReceptor - relatedCfdis - substitutedBy - paymentMethod - balance PaymentDocumentDto: type: object properties: invoiceUuid: type: string example: d3bfbc57-44af-4390-a064-f0afab85e5df description: Folio fiscal (UUID) de la factura PPD que se paga amount: type: number example: 500 description: Monto que se paga de esta factura, en su moneda required: - invoiceUuid - amount RelatedCfdiResponseDto: type: object properties: type: type: string enum: - '01' - '02' - '03' - '04' - '05' - '06' - '07' example: '04' description: Clave de c_TipoRelacion (04 = sustitución) uuids: example: - D3BFBC57-44AF-4390-A064-F0AFAB85E5DF description: UUID de los CFDI relacionados type: array items: type: string required: - type - uuids SubstituteSummaryResponseDto: type: object properties: uuid: type: string example: 6F2B1C9A-3D4E-4F5A-8B7C-9D0E1F2A3B4C serie: type: string example: A folio: type: string example: '124' status: type: string enum: - vigente - cancelado example: vigente required: - uuid - serie - folio - status InvoicePaymentDto: type: object properties: date: type: string example: '2026-10-15T12:00:00' paymentForm: type: string example: '03' currency: type: string example: MXN exchange: type: number example: 1 amount: type: number example: 1660 operationNumber: type: object nullable: true example: SPEI-123 documents: type: array items: $ref: '#/components/schemas/InvoicePaymentDocumentDto' required: - date - paymentForm - currency - exchange - amount - operationNumber - documents InvoicePaymentDocumentDto: type: object properties: invoiceUuid: type: string example: d3bfbc57-44af-4390-a064-f0afab85e5df installment: type: number example: 2 previousBalance: type: number example: 660 amountPaid: type: number example: 500 remainingBalance: type: number example: 160 required: - invoiceUuid - installment - previousBalance - amountPaid - remainingBalance securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: 'API Key for authentication (format: sk_...)' bearer: scheme: bearer bearerFormat: JWT type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.