Crear complemento de pago

Emitir complemento de pago (SAT México) con Piriod requiere 4 llamadas a la API en la siguiente secuencia:

Crear Source
Autorizar Payment usando el Source previamente creado
Crear Payment Receipt (SAT)
Finalizar Payment Receipt (SAT)

Crear un Source

En este paso se registra el origen del pago en Piriod.El Source representa la fuente de pago y contiene la información clave del monto, cliente, método y contexto (en este caso, un offline_payment vía transferencia bancaria en MXN).Aquí todavía no se está autorizando ni asociando el pago a un pago existente. Solo se está declarando formalmente el instrumento/origen que luego será utilizado para autorizar el pago.Este paso es obligatorio porque el comprobante SAT se genera a partir de un pago autorizado, y ese pago debe tener un source válido asociado.Output clave que debes guardar:

source.id → se utilizará en el Paso 2

const createSource = async function () {
  const payload = {
    amount: "116000",
    description: "Prueba",
    gateway: "offline_payment",
    offline_payment: {
      currency: "MXN",
      date: "2026-02-24",
      method: "bank_transfer",
    },
    usage: "single",
    customer: "cus_xxxxxxxxx",
  };

  const source = await piriod.resource.create("sources", payload);

  // Guarda el ID para el Paso 2
  console.log("source.id:", source?.id);

  return source;
};

import requests

def create_source():
    url = f"{BASE_URL}/sources/"
    payload = {
        "amount": "116000",
        "description": "Prueba",
        "gateway": "offline_payment",
        "offline_payment": {
            "currency": "MXN",
            "date": "2026-02-24",
            "method": "bank_transfer",
        },
        "usage": "single",
        "customer": "cus_xxxxxxxxx",
    }

    resp = requests.post(url, json=payload, headers=headers, timeout=30)
    resp.raise_for_status()

    source = resp.json()
    print("source.id:", source.get("id"))
    return source

# source = create_source()

curl https://api.piriod.com/sources/ \
  -X POST \
  -H "Authorization: your-user-api-key" \
  -H "X-Simple-Workspace: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "116000",
    "description": "Prueba",
    "gateway": "offline_payment",
    "offline_payment": {
      "currency": "MXN",
      "date": "2026-02-24",
      "method": "bank_transfer"
    },
    "usage": "single",
    "customer": "cus_xxxxxxxxx"
  }'

Autorizar el pago

En este paso se autoriza el pago existente, asociándolo al Source creado previamente.La autorización indica que el pago fue validado y aceptado dentro del sistema, cambiando su estado (por ejemplo, a authorized o equivalente).Sin este paso, el comprobante SAT no puede generarse, ya que únicamente se permite emitirlo sobre pagos autorizados.Este es el momento en que:

El pago queda formalmente respaldado por un origen de fondos.
El sistema valida que el monto y el método sean consistentes.

Inputs necesarios:

paymentId
sourceId

Output clave a validar:

payment.status debe reflejar un estado autorizable (ej: authorized).

const authorizePayment = async function ({ paymentId, sourceId }) {
  const payload = {
    source: sourceId,
  };

  const payment = await piriod.resource.create(
    `payments/${paymentId}`,
    payload,
    "authorize"
  );

  console.log("payment.id:", payment?.id);
  console.log("payment.status:", payment?.status);

  return payment;
};

import requests

def authorize_payment(payment_id: str, source_id: str):
    url = f"{BASE_URL}/payments/{payment_id}/authorize/"
    payload = {"source": source_id}

    resp = requests.post(url, json=payload, headers=headers, timeout=30)
    resp.raise_for_status()

    payment = resp.json()
    print("payment.id:", payment.get("id"))
    print("payment.status:", payment.get("status"))
    return payment

# payment = authorize_payment(payment_id="pay_lM2nB28b3Nu2yc70LL", source_id="src_xxxxx")

