Register a payment of PPD invoices and stamp its Complemento de Pago (CFDI tipo P)
curl --request POST \
--url https://api.example.com/invoices/payments \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--header 'x-timbrix-client: <x-timbrix-client>' \
--data '
{
"date": "2026-10-15T12:00:00",
"paymentForm": "03",
"documents": [
{
"invoiceUuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"amount": 500
}
],
"customerId": "<string>",
"currency": "MXN",
"exchange": 18.5,
"operationNumber": "SPEI-123",
"payerBankRfc": "<string>",
"payerAccount": "<string>",
"payeeBankRfc": "<string>",
"payeeAccount": "<string>",
"series": "P",
"folioNumber": "12",
"substitutes": "5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a",
"idempotencyKey": "pago-8421"
}
'import requests
url = "https://api.example.com/invoices/payments"
payload = {
"date": "2026-10-15T12:00:00",
"paymentForm": "03",
"documents": [
{
"invoiceUuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"amount": 500
}
],
"customerId": "<string>",
"currency": "MXN",
"exchange": 18.5,
"operationNumber": "SPEI-123",
"payerBankRfc": "<string>",
"payerAccount": "<string>",
"payeeBankRfc": "<string>",
"payeeAccount": "<string>",
"series": "P",
"folioNumber": "12",
"substitutes": "5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a",
"idempotencyKey": "pago-8421"
}
headers = {
"x-timbrix-client": "<x-timbrix-client>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-timbrix-client': '<x-timbrix-client>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
date: '2026-10-15T12:00:00',
paymentForm: '03',
documents: [{invoiceUuid: 'd3bfbc57-44af-4390-a064-f0afab85e5df', amount: 500}],
customerId: '<string>',
currency: 'MXN',
exchange: 18.5,
operationNumber: 'SPEI-123',
payerBankRfc: '<string>',
payerAccount: '<string>',
payeeBankRfc: '<string>',
payeeAccount: '<string>',
series: 'P',
folioNumber: '12',
substitutes: '5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a',
idempotencyKey: 'pago-8421'
})
};
fetch('https://api.example.com/invoices/payments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/invoices/payments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'date' => '2026-10-15T12:00:00',
'paymentForm' => '03',
'documents' => [
[
'invoiceUuid' => 'd3bfbc57-44af-4390-a064-f0afab85e5df',
'amount' => 500
]
],
'customerId' => '<string>',
'currency' => 'MXN',
'exchange' => 18.5,
'operationNumber' => 'SPEI-123',
'payerBankRfc' => '<string>',
'payerAccount' => '<string>',
'payeeBankRfc' => '<string>',
'payeeAccount' => '<string>',
'series' => 'P',
'folioNumber' => '12',
'substitutes' => '5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a',
'idempotencyKey' => 'pago-8421'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>",
"x-timbrix-client: <x-timbrix-client>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/invoices/payments"
payload := strings.NewReader("{\n \"date\": \"2026-10-15T12:00:00\",\n \"paymentForm\": \"03\",\n \"documents\": [\n {\n \"invoiceUuid\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\",\n \"amount\": 500\n }\n ],\n \"customerId\": \"<string>\",\n \"currency\": \"MXN\",\n \"exchange\": 18.5,\n \"operationNumber\": \"SPEI-123\",\n \"payerBankRfc\": \"<string>\",\n \"payerAccount\": \"<string>\",\n \"payeeBankRfc\": \"<string>\",\n \"payeeAccount\": \"<string>\",\n \"series\": \"P\",\n \"folioNumber\": \"12\",\n \"substitutes\": \"5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a\",\n \"idempotencyKey\": \"pago-8421\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-timbrix-client", "<x-timbrix-client>")
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/invoices/payments")
.header("x-timbrix-client", "<x-timbrix-client>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"date\": \"2026-10-15T12:00:00\",\n \"paymentForm\": \"03\",\n \"documents\": [\n {\n \"invoiceUuid\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\",\n \"amount\": 500\n }\n ],\n \"customerId\": \"<string>\",\n \"currency\": \"MXN\",\n \"exchange\": 18.5,\n \"operationNumber\": \"SPEI-123\",\n \"payerBankRfc\": \"<string>\",\n \"payerAccount\": \"<string>\",\n \"payeeBankRfc\": \"<string>\",\n \"payeeAccount\": \"<string>\",\n \"series\": \"P\",\n \"folioNumber\": \"12\",\n \"substitutes\": \"5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a\",\n \"idempotencyKey\": \"pago-8421\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/invoices/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-timbrix-client"] = '<x-timbrix-client>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"date\": \"2026-10-15T12:00:00\",\n \"paymentForm\": \"03\",\n \"documents\": [\n {\n \"invoiceUuid\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\",\n \"amount\": 500\n }\n ],\n \"customerId\": \"<string>\",\n \"currency\": \"MXN\",\n \"exchange\": 18.5,\n \"operationNumber\": \"SPEI-123\",\n \"payerBankRfc\": \"<string>\",\n \"payerAccount\": \"<string>\",\n \"payeeBankRfc\": \"<string>\",\n \"payeeAccount\": \"<string>\",\n \"series\": \"P\",\n \"folioNumber\": \"12\",\n \"substitutes\": \"5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a\",\n \"idempotencyKey\": \"pago-8421\"\n}"
response = http.request(request)
puts response.read_body{
"id": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
"uuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"status": "vigente",
"cancellationStatus": "pendiente",
"cancellationDesynced": false,
"type": "I",
"series": "A",
"folioNumber": "1",
"total": 116,
"date": "2026-07-30T22:50:00",
"xml": "<string>",
"createdAt": "2026-07-30T22:50:03.412Z",
"environment": "production",
"channel": "mcp",
"rfcReceptor": "GODE561231GR8",
"relatedCfdis": [
{
"type": "04",
"uuids": [
"D3BFBC57-44AF-4390-A064-F0AFAB85E5DF"
]
}
],
"substitutedBy": [
{
"uuid": "6F2B1C9A-3D4E-4F5A-8B7C-9D0E1F2A3B4C",
"serie": "A",
"folio": "124",
"status": "vigente"
}
],
"paymentMethod": "PPD",
"balance": 160,
"payment": {
"date": "2026-10-15T12:00:00",
"paymentForm": "03",
"currency": "MXN",
"exchange": 1,
"amount": 1660,
"operationNumber": "SPEI-123",
"documents": [
{
"invoiceUuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"installment": 2,
"previousBalance": 660,
"amountPaid": 500,
"remainingBalance": 160
}
]
}
}invoices
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.
POST
/
invoices
/
payments
Register a payment of PPD invoices and stamp its Complemento de Pago (CFDI tipo P)
curl --request POST \
--url https://api.example.com/invoices/payments \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--header 'x-timbrix-client: <x-timbrix-client>' \
--data '
{
"date": "2026-10-15T12:00:00",
"paymentForm": "03",
"documents": [
{
"invoiceUuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"amount": 500
}
],
"customerId": "<string>",
"currency": "MXN",
"exchange": 18.5,
"operationNumber": "SPEI-123",
"payerBankRfc": "<string>",
"payerAccount": "<string>",
"payeeBankRfc": "<string>",
"payeeAccount": "<string>",
"series": "P",
"folioNumber": "12",
"substitutes": "5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a",
"idempotencyKey": "pago-8421"
}
'import requests
url = "https://api.example.com/invoices/payments"
payload = {
"date": "2026-10-15T12:00:00",
"paymentForm": "03",
"documents": [
{
"invoiceUuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"amount": 500
}
],
"customerId": "<string>",
"currency": "MXN",
"exchange": 18.5,
"operationNumber": "SPEI-123",
"payerBankRfc": "<string>",
"payerAccount": "<string>",
"payeeBankRfc": "<string>",
"payeeAccount": "<string>",
"series": "P",
"folioNumber": "12",
"substitutes": "5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a",
"idempotencyKey": "pago-8421"
}
headers = {
"x-timbrix-client": "<x-timbrix-client>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-timbrix-client': '<x-timbrix-client>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
date: '2026-10-15T12:00:00',
paymentForm: '03',
documents: [{invoiceUuid: 'd3bfbc57-44af-4390-a064-f0afab85e5df', amount: 500}],
customerId: '<string>',
currency: 'MXN',
exchange: 18.5,
operationNumber: 'SPEI-123',
payerBankRfc: '<string>',
payerAccount: '<string>',
payeeBankRfc: '<string>',
payeeAccount: '<string>',
series: 'P',
folioNumber: '12',
substitutes: '5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a',
idempotencyKey: 'pago-8421'
})
};
fetch('https://api.example.com/invoices/payments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/invoices/payments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'date' => '2026-10-15T12:00:00',
'paymentForm' => '03',
'documents' => [
[
'invoiceUuid' => 'd3bfbc57-44af-4390-a064-f0afab85e5df',
'amount' => 500
]
],
'customerId' => '<string>',
'currency' => 'MXN',
'exchange' => 18.5,
'operationNumber' => 'SPEI-123',
'payerBankRfc' => '<string>',
'payerAccount' => '<string>',
'payeeBankRfc' => '<string>',
'payeeAccount' => '<string>',
'series' => 'P',
'folioNumber' => '12',
'substitutes' => '5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a',
'idempotencyKey' => 'pago-8421'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>",
"x-timbrix-client: <x-timbrix-client>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/invoices/payments"
payload := strings.NewReader("{\n \"date\": \"2026-10-15T12:00:00\",\n \"paymentForm\": \"03\",\n \"documents\": [\n {\n \"invoiceUuid\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\",\n \"amount\": 500\n }\n ],\n \"customerId\": \"<string>\",\n \"currency\": \"MXN\",\n \"exchange\": 18.5,\n \"operationNumber\": \"SPEI-123\",\n \"payerBankRfc\": \"<string>\",\n \"payerAccount\": \"<string>\",\n \"payeeBankRfc\": \"<string>\",\n \"payeeAccount\": \"<string>\",\n \"series\": \"P\",\n \"folioNumber\": \"12\",\n \"substitutes\": \"5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a\",\n \"idempotencyKey\": \"pago-8421\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-timbrix-client", "<x-timbrix-client>")
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/invoices/payments")
.header("x-timbrix-client", "<x-timbrix-client>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"date\": \"2026-10-15T12:00:00\",\n \"paymentForm\": \"03\",\n \"documents\": [\n {\n \"invoiceUuid\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\",\n \"amount\": 500\n }\n ],\n \"customerId\": \"<string>\",\n \"currency\": \"MXN\",\n \"exchange\": 18.5,\n \"operationNumber\": \"SPEI-123\",\n \"payerBankRfc\": \"<string>\",\n \"payerAccount\": \"<string>\",\n \"payeeBankRfc\": \"<string>\",\n \"payeeAccount\": \"<string>\",\n \"series\": \"P\",\n \"folioNumber\": \"12\",\n \"substitutes\": \"5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a\",\n \"idempotencyKey\": \"pago-8421\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/invoices/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-timbrix-client"] = '<x-timbrix-client>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"date\": \"2026-10-15T12:00:00\",\n \"paymentForm\": \"03\",\n \"documents\": [\n {\n \"invoiceUuid\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\",\n \"amount\": 500\n }\n ],\n \"customerId\": \"<string>\",\n \"currency\": \"MXN\",\n \"exchange\": 18.5,\n \"operationNumber\": \"SPEI-123\",\n \"payerBankRfc\": \"<string>\",\n \"payerAccount\": \"<string>\",\n \"payeeBankRfc\": \"<string>\",\n \"payeeAccount\": \"<string>\",\n \"series\": \"P\",\n \"folioNumber\": \"12\",\n \"substitutes\": \"5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a\",\n \"idempotencyKey\": \"pago-8421\"\n}"
response = http.request(request)
puts response.read_body{
"id": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
"uuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"status": "vigente",
"cancellationStatus": "pendiente",
"cancellationDesynced": false,
"type": "I",
"series": "A",
"folioNumber": "1",
"total": 116,
"date": "2026-07-30T22:50:00",
"xml": "<string>",
"createdAt": "2026-07-30T22:50:03.412Z",
"environment": "production",
"channel": "mcp",
"rfcReceptor": "GODE561231GR8",
"relatedCfdis": [
{
"type": "04",
"uuids": [
"D3BFBC57-44AF-4390-A064-F0AFAB85E5DF"
]
}
],
"substitutedBy": [
{
"uuid": "6F2B1C9A-3D4E-4F5A-8B7C-9D0E1F2A3B4C",
"serie": "A",
"folio": "124",
"status": "vigente"
}
],
"paymentMethod": "PPD",
"balance": 160,
"payment": {
"date": "2026-10-15T12:00:00",
"paymentForm": "03",
"currency": "MXN",
"exchange": 1,
"amount": 1660,
"operationNumber": "SPEI-123",
"documents": [
{
"invoiceUuid": "d3bfbc57-44af-4390-a064-f0afab85e5df",
"installment": 2,
"previousBalance": 660,
"amountPaid": 500,
"remainingBalance": 160
}
]
}
}Authorizations
apiKeybearer
API Key for authentication (format: sk_...)
Headers
Canal de origen del CFDI: web, api, sdk, cli o mcp.
Required for Supabase session auth. Ignored when authenticating with an API key (the organization resolves from the key).
Body
application/json
Fecha y hora del pago en la Ciudad de México (sin zona horaria)
Example:
"2026-10-15T12:00:00"
Forma de pago del catálogo c_FormaPago del SAT (sin 99)
Example:
"03"
Facturas PPD que liquida este pago (1 a 50)
Show child attributes
Show child attributes
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.
Default: MXN. Debe ser la moneda de las facturas.
Example:
"MXN"
Tipo de cambio a MXN. Obligatorio si currency no es MXN; se ignora con MXN.
Example:
18.5
Número o referencia de la operación
Example:
"SPEI-123"
RFC del banco del que paga
Cuenta del que paga
RFC del banco que recibe
Cuenta que recibe
Serie del complemento. Default: P
Example:
"P"
Folio del complemento. Si se omite, Timbrix usa el siguiente de la organización.
Example:
"12"
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.
Example:
"5f0e7c4b-2a8d-4c1e-9b3a-7d6f1e2c3b4a"
Llave para reintentar sin timbrar dos veces el mismo complemento
Example:
"pago-8421"
Response
Timbrix invoice record ID
Example:
"0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab"
Folio fiscal UUID asignado por el SAT vía PAC
Example:
"d3bfbc57-44af-4390-a064-f0afab85e5df"
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.
Available options:
vigente, cancelado Example:
"vigente"
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.
Available options:
pendiente, rechazada, en_proceso 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
I = Ingreso, E = Egreso, T = Traslado, P = Pago
Available options:
I, E, T, P Example:
"I"
Example:
"A"
Example:
"1"
Example:
116
Example:
"2026-07-30T22:50:00"
XML del CFDI timbrado (UTF-8)
Example:
"2026-07-30T22:50:03.412Z"
Ambiente en el que se timbró el CFDI. Los CFDI de sandbox no tienen validez fiscal ante el SAT.
Available options:
sandbox, production Example:
"production"
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.
Available options:
web, api, sdk, cli, mcp Example:
"mcp"
RFC del receptor del CFDI
Example:
"GODE561231GR8"
Relaciones de este CFDI (CfdisRelacionados). Con tipo 04 apunta al CFDI que sustituye.
Show child attributes
Show child attributes
CFDI cuya relación 04 apunta a este comprobante (sustitutos emitidos).
Show child attributes
Show child attributes
Método de pago; null en Traslado, Pago y facturas anteriores a este campo.
Available options:
PUE, PPD Example:
"PPD"
Saldo pendiente de una factura PPD (total menos complementos de pago vigentes o en timbrado); null en las demás.
Example:
160
Solo en complementos de pago (type P): el pago y las facturas que liquida.
Show child attributes
Show child attributes