Transactions

Una Transacción representa un pago efectivamente procesado por un operador. Sangho la crea automáticamente cuando se completa con éxito una Intención de pago: no se puede crear directamente mediante la API.

Las transacciones son el registro contable de referencia de su actividad. Contienen el importe neto cobrado, las tarifas de Sangho y las comisiones de socios, y son el origen de los Receipts enviados a los clientes.

Transacciones de solo lectura

Las transacciones no se pueden crear, modificar (salvo description y metadata) ni eliminar. Para anular los fondos de una transacción, cree un Refund. Para impugnar una transacción, contacte con el soporte de Sangho.

Estados posibles

Estado	Significado	Acción posible
`approved`	Aprobada por el operador, a la espera de liquidación.	Esperar: pasa automáticamente a `completed`.
`pending`	En cola de procesamiento del operador.	Esperar el webhook `transaction.succeeded`.
`completed`	Pago correcto: fondos capturados y disponibles.	Entregar el servicio/producto. Reembolso posible.
`failed`	Pago fallido en el operador.	Informar al cliente y proponer otro método.
`refunded`	Reembolso total realizado.	Ninguna: transacción cerrada.
`disputed`	Transacción impugnada por el cliente o el operador.	Contactar con el soporte con las pruebas.
`canceled`	Transacción cancelada antes de su procesamiento.	Crear una nueva Intención de pago si es necesario.

Endpoints

Méthode	Endpoint	Description
GET	`/transactions/`	Listar las transacciones (paginado, filtrable)
GET	`/transactions/{id}/`	Recuperar una transacción por su ID
PATCH	`/transactions/{id}/`	Modificar únicamente description y metadata
POST	`/transactions/{id}/cancel/`	Cancelar una transacción en estado pending

¿Está clara esta introducción?

Esquema del objeto

ResponseObjeto Transaction

Estructura completa. Los campos fee y commission los calcula automáticamente Sangho según su plan de precios.

json

{
  "id": "trans_3Nx8mLKZ2eZvKYlo28m",
  "object": "transaction",
  "app": "app_xxxxxxxx",
  "amount": 15000,
  "fee": 350,
  "fee_rate": 0.023,
  "commission": 150,
  "commission_rate": 0.01,
  "net_amount": 14500,
  "currency": "XAF",
  "status": "completed",
  "type": "deposit",
  "description": "Commande #CMD-2026-042",
  "payment_intent": "pi_xxxxxxxxxxxx",
  "customer": "cust_xxxxxxxx",
  "payment_method_type": "mobile_money",
  "operator": "airtel",
  "processed_at": "2026-03-01T10:05:00Z",
  "metadata": {
    "order_id": "CMD-2026-042"
  },
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:05:00Z"
}

Listar las transacciones

Devuelve una lista paginada de todas las transacciones de su App. Es el endpoint principal para los informes contables, las conciliaciones y las exportaciones.

GETParámetros de consulta (query)

statusOptionnel

stringquery

Filtrar por estado. Varios valores separados por coma: status=completed,refunded.

typeOptionnel

stringquery

Filtrar por tipo de transacción.

Valores posibles: deposit (pago entrante), refund (reembolso), payout (transferencia saliente), withdraw (retirada), transfer (transferencia interna).

payment_method_typeOptionnel

stringquery

Filtrar por método de pago utilizado: mobile_money, bank_card, paypal.

currencyOptionnel

stringISO 4217query

Filtrar por moneda.

customerOptionnel

stringquery

Filtrar por ID o correo electrónico del Customer. Devuelve todas las transacciones vinculadas a ese cliente.

min_amountOptionnel

integercentimesquery

Importe mínimo (inclusivo) en céntimos. Útil para filtrar las transacciones por encima de un umbral.

max_amountOptionnel

integercentimesquery

Importe máximo (inclusivo) en céntimos.

created_afterOptionnel

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

Fecha de inicio del intervalo de tiempo (inclusiva).

created_beforeOptionnel

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

Fecha de fin del intervalo de tiempo (inclusiva).

searchOptionnel

stringquery

Búsqueda de texto en la descripción de la transacción. Parcial e insensible a mayúsculas y minúsculas.

orderingOptionnel

stringquerydéfaut :-created_at

Ordenación. Campos disponibles: created_at, amount, net_amount, status.

pageOptionnel

integerquerydéfaut :1

Número de página.

page_sizeOptionnel

integerquerydéfaut :20

Resultados por página. Máximo: 100.

Para las exportaciones contables o las conciliaciones, combine page_size=100 con created_after y created_before para paginar sobre un período concreto.

Conciliación mensual

Para exportar todas las transacciones de un mes, combine created_after=2026-03-01T00:00:00Z, created_before=2026-03-31T23:59:59Z, status=completed, type=deposit y pagine con page_size=100 hasta agotar las páginas.

¿Están suficientemente documentados los filtros de listado?

Listar las transacciones

bash

# Transactions complétées du T1 2026
curl "https://api.sangho.ga/v1/transactions/?status=completed&type=deposit&created_after=2026-01-01T00:00:00Z&created_before=2026-03-31T23:59:59Z&page_size=100" \
  -H "Authorization: Bearer sk_prod_xxxx"

Response200 OK — Lista paginada

El campo pagination.count indica el número total de transacciones que coinciden con los filtros, todos ellos utilizables para los totales contables.

json

{
  "object": "list",
  "data": [
    {
      "id": "trans_3Nx8mLKZ2eZvKYlo28m",
      "object": "transaction",
      "amount": 15000,
      "fee": 350,
      "net_amount": 14500,
      "currency": "XAF",
      "status": "completed",
      "type": "deposit",
      "payment_method_type": "mobile_money",
      "customer": "cust_xxxxxxxx",
      "created_at": "2026-03-01T10:05:00Z"
    }
  ],
  "pagination": {
    "count": 347,
    "total_pages": 4,
    "page": 1,
    "page_size": 100,
    "previous": null,
    "next": "https://api.sangho.ga/v1/transactions/?page=2&page_size=100&status=completed"
  }
}

ResponseRecuperar una transacción

GET /transactions/{id}/ devuelve el objeto completo con todos los campos de tarifas y el operador.

json

{
  "id": "trans_3Nx8mLKZ2eZvKYlo28m",
  "amount": 15000,
  "fee": 350,
  "fee_rate": 0.023,
  "commission": 150,
  "net_amount": 14500,
  "currency": "XAF",
  "status": "completed",
  "type": "deposit",
  "payment_intent": "pi_xxxxxxxxxxxx",
  "customer": "cust_xxxxxxxx",
  "payment_method_type": "mobile_money",
  "operator": "airtel",
  "processed_at": "2026-03-01T10:05:00Z"
}