Intenciones de pago

Una Intención de pago es un objeto central en el ciclo de pago de Sangho. Representa su intención de cobrar dinero a un cliente y orquesta todas las etapas del proceso, desde la asociación de un método de pago hasta la confirmación final y la creación de una Transacción.

A cada pago le corresponde exactamente una Intención. Su ciclo de vida lo gestiona automáticamente la API de Sangho en función de las acciones de su cliente y de las respuestas de los operadores.

¿Por qué una Intención y no un pago directo?

Las Intenciones de pago permiten gestionar los escenarios complejos: autenticación 3D Secure, redirección al operador móvil, captura diferida y reintento tras un fallo sin perder nunca el estado del pago en curso. Es el enfoque recomendado para cualquier integración de pago robusta.

Ciclo de vida

requires_payment_method→requires_confirmation→requires_action→pending→processing→succeeded / canceled

Estado	Significado	Acción requerida
`requires_payment_method`	Todavía no hay ningún método de pago asociado.	Mostrar el formulario de pago al cliente.
`requires_confirmation`	Hay un método asociado, a la espera de confirmación.	Llamar a `/confirm/` o pasar `confirm: true` en la creación.
`requires_action`	El operador solicita una acción adicional (3DS, redirect).	Redirigir al cliente a `next_action.redirect_url`.
`pending`	A la espera de la respuesta del operador (mobile money).	Esperar el webhook `payment_intent.succeeded`.
`processing`	El pago está siendo procesado por el operador.	No hacer nada: esperar el webhook.
`requires_capture`	Autorizado: se requiere captura manual (captura diferida).	Llamar a `/capture/` antes de que caduque.
`succeeded`	Pago correcto. Se ha creado una Transaction.	Entregar el servicio/producto.
`canceled`	Cancelado definitivamente. No recuperable.	Crear una nueva Intención de Pago si es necesario.

Endpoints

Méthode	Endpoint	Description
POST	`/payment-intents/`	Crear una Intención de Pago
GET	`/payment-intents/`	Listar las Intenciones de Pago (paginado, filtrable)
GET	`/payment-intents/{id}/`	Recuperar una Intención de Pago por su ID
PATCH	`/payment-intents/{id}/`	Actualizar una Intención de Pago (antes de la confirmación)
POST	`/payment-intents/{id}/confirm/`	Confirmar el pago y activar el procesamiento
POST	`/payment-intents/{id}/capture/`	Capturar un pago autorizado (captura diferida)
POST	`/payment-intents/{id}/cancel/`	Cancelar definitivamente

¿Le ha resultado útil esta introducción?

Esquema del objeto

ResponseObjeto PaymentIntent

Estructura completa devuelta por todos los endpoints GET y POST de este recurso.

json

