Aceptar un pago

Esta es la guía de integración completa para negocios. Al terminar tendrás: cargos saliendo de tu backend, agentes pagándolos, webhooks confirmándolo todo y tu dinero en un saldo de comercio.

Requisitos previos

Una cuenta de consola en un despliegue de Payzor.
Tu API key de comercio (sk_mch_...). Si no la tienes, mira el paso 1 de la guía rápida.

Arquitectura

Tu servidor nunca toca directamente las billeteras de los agentes. Tú creas cargos; Payzor mueve el dinero y te cuenta qué pasó vía webhooks.

Tu backend                  Payzor                      Agente del cliente
──────────                  ──────                      ──────────────────
POST /merchant/charges ───▶ cargo (pending)
                            ◀────────────────────────── POST /charges/:id/pay
                            política → debita billetera
◀── webhook: payment.succeeded / charge.succeeded
GET /merchant/me ─────────▶ saldo actualizado

Paso a paso

1. Crea el cargo cuando toque facturar

Justo donde normalmente pedirías una tarjeta:

curl -X POST https://tu-host-payzor/merchant/charges \
  -H "Authorization: Bearer sk_mch_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsdCents": 499,
    "description": "Plan Pro - agosto",
    "externalId": "sub_42_invoice_8"
  }'

Guarda en tu base de datos el chargeId que te devuelve, asociado a tu externalId.

2. Dale al agente algo con qué pagar

El agente del cliente necesita saber qué pagar. Patrones habituales:

Tu API devuelve la URL de pago. Incluye "/charges/<id>/pay" en la respuesta de tu API, allí donde un agente iría a mirar.
Tu documentación le dice a los desarrolladores de agentes que conecten POST /charges/:id/pay en su bucle de herramientas.

El agente lo llama con su propia key; Payzor hace cumplir su política. Tú no haces nada más.

3. Maneja los resultados

El agente recibe	Significado	Qué deberías hacer
`{ paid: true, ... }`	Liquidado	Nada, el webhook lo confirmará.
`{ pendingApproval: true, approvalId }`	Esperando al humano	Espera; si se aprueba recibirás `payment.succeeded`.
`{ error: "..." }`	Bloqueado por política o saldo	Deja que decida el agente (reintentar más tarde, bajar de plan…).

4. Verifica que llegó

En desarrollo, consulta GET /merchant/me. En producción, apóyate en los webhooks (guía).

Conciliación

Cada cargo liquidado lleva:

chargeId: tuyo para guardarlo,
reference: coincide con la entrada en el rastro de auditoría del agente,
agentId: quién pagó.

Para exportaciones contables, el usuario de consola puede descargar GET /export/transactions.csv; cada hecho con su número de secuencia y su hash de cadena.

Primeros pasos

Conceptos clave

Guías

Aceptar un pago

Aceptar un pago

Requisitos previos

Arquitectura

Paso a paso

1. Crea el cargo cuando toque facturar

2. Dale al agente algo con qué pagar

3. Maneja los resultados

4. Verifica que llegó

Conciliación

Checklist antes de salir a producción

​Aceptar un pago

​Requisitos previos

​Arquitectura

​Paso a paso

​1. Crea el cargo cuando toque facturar

​2. Dale al agente algo con qué pagar

​3. Maneja los resultados

​4. Verifica que llegó

​Conciliación

​Checklist antes de salir a producción

Aceptar un pago

Requisitos previos

Arquitectura

Paso a paso

1. Crea el cargo cuando toque facturar

2. Dale al agente algo con qué pagar

3. Maneja los resultados

4. Verifica que llegó

Conciliación

Checklist antes de salir a producción