Skip to main content

Documentation Index

Fetch the complete documentation index at: https://piriod-d406ac55.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Emitir complemento de pago (SAT México) con Piriod requiere 4 llamadas a la API en la siguiente secuencia:
  1. Crear Source
  2. Autorizar Payment usando el Source previamente creado
  3. Crear Payment Receipt (SAT)
  4. Finalizar Payment Receipt (SAT)
1

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;
};
2

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;
};
3

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;
4

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;
};