curl https://api.piriod.com/payments/:payment_id/authorize/ \
  -X POST \
  -H "Authorization: your-user-api-key" \
  -H "X-Simple-Workspace: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "src_xxxxxxxxx"
  }'

Crear el complemento de pago

En este paso se crea el recurso payment-receipt, que representa el comprobante de pago conforme a SAT México (CFDI de complemento de pago).Aquí todavía no se timbra ni se finaliza el comprobante; simplemente se genera el registro inicial que vincula el pago autorizado con el documento fiscal correspondiente.Este paso:

Valida que el pago esté autorizado.
Prepara la estructura fiscal necesaria para el timbrado.
Genera un receipt.id que será utilizado en el paso siguiente.

Output clave a guardar:

receipt.id
receipt.status (usualmente en estado preliminar o pendiente)

const createPaymentReceipt = async function ({ sourceId }) {
  const payload = {
    sources: [sourceId],
	tax_settings: {
        mx_payment_form: "03",
        mx_payment_method: "PUE",
        mx_relation: "partial_payment_invoice"
    }
  };

  const receipt = await piriod.resource.create("payment-receipts", payload);

  // Guarda el ID para el Paso 4
  console.log("receipt.id:", receipt?.id);
  console.log("receipt.status:", receipt?.status);

  return receipt;

import requests

def create_payment_receipt(source_id: str):
    url = f"{BASE_URL}/payment-receipts/"
    payload = {
		"sources": [source_id],
		"tax_settings": {
	        "mx_payment_form": "03",
	        "mx_payment_method": "PUE",
	        "mx_relation": "partial_payment_invoice"
	    }
	}

    resp = requests.post(url, json=payload, headers=headers, timeout=30)
    resp.raise_for_status()

    receipt = resp.json()
    print("receipt.id:", receipt.get("id"))
    print("receipt.status:", receipt.get("status"))
    return receipt

# receipt = create_payment_receipt(payment_id="pay_lM2nB28b3Nu2yc70LL")

curl https://api.piriod.com/payment-receipts/ \
  -X POST \
  -H "Authorization: your-user-api-key" \
  -H "X-Simple-Workspace: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [sou_xxxxxxxxxxxxxx],
	"tax_settings": {
        "mx_payment_form": "03",
        "mx_payment_method": "PUE",
        "mx_relation": "partial_payment_invoice"
    }
  }'

Finalizar el complemento de pago

Este paso ejecuta el proceso de finalización y timbrado fiscal del comprobante ante el SAT.Al finalizar:

El comprobante se valida fiscalmente.
Se genera el XML timbrado.
Se habilita el PDF (si aplica).
El estado cambia a finalizado (finalized, issued o similar).

Este paso es el que convierte el registro preliminar en un documento fiscal válido ante el SAT.Después de esta operación, el comprobante:

No debería modificarse.
Puede ser descargado o enviado al cliente.
Queda registrado oficialmente como CFDI de complemento de pago.

Output esperado:

receipt.status final.
xml_url y/o pdf_url (si el API los expone).

const finalizePaymentReceipt = async function ({ receiptId }) {
  const finalized = await piriod.resource.get(
    "payment-receipts",
    receiptId,
    "finalize"
  );

  console.log("finalized.id:", finalized?.id);
  console.log("finalized.status:", finalized?.status);

  return finalized;
};

import requests

def finalize_payment_receipt(receipt_id: str):
    url = f"{BASE_URL}/payment-receipts/{receipt_id}/finalize/"

    resp = requests.get(url, headers=headers, timeout=30)
    resp.raise_for_status()

    finalized = resp.json()
    print("finalized.id:", finalized.get("id"))
    print("finalized.status:", finalized.get("status"))

    return finalized

# finalized = finalize_payment_receipt(receipt_id="prc_xxxxx")

curl https://api.piriod.com/payment-receipts/:payment_receipt_id/finalize/ \
  -X GET \
  -H "Authorization: your-user-api-key" \
  -H "X-Simple-Workspace: your-organization-id" \

Webhooks

API Templates

Crear complemento de pago