{
  "id": "pi_3Nx8mLKZ2eZvKYlo28m",
  "object": "payment_intent",
  "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": 15000,
  "amount_capturable": 0,
  "amount_received": 0,
  "currency": "XAF",
  "status": "requires_payment_method",
  "payment_method": null,
  "payment_method_types": ["mobile_money", "bank_card"],
  "customer": "cust_xxxxxxxx",
  "description": "Commande #CMD-2026-042",
  "receipt_email": "[email protected]",
  "category": "product",
  "confirm": false,
  "capture_method": "automatic",
  "next_action": null,
  "url": "https://checkout.sangho.ga/pay/pi_xxx",
  "livemode": true,
  "metadata": {
    "order_id": "CMD-2026-042"
  },
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Crear una Intención de pago

Instancia una nueva Intención de pago en el estado requires_payment_method. Es la primera etapa de todo flujo de pago con Sangho.

POSTCuerpo de la solicitud

amountRequis

integercentimesex :15000

Importe que se va a cobrar, expresado en céntimos de la moneda. Para las monedas sin decimales como XAF/XOF, 1 FCFA = 1 céntimo (sin decimales). Para USD/EUR, 1 unidad = 100 céntimos.

El importe mínimo aceptado es de 100 céntimos (1 XAF). El importe máximo depende del límite de transacción configurado en su App. Utilice siempre enteros: los valores decimales (float) se rechazan con un error 400.

currencyRequis

stringISO 4217ex :XAF

Código ISO 4217 de la moneda del pago. Sangho reconoce 132 monedas ISO 4217, pero la moneda utilizada debe, además, estar activada en Sangho e incluida en su plan: XAF y XOF están disponibles en todos los planes.

Una moneda desconocida o desactivada devuelve 422 INVALID_CURRENCY. Una moneda válida pero que no figura en su plan devuelve 403 CURRENCY_NOT_IN_PLAN: pase a un plan superior para activarla. Una vez creado, el campo currency de una Intención de Pago ya no se puede modificar.

payment_method_typesOptionnel

array[string]ex :[“mobile_money”, “bank_card”]

Lista de los métodos de pago autorizados para esta Intención. Si se omite, están disponibles todos los métodos activos de su App.

Valores posibles: mobile_money, bank_card, paypal. Restringir los tipos mejora la experiencia de usuario en la página de pago y reduce los errores debidos a métodos no disponibles en una región determinada.

customerOptionnel

stringID Customerex :cust_xxxxxxxx

Identificador o correo electrónico de un objeto Customer existente que se asociará a este pago. Permite recuperar el historial de pagos de un cliente.

Si pasa un correo electrónico aún no registrado, Sangho crea automáticamente un Customer. Si pasa un ID y el Customer no existe, la API devuelve un error 404. Asociar un Customer también le permite enviar automáticamente un recibo si no se indica receipt_email.

descriptionOptionnel

string

Descripción interna del pago no visible para el comprador en la página de pago. Útil para encontrar un pago en su panel o mediante la API.

Máx. 500 caracteres. Esta descripción aparece en los registros y en las exportaciones CSV del panel, pero no en los recibos ni en la página de checkout.

receipt_emailOptionnel

stringemailex :[email protected]

Dirección de correo electrónico a la que Sangho enviará automáticamente el recibo de pago tras un pago correcto.

Si no se indica y hay un Customer asociado, se utiliza por defecto el correo del Customer. Para desactivar el envío del recibo, pase explícitamente null.

confirmOptionnel

booleandéfaut :false

Si es true, intenta confirmar el pago inmediatamente después de la creación. Requiere que payment_method se facilite en la misma solicitud.

Útil para los pagos de servidor a servidor en los que ya dispone del método de pago. Si la confirmación falla, el PaymentIntent pasa a requires_payment_method: no se cancela.

payment_methodOptionnel

stringID PaymentMethodex :meth_xxxxxxxx

ID de un método de pago existente que se asociará de inmediato al PaymentIntent.

Necesario si confirm: true. El método debe pertenecer a la App o al Customer asociado.

categoryOptionnel

stringdéfaut :product

Categoría de negocio del pago, utilizada para las estadísticas y el cumplimiento normativo OHADA. Valores: product, service, donation, invoice.

capture_methodOptionnel

stringdéfaut :automatic

Determina si el importe se captura automáticamente tras la autorización o si desea capturarlo manualmente más adelante.

automatic: captura inmediatamente tras la confirmación (flujo estándar). manual: solo autoriza; debe llamar a /capture/ en un plazo de 7 días; si no, la autorización se cancela automáticamente. La captura manual es útil para las reservas, los pedidos anticipados o las validaciones de negocio.

metadataOptionnel

object

Diccionario clave/valor para almacenar sus propios datos asociados al PaymentIntent: referencia del pedido, ID de usuario interno, etc.

Máximo 50 claves; cada clave y cada valor son strings de 500 caracteres como máximo. Los metadatos se devuelven en todos los webhooks vinculados a este PaymentIntent. No son visibles para el cliente final.

¿Están claros los parámetros de creación?

Crear una Intención de Pago

bash

curl -X POST https://api.sangho.ga/v1/payment-intents/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: uuid-unique" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "payment_method_types": ["mobile_money", "bank_card"],
    "customer": "cust_xxxxxxxx",
    "description": "Commande #CMD-2026-042",
    "metadata": { "order_id": "CMD-2026-042" }
  }'

