Saltar al contenido

Referencia de la API

Cobros

El cobro de cada periodo y sus intentos en Wompi.

Listar cobros

GET/v1/charges

Más recientes primero, paginado por cursor. Filtros opcionales por suscripción, cliente, estados (repetible o separado por comas) y rango de period_start (from inclusivo, to exclusivo). Sin intentos. Solo cobros del entorno de la API key.

Autenticación: Authorization: Bearer <API key>.

Parámetros

Parámetros de Listar cobros
ParámetroEnTipoDescripción
subscription_idquerystring
Otro formato que sub_… → 422 invalid_subscription_id.
customer_idquerystring
Otro formato que cus_… → 422 invalid_customer_id.
statusqueryarray<ChargeStatus>
Otro valor → 422 invalid_status.

Valores: SCHEDULED, PROCESSING, PENDING, PAID, FAILED, UNCOLLECTIBLE, VOIDED

fromquerystring (date-time)
toquerystring (date-time)
from debe ser anterior a to → si no, 422 invalid_range.
limitqueryinteger
Tamaño de página (1–100, por defecto 50).

Por defecto: 50

starting_afterquerystring
Id (chg_…) del último cobro de la página anterior; otro formato → 422 invalid_cursor; excluyente con ending_before (422 invalid_cursor).
ending_beforequerystring
Id (chg_…) del primer cobro de la página actual, para pedir la anterior (más recientes); excluyente con starting_after (422 invalid_cursor). Mismo orden (más recientes primero); has_more indica si hay más antes de esta página.

Respuestas

200Una página de cobros.

Esquema ChargeList

Campos de la respuesta 200
CampoTipoDescripción
dataobligatorioarray<Charge>
data[].idobligatoriostring

Ejemplo: chg_01JB86R800ABCDEFGHJKMNPQRS

data[].environmentobligatoriostring

Valores: SANDBOX, PRODUCTION

data[].subscription_idobligatoriostring
data[].customer_idobligatoriostring
data[].plan_idobligatoriostring
Plan cuyo precio se cobra en este periodo.
data[].statusobligatoriostring

Valores: SCHEDULED, PROCESSING, PENDING, PAID, FAILED, UNCOLLECTIBLE, VOIDED

data[].amount_in_centsobligatoriointeger (int64)

Ejemplo: 4990000

data[].currencyobligatoriostring

Valores: COP

data[].period_startobligatoriostring (date-time)
RFC 3339 en UTC.
data[].period_endobligatoriostring (date-time)
RFC 3339 en UTC.
data[].attempt_countobligatoriointeger
data[].next_retry_atobligatoriostring (date-time) | null
Próximo reintento automático (dunning).
data[].failure_reasonobligatoriostring | null
Mensaje de Wompi o TENANT_NOT_READY, PAYMENT_METHOD_REQUIRED, TRANSACTION_NOT_CREATED, PENDING_TIMEOUT, GATEWAY_REJECTED.
data[].paid_atobligatoriostring (date-time) | null
data[].voided_atobligatoriostring (date-time) | null
data[].created_atobligatoriostring (date-time)
RFC 3339 en UTC.
data[].updated_atobligatoriostring (date-time)
RFC 3339 en UTC.
has_moreobligatorioboolean

Errores

401

Credencial ausente, inválida, expirada o revocada (code unauthorized).

422

La entrada no cumple las reglas (type invalid_request; param indica el campo).

429

Demasiadas peticiones (type rate_limited, code rate_limited): más de 100 peticiones por segundo con la misma API key. Reintenta cuando indique Retry-After.

Otros

Error con el formato estándar.

Todos con el formato de error estándar.

Petición (cURL)
curl https://api.paygumi.com/v1/charges \
  -H "Authorization: Bearer pgm_test_..."
Respuesta 200
{
  "data": [
    {
      "id": "chg_01JB86R800ABCDEFGHJKMNPQRS",
      "environment": "SANDBOX",
      "subscription_id": "string",
      "customer_id": "string",
      "plan_id": "string",
      "status": "SCHEDULED",
      "amount_in_cents": 4990000,
      "currency": "COP",
      "period_start": "2026-11-01T05:00:00Z",
      "period_end": "2026-11-01T05:00:00Z",
      "attempt_count": 0,
      "next_retry_at": "2026-11-01T05:00:00Z",
      "failure_reason": "string",
      "paid_at": "2026-11-01T05:00:00Z",
      "voided_at": "2026-11-01T05:00:00Z",
      "created_at": "2026-11-01T05:00:00Z",
      "updated_at": "2026-11-01T05:00:00Z"
    }
  ],
  "has_more": false
}