Response201 Created

Estado requires_payment_method. El campo url contiene la URL de checkout a la que redirigir a su cliente.

json

{
  "id": "pi_3Nx8mLKZ2eZvKYlo28m",
  "object": "payment_intent",
  "amount": 15000,
  "currency": "XAF",
  "status": "requires_payment_method",
  "payment_method_types": ["mobile_money", "bank_card"],
  "customer": "cust_xxxxxxxx",
  "description": "Commande #CMD-2026-042",
  "url": "https://checkout.sangho.ga/pay/pi_3Nx8mLKZ",
  "livemode": true,
  "metadata": { "order_id": "CMD-2026-042" },
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Response400 Bad Request

El cuerpo contiene datos no válidos. El campo errors detalla cada campo con error.

Causas frecuentes: importe ≤ 0, moneda no admitida o fuera del plan, importe por debajo del límite mínimo de la App.

json

{
  "status": 422,
  "type": "VALIDATION_ERROR",
  "code": "AMOUNT_TOO_SMALL",
  "message": "Le montant est trop faible. Le minimum est de 100 XAF.",
  "param": "amount",
  "doc_url": "https://docs.sangho.ga/errors#AMOUNT_TOO_SMALL"
}

Response401 Unauthorized

La clave API está ausente, caducada o no es válida.

No exponga nunca su clave secreta en el frontend ni en un repositorio Git público.

json

{
  "status": 401,
  "type": "AUTHENTICATION_ERROR",
  "code": "INVALID_API_KEY",
  "message": "Clé API invalide ou expirée.",
  "doc_url": "https://docs.sangho.ga/errors#INVALID_API_KEY"
}

↗Guía de autenticación →

Listar las Intenciones de pago

Devuelve una lista paginada de todas las Intenciones de pago de su App, ordenadas por fecha de creación descendente por defecto. Admite filtrado, búsqueda y ordenación.

GETParámetros de consulta (query)

statusOptionnel

stringquery

Filtrar las Intenciones por estado. Acepta los valores del ciclo de vida.

Puede pasar varios valores separados por coma: status=succeeded,canceled.

currencyOptionnel

stringISO 4217queryex :XAF

Filtrar por código de moneda ISO 4217.

customerOptionnel

stringquery

Filtrar por ID o correo electrónico de un Customer. Devuelve todos los pagos asociados a ese cliente.

Puede pasar el ID (cust_xxx) o la dirección de correo exacta. La búsqueda por correo distingue entre mayúsculas y minúsculas.

created_afterOptionnel

stringISO 8601queryex :2026-01-01T00:00:00Z

Devuelve únicamente las Intenciones de pago creadas después de esta fecha/hora (inclusive).

created_beforeOptionnel

stringISO 8601queryex :2026-12-31T23:59:59Z

Devuelve únicamente las Intenciones de pago creadas antes de esta fecha/hora (inclusive).

orderingOptionnel

stringquerydéfaut :-created_at

Campo de ordenación. Añada el prefijo - para un orden descendente.

Campos ordenables: created_at, amount, status. Ejemplos: ordering=amount (ascendente), ordering=-amount (descendente).

pageOptionnel

integerquerydéfaut :1

Número de la página que se va a devolver. La paginación empieza en 1.

Si la página solicitada supera el número total de páginas, se devuelve una lista vacía (sin error 404).

page_sizeOptionnel

integerquerydéfaut :20

Número de resultados por página. Mínimo: 1. Máximo: 100.

Para recuperar todas las Intenciones de pago de un período, utilice page_size=100 e itere mientras pagination.next no sea nulo en la respuesta.

Paginación

Todos los endpoints de listado de Sangho utilizan una paginación por página (page / page_size). La respuesta es un envoltorio plano: count, next, previous y data están al mismo nivel y no hay ningún objeto pagination anidado.

Iterar sobre todas las páginas

Siga incrementando page mientras next no sea nulo. Esta propiedad contiene la URL completa de la página siguiente, lista para invocarse directamente.

¿Está suficientemente clara la sección de paginación?

Listar las Intenciones de pago

bash

# Paiements réussis en XAF, 50 par page
curl "https://api.sangho.ga/v1/payment-intents/?status=succeeded&currency=XAF&page_size=50" \
  -H "Authorization: Bearer sk_prod_xxxx"

Response200 OK — Lista paginada

Envoltorio plano: count, next, previous y data están al mismo nivel; no hay ningún objeto pagination anidado.

json

{
  "count": 142,
  "next": "https://api.sangho.ga/v1/payment-intents/?page=2&page_size=50&status=succeeded",
  "previous": null,
  "data": [
    {
      "id": "pi_3Nx8mLKZ2eZvKYlo28m",
      "object": "payment_intent",
      "amount": 15000,
      "currency": "XAF",
      "status": "succeeded",
      "customer": "cust_xxxxxxxx",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Confirmar una Intención de pago

Activa el procesamiento del pago. Pasa el PaymentIntent a processing (o a requires_action si se necesita una etapa adicional).

POSTCuerpo de la confirmación (POST)

payment_methodOptionnel

stringID PaymentMethod

ID de un método de pago que se asociará antes de la confirmación. Requerido si el PaymentIntent está en requires_payment_method.

Utilice siempre una Idempotency-Key

Llame a /confirm/ con una cabecera Idempotency-Key única para evitar las confirmaciones dobles en caso de timeout de red. La clave debe ser única por PaymentIntent.

Capturar (captura diferida)

Captura un importe autorizado. Solo está disponible si capture_method: “manual” y el estado es requires_capture. Puede capturar un importe inferior al importe autorizado.

POSTCuerpo de la captura (POST)

amount_to_captureOptionnel

integercentimes

Importe que se va a capturar. Debe ser ≤ amount_capturable. Si se omite, captura el importe total autorizado.

Capturar un importe parcial cancela automáticamente el resto. Ejemplo: autorización de 20 000 XAF, captura de 15 000 → 5 000 cancelados automáticamente.

Cancelar

Cancela definitivamente el PaymentIntent. Es irreversible. Si el PaymentIntent estaba en requires_capture, la autorización se libera en el operador.

Cancelación irreversible

Una Intención de Pago cancelada no se puede reactivar. Si desea reintentar el pago, debe crear una nueva Intención de pago.

¿Están bien explicadas las acciones confirm, capture y cancel?

Confirmar

bash

curl -X POST https://api.sangho.ga/v1/payment-intents/pi_xxx/confirm/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Idempotency-Key: confirm-pi_xxx-1234" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method": "meth_xxxxxxxx" }'

Response200 OK — Confirmado

El estado pasa a processing o a requires_action si se requiere una redirección al operador (next_action no nulo).

json

{
  "id": "pi_3Nx8mLKZ2eZvKYlo28m",
  "status": "processing",
  "next_action": null,
  "updated_at": "2026-03-01T10:01:00Z"
}

Response422 — Estado no válido

El PaymentIntent no está en un estado confirmable (ya está succeeded, canceled o en processing).

Compruebe el estado actual antes de llamar a /confirm/. Se recomienda un GET previo.

json

{
  "status": 422,
  "type": "VALIDATION_ERROR",
  "code": "PAYMENT_INTENT_NOT_CONFIRMABLE",
  "message": "Impossible de confirmer un PaymentIntent au statut 'succeeded'.",
  "param": "status",
  "doc_url": "https://docs.sangho.ga/errors#PAYMENT_INTENT_NOT_CONFIRMABLE"
}

Captura parcial

bash

curl -X POST https://api.sangho.ga/v1/payment-intents/pi_xxx/capture/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount_to_capture": 12000 }'

Response200 OK — Capturado

El pago queda capturado. amount_received refleja el importe efectivamente cobrado. El resto, si lo hay, se cancela.

json

{
  "id": "pi_3Nx8mLKZ2eZvKYlo28m",
  "status": "succeeded",
  "amount": 20000,
  "amount_received": 12000,
  "amount_capturable": 0,
  "updated_at": "2026-03-01T10:05:00Z"
}