Consultar un cobro con sus intentos

GET/v1/charges/{id}

Detalle del cobro y todos sus intentos en Wompi. De otro tenant o entorno → 404 charge_not_found.

Autenticación: Authorization: Bearer <API key>.

Parámetros

Parámetros de Consultar un cobro con sus intentos
ParámetroEnTipoDescripción
idobligatoriorutastring
Id del cobro (chg_…). Uno mal formado responde 404.

Ejemplo: chg_01JB86R800ABCDEFGHJKMNPQRS

Respuestas

200El cobro.

Esquema ChargeDetail

Campos de la respuesta 200
CampoTipoDescripción
idobligatoriostring

Ejemplo: chg_01JB86R800ABCDEFGHJKMNPQRS

environmentobligatoriostring

Valores: SANDBOX, PRODUCTION

subscription_idobligatoriostring
customer_idobligatoriostring
plan_idobligatoriostring
Plan cuyo precio se cobra en este periodo.
statusobligatoriostring

Valores: SCHEDULED, PROCESSING, PENDING, PAID, FAILED, UNCOLLECTIBLE, VOIDED

amount_in_centsobligatoriointeger (int64)

Ejemplo: 4990000

currencyobligatoriostring

Valores: COP

period_startobligatoriostring (date-time)
RFC 3339 en UTC.
period_endobligatoriostring (date-time)
RFC 3339 en UTC.
attempt_countobligatoriointeger
next_retry_atobligatoriostring (date-time) | null
Próximo reintento automático (dunning).
failure_reasonobligatoriostring | null
Mensaje de Wompi o TENANT_NOT_READY, PAYMENT_METHOD_REQUIRED, TRANSACTION_NOT_CREATED, PENDING_TIMEOUT, GATEWAY_REJECTED.
paid_atobligatoriostring (date-time) | null
voided_atobligatoriostring (date-time) | null
created_atobligatoriostring (date-time)
RFC 3339 en UTC.
updated_atobligatoriostring (date-time)
RFC 3339 en UTC.
attemptsobligatorioarray<PaymentAttempt>
attempts[].idobligatoriostring

Ejemplo: att_01JB86R800ABCDEFGHJKMNPQRS

attempts[].numberobligatoriointeger
attempts[].referenceobligatoriostring
Referencia enviada a Wompi: {tenant_public_id}-{charge_id}-a{n}.
attempts[].triggerobligatoriostring

Valores: SCHEDULED, RETRY, MANUAL, PAYMENT_METHOD_UPDATED

attempts[].wompi_transaction_idobligatoriostring | null
attempts[].statusobligatoriostring

Valores: CREATED, PENDING, APPROVED, DECLINED, ERROR, VOIDED

attempts[].status_messageobligatoriostring | null
attempts[].created_atobligatoriostring (date-time)
RFC 3339 en UTC.
attempts[].finalized_atobligatoriostring (date-time) | null

Errores

401

Credencial ausente, inválida, expirada o revocada (code unauthorized).

404

El recurso no existe o es de otro tenant (nunca 403, para no filtrar existencia).

429

Demasiadas peticiones (type rate_limited, code rate_limited): más de 100 peticiones por segundo con la misma API key. Reintenta cuando indique Retry-After.

Otros

Error con el formato estándar.

Todos con el formato de error estándar.

Petición (cURL)
curl https://api.paygumi.com/v1/charges/{id} \
  -H "Authorization: Bearer pgm_test_..."
Respuesta 200
{
  "id": "chg_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "subscription_id": "string",
  "customer_id": "string",
  "plan_id": "string",
  "status": "SCHEDULED",
  "amount_in_cents": 4990000,
  "currency": "COP",
  "period_start": "2026-11-01T05:00:00Z",
  "period_end": "2026-11-01T05:00:00Z",
  "attempt_count": 0,
  "next_retry_at": "2026-11-01T05:00:00Z",
  "failure_reason": "string",
  "paid_at": "2026-11-01T05:00:00Z",
  "voided_at": "2026-11-01T05:00:00Z",
  "created_at": "2026-11-01T05:00:00Z",
  "updated_at": "2026-11-01T05:00:00Z",
  "attempts": [
    {
      "id": "att_01JB86R800ABCDEFGHJKMNPQRS",
      "number": 1,
      "reference": "string",
      "trigger": "SCHEDULED",
      "wompi_transaction_id": "string",
      "status": "CREATED",
      "status_message": "string",
      "created_at": "2026-11-01T05:00:00Z",
      "finalized_at": "2026-11-01T05:00:00Z"
    }
  ]
}