Clientes

Los usuarios de tu sistema que pagan una suscripción, y sus medios de pago.

Registrar un cliente

POST/v1/customers

Registra al usuario de tu sistema que va a pagar, en el entorno de la API key. external_id (tu id del usuario, 1–255 caracteres) es único por entorno: repetido → 409 customer_external_id_taken con el id del cliente existente en error.resource_id y error.param external_id; en el otro entorno se puede repetir. email obligatorio (se guarda en minúsculas); phone opcional, se normaliza a E.164 (un número de 10 dígitos se toma como colombiano, +57); documento opcional (legal_id_type CC, CE, NIT o PP, con su legal_id_number); metadata hasta 20 llaves (1–40 caracteres) con valores de hasta 500. Errores 422: invalid_external_id, invalid_email, invalid_full_name, invalid_phone, invalid_legal_id, invalid_metadata.

Los medios de pago no se crean aquí: el cliente final registra su tarjeta en la página de pago (sesiones de checkout).

Autenticación: Authorization: Bearer <API key>. Acepta Idempotency-Key.

Parámetros

Parámetros de Registrar un cliente
Parámetro	En	Tipo	Descripción
`Idempotency-Key`	cabecera	string	Clave elegida por el cliente (1–255 caracteres ASCII visibles; se recomienda un UUID v4) para reintentar un `POST` sin repetir su efecto. Es única por tenant y entorno de la API key. La respuesta (2xx o 4xx) se guarda 24 h; las 5xx no se guardan. Misma clave y misma petición (método, ruta con query y body idénticos byte a byte): se devuelve la respuesta guardada, con `Idempotent-Replayed: true`, sin volver a ejecutar. Misma clave con otra petición → `422 idempotency_key_reused`. Misma clave mientras la primera sigue en curso → `409 idempotency_key_in_use` (reintenta en unos segundos). Clave mal formada → `422 invalid_idempotency_key`; body de más de 1 MiB → `413`. Ejemplo: `3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14`

Cuerpo (application/json, `RegisterCustomerRequest`)

Campos del cuerpo de Registrar un cliente
Campo	Tipo	Descripción
`external_id`obligatorio	string	Ejemplo: `user_42`
`email`obligatorio	string (email)
`full_name`	string
`phone`	string	E.164 (`+573001234567`) o número colombiano de 10 dígitos.
`legal_id_type`	string	Valores: `CC,` `CE,` `NIT,` `PP`
`legal_id_number`	string
`metadata`	object<string, string>

Respuestas

201Cliente registrado (o la misma respuesta repetida, con Idempotent-Replayed).

Esquema Customer

Campos de la respuesta 201
Campo	Tipo	Descripción
`id`obligatorio	string	Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`
`environment`obligatorio	string	Valores: `SANDBOX,` `PRODUCTION`
`external_id`obligatorio	string	Id del usuario en tu sistema (inmutable).
`email`obligatorio	string (email)
`full_name`obligatorio	string \| null
`phone`obligatorio	string \| null	E.164 Ejemplo: `+573001234567`
`legal_id_type`obligatorio	string \| null	Valores: `CC,` `CE,` `NIT,` `PP`
`legal_id_number`obligatorio	string \| null
`metadata`obligatorio	object<string, string>
`payment_methods`obligatorio	array<PaymentMethod>
`payment_methods[].id`obligatorio	string	Ejemplo: `pm_01JB86R800ABCDEFGHJKMNPQRS`
`payment_methods[].type`obligatorio	string	Valores: `CARD,` `NEQUI,` `BANCOLOMBIA_TRANSFER`
`payment_methods[].brand`obligatorio	string \| null	Marca de la tarjeta (VISA, MASTERCARD, …), `NEQUI` o el tipo de cuenta Bancolombia. Ejemplo: `VISA`
`payment_methods[].last4`obligatorio	string \| null	Últimos 4 de la tarjeta, del celular Nequi o de la cuenta Bancolombia. Ejemplo: `4242`
`payment_methods[].exp_month`obligatorio	integer \| null
`payment_methods[].exp_year`obligatorio	integer \| null
`payment_methods[].is_default`obligatorio	boolean	Exactamente un medio `ACTIVE` es el predeterminado (si hay alguno).
`payment_methods[].status`obligatorio	string	Valores: `ACTIVE,` `INVALID`
`payment_methods[].created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`updated_at`obligatorio	string (date-time)	RFC 3339 en UTC.

Idempotent-Replayed: true si la respuesta es la guardada de una petición anterior con la misma Idempotency-Key.

Errores

400: JSON mal formado o tipos inválidos (p. ej. decimales donde va un entero) (code invalid_body).
401: Credencial ausente, inválida, expirada o revocada (code unauthorized).
409: Conflicto. code: already_member, api_key_limit_exceeded, last_owner, invitation_expired, invitation_not_pending, webhook_endpoint_limit_exceeded, plan_name_taken (param name), customer_external_id_taken (con resource_id y param external_id; en POST /v1/checkout-sessions, customer.external_id), last_payment_method_in_use, payment_method_not_active, idempotency_key_in_use, tenant_not_ready (el entorno no tiene credenciales de Wompi verificadas), checkout_session_completed, checkout_session_expired, checkout_session_canceled, plan_archived, subscription_exists (con resource_id), subscription_version_conflict (reintenta), payment_method_required, subscription_not_pausable, subscription_not_paused, subscription_not_changeable, subscription_cancel_at_period_end_not_allowed, subscription_cancel_not_scheduled, portal_disabled (el tenant deshabilitó el portal en el entorno).
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 -X POST https://api.paygumi.com/v1/customers \
  -H "Authorization: Bearer pgm_test_..." \
  -H "Idempotency-Key: 3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "user_42",
  "email": "cliente@ejemplo.co"
}'

Respuesta 201

{
  "id": "cus_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "external_id": "string",
  "email": "cliente@ejemplo.co",
  "full_name": "string",
  "phone": "+573001234567",
  "legal_id_type": "CC",
  "legal_id_number": "string",
  "metadata": {},
  "payment_methods": [
    {
      "id": "pm_01JB86R800ABCDEFGHJKMNPQRS",
      "type": "CARD",
      "brand": "VISA",
      "last4": "4242",
      "exp_month": 1,
      "exp_year": 0,
      "is_default": false,
      "status": "ACTIVE",
      "created_at": "2026-11-01T05:00:00Z"
    }
  ],
  "created_at": "2026-11-01T05:00:00Z",
  "updated_at": "2026-11-01T05:00:00Z"
}

Ver un cliente

GET/v1/customers/{id}

El cliente con sus medios de pago activos o inválidos (sin datos sensibles: marca, últimos 4 y expiración; nunca el número de la tarjeta ni el id de la fuente de Wompi) y el resumen de sus suscripciones. De otro entorno → 404 customer_not_found.

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

Parámetros

Parámetros de Ver un cliente
Parámetro	En	Tipo	Descripción
`id`obligatorio	ruta	string	Id del cliente (`cus_…`). Uno mal formado responde `404`. Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`

Respuestas

200El cliente.

Esquema CustomerDetail

Campos de la respuesta 200
Campo	Tipo	Descripción
`id`obligatorio	string	Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`
`environment`obligatorio	string	Valores: `SANDBOX,` `PRODUCTION`
`external_id`obligatorio	string	Id del usuario en tu sistema (inmutable).
`email`obligatorio	string (email)
`full_name`obligatorio	string \| null
`phone`obligatorio	string \| null	E.164 Ejemplo: `+573001234567`
`legal_id_type`obligatorio	string \| null	Valores: `CC,` `CE,` `NIT,` `PP`
`legal_id_number`obligatorio	string \| null
`metadata`obligatorio	object<string, string>
`payment_methods`obligatorio	array<PaymentMethod>
`payment_methods[].id`obligatorio	string	Ejemplo: `pm_01JB86R800ABCDEFGHJKMNPQRS`
`payment_methods[].type`obligatorio	string	Valores: `CARD,` `NEQUI,` `BANCOLOMBIA_TRANSFER`
`payment_methods[].brand`obligatorio	string \| null	Marca de la tarjeta (VISA, MASTERCARD, …), `NEQUI` o el tipo de cuenta Bancolombia. Ejemplo: `VISA`
`payment_methods[].last4`obligatorio	string \| null	Últimos 4 de la tarjeta, del celular Nequi o de la cuenta Bancolombia. Ejemplo: `4242`
`payment_methods[].exp_month`obligatorio	integer \| null
`payment_methods[].exp_year`obligatorio	integer \| null
`payment_methods[].is_default`obligatorio	boolean	Exactamente un medio `ACTIVE` es el predeterminado (si hay alguno).
`payment_methods[].status`obligatorio	string	Valores: `ACTIVE,` `INVALID`
`payment_methods[].created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`updated_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`subscriptions`obligatorio	array<SubscriptionSummary>	Resumen de las suscripciones del cliente, más recientes primero.
`subscriptions[].id`obligatorio	string	Ejemplo: `sub_01JB86R800ABCDEFGHJKMNPQRS`
`subscriptions[].status`obligatorio	string
`subscriptions[].access_status`obligatorio	string	Valores: `GRANTED,` `RESTRICTED,` `REVOKED`
`subscriptions[].plan_name`obligatorio	string

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/customers/{id} \
  -H "Authorization: Bearer pgm_test_..."

Respuesta 200

{
  "id": "cus_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "external_id": "string",
  "email": "cliente@ejemplo.co",
  "full_name": "string",
  "phone": "+573001234567",
  "legal_id_type": "CC",
  "legal_id_number": "string",
  "metadata": {},
  "payment_methods": [
    {
      "id": "pm_01JB86R800ABCDEFGHJKMNPQRS",
      "type": "CARD",
      "brand": "VISA",
      "last4": "4242",
      "exp_month": 1,
      "exp_year": 0,
      "is_default": false,
      "status": "ACTIVE",
      "created_at": "2026-11-01T05:00:00Z"
    }
  ],
  "created_at": "2026-11-01T05:00:00Z",
  "updated_at": "2026-11-01T05:00:00Z",
  "subscriptions": [
    {
      "id": "sub_01JB86R800ABCDEFGHJKMNPQRS",
      "status": "string",
      "access_status": "GRANTED",
      "plan_name": "string"
    }
  ]
}

Editar un cliente

PATCH/v1/customers/{id}

Cambia email, full_name, phone ("" lo borra) y metadata (reemplaza el mapa completo; {} lo borra). Campos ausentes no cambian. external_id es inmutable: enviarlo distinto → 422 external_id_immutable. Cambiar el email no cambia el de la fuente de pago en Wompi; los cobros siguientes usan el nuevo.

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

Parámetros

Parámetros de Editar un cliente
Parámetro	En	Tipo	Descripción
`id`obligatorio	ruta	string	Id del cliente (`cus_…`). Uno mal formado responde `404`. Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`

Cuerpo (application/json, `UpdateCustomerRequest`)

Campos ausentes (o null) no cambian.

Campos del cuerpo de Editar un cliente
Campo	Tipo	Descripción
`email`	string (email)
`full_name`	string
`phone`	string	`""` borra el teléfono.
`metadata`	object<string, string>	Reemplaza el mapa completo; `{}` lo borra.
`external_id`	string	Inmutable; solo se acepta el valor actual.

Respuestas

200Cliente actualizado.

Esquema Customer

Campos de la respuesta 200
Campo	Tipo	Descripción
`id`obligatorio	string	Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`
`environment`obligatorio	string	Valores: `SANDBOX,` `PRODUCTION`
`external_id`obligatorio	string	Id del usuario en tu sistema (inmutable).
`email`obligatorio	string (email)
`full_name`obligatorio	string \| null
`phone`obligatorio	string \| null	E.164 Ejemplo: `+573001234567`
`legal_id_type`obligatorio	string \| null	Valores: `CC,` `CE,` `NIT,` `PP`
`legal_id_number`obligatorio	string \| null
`metadata`obligatorio	object<string, string>
`payment_methods`obligatorio	array<PaymentMethod>
`payment_methods[].id`obligatorio	string	Ejemplo: `pm_01JB86R800ABCDEFGHJKMNPQRS`
`payment_methods[].type`obligatorio	string	Valores: `CARD,` `NEQUI,` `BANCOLOMBIA_TRANSFER`
`payment_methods[].brand`obligatorio	string \| null	Marca de la tarjeta (VISA, MASTERCARD, …), `NEQUI` o el tipo de cuenta Bancolombia. Ejemplo: `VISA`
`payment_methods[].last4`obligatorio	string \| null	Últimos 4 de la tarjeta, del celular Nequi o de la cuenta Bancolombia. Ejemplo: `4242`
`payment_methods[].exp_month`obligatorio	integer \| null
`payment_methods[].exp_year`obligatorio	integer \| null
`payment_methods[].is_default`obligatorio	boolean	Exactamente un medio `ACTIVE` es el predeterminado (si hay alguno).
`payment_methods[].status`obligatorio	string	Valores: `ACTIVE,` `INVALID`
`payment_methods[].created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`updated_at`obligatorio	string (date-time)	RFC 3339 en UTC.

Errores

400: JSON mal formado o tipos inválidos (p. ej. decimales donde va un entero) (code invalid_body).
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).
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 -X PATCH https://api.paygumi.com/v1/customers/{id} \
  -H "Authorization: Bearer pgm_test_..."

Respuesta 200

{
  "id": "cus_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "external_id": "string",
  "email": "cliente@ejemplo.co",
  "full_name": "string",
  "phone": "+573001234567",
  "legal_id_type": "CC",
  "legal_id_number": "string",
  "metadata": {},
  "payment_methods": [
    {
      "id": "pm_01JB86R800ABCDEFGHJKMNPQRS",
      "type": "CARD",
      "brand": "VISA",
      "last4": "4242",
      "exp_month": 1,
      "exp_year": 0,
      "is_default": false,
      "status": "ACTIVE",
      "created_at": "2026-11-01T05:00:00Z"
    }
  ],
  "created_at": "2026-11-01T05:00:00Z",
  "updated_at": "2026-11-01T05:00:00Z"
}

Quitar un medio de pago

DELETE/v1/customers/{id}/payment-methods/{pmId}

Borrado lógico: el medio deja de mostrarse y de cobrarse; los cobros históricos lo siguen referenciando. Si era el predeterminado, el activo más reciente pasa a serlo, y las suscripciones que lo usaban pasan al predeterminado. Es el único activo y el cliente tiene suscripciones vivas → 409 last_payment_method_in_use. Ya quitado o inexistente → 404 payment_method_not_found. Responde el cliente actualizado.

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

Parámetros

Parámetros de Quitar un medio de pago
Parámetro	En	Tipo	Descripción
`id`obligatorio	ruta	string	Id del cliente (`cus_…`). Uno mal formado responde `404`. Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`
`pmId`obligatorio	ruta	string	Id del medio de pago (`pm_…`). Uno mal formado responde `404`. Ejemplo: `pm_01JB86R800ABCDEFGHJKMNPQRS`

Respuestas

200Cliente actualizado (sin el medio quitado).

Esquema Customer

Campos de la respuesta 200
Campo	Tipo	Descripción
`id`obligatorio	string	Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`
`environment`obligatorio	string	Valores: `SANDBOX,` `PRODUCTION`
`external_id`obligatorio	string	Id del usuario en tu sistema (inmutable).
`email`obligatorio	string (email)
`full_name`obligatorio	string \| null
`phone`obligatorio	string \| null	E.164 Ejemplo: `+573001234567`
`legal_id_type`obligatorio	string \| null	Valores: `CC,` `CE,` `NIT,` `PP`
`legal_id_number`obligatorio	string \| null
`metadata`obligatorio	object<string, string>
`payment_methods`obligatorio	array<PaymentMethod>
`payment_methods[].id`obligatorio	string	Ejemplo: `pm_01JB86R800ABCDEFGHJKMNPQRS`
`payment_methods[].type`obligatorio	string	Valores: `CARD,` `NEQUI,` `BANCOLOMBIA_TRANSFER`
`payment_methods[].brand`obligatorio	string \| null	Marca de la tarjeta (VISA, MASTERCARD, …), `NEQUI` o el tipo de cuenta Bancolombia. Ejemplo: `VISA`
`payment_methods[].last4`obligatorio	string \| null	Últimos 4 de la tarjeta, del celular Nequi o de la cuenta Bancolombia. Ejemplo: `4242`
`payment_methods[].exp_month`obligatorio	integer \| null
`payment_methods[].exp_year`obligatorio	integer \| null
`payment_methods[].is_default`obligatorio	boolean	Exactamente un medio `ACTIVE` es el predeterminado (si hay alguno).
`payment_methods[].status`obligatorio	string	Valores: `ACTIVE,` `INVALID`
`payment_methods[].created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`updated_at`obligatorio	string (date-time)	RFC 3339 en UTC.

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).
409: Conflicto. code: already_member, api_key_limit_exceeded, last_owner, invitation_expired, invitation_not_pending, webhook_endpoint_limit_exceeded, plan_name_taken (param name), customer_external_id_taken (con resource_id y param external_id; en POST /v1/checkout-sessions, customer.external_id), last_payment_method_in_use, payment_method_not_active, idempotency_key_in_use, tenant_not_ready (el entorno no tiene credenciales de Wompi verificadas), checkout_session_completed, checkout_session_expired, checkout_session_canceled, plan_archived, subscription_exists (con resource_id), subscription_version_conflict (reintenta), payment_method_required, subscription_not_pausable, subscription_not_paused, subscription_not_changeable, subscription_cancel_at_period_end_not_allowed, subscription_cancel_not_scheduled, portal_disabled (el tenant deshabilitó el portal en el entorno).
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 -X DELETE https://api.paygumi.com/v1/customers/{id}/payment-methods/{pmId} \
  -H "Authorization: Bearer pgm_test_..."

Respuesta 200

{
  "id": "cus_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "external_id": "string",
  "email": "cliente@ejemplo.co",
  "full_name": "string",
  "phone": "+573001234567",
  "legal_id_type": "CC",
  "legal_id_number": "string",
  "metadata": {},
  "payment_methods": [
    {
      "id": "pm_01JB86R800ABCDEFGHJKMNPQRS",
      "type": "CARD",
      "brand": "VISA",
      "last4": "4242",
      "exp_month": 1,
      "exp_year": 0,
      "is_default": false,
      "status": "ACTIVE",
      "created_at": "2026-11-01T05:00:00Z"
    }
  ],
  "created_at": "2026-11-01T05:00:00Z",
  "updated_at": "2026-11-01T05:00:00Z"
}

Marcar un medio de pago como predeterminado

POST/v1/customers/{id}/payment-methods/{pmId}/default

Los próximos cobros de las suscripciones sin medio explícito usan este. Exactamente un medio es el predeterminado. Idempotente. Un medio INVALID → 409 payment_method_not_active. Responde el cliente actualizado. Acepta Idempotency-Key.

Autenticación: Authorization: Bearer <API key>. Acepta Idempotency-Key.

Parámetros

Parámetros de Marcar un medio de pago como predeterminado
Parámetro	En	Tipo	Descripción
`id`obligatorio	ruta	string	Id del cliente (`cus_…`). Uno mal formado responde `404`. Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`
`pmId`obligatorio	ruta	string	Id del medio de pago (`pm_…`). Uno mal formado responde `404`. Ejemplo: `pm_01JB86R800ABCDEFGHJKMNPQRS`
`Idempotency-Key`	cabecera	string	Clave elegida por el cliente (1–255 caracteres ASCII visibles; se recomienda un UUID v4) para reintentar un `POST` sin repetir su efecto. Es única por tenant y entorno de la API key. La respuesta (2xx o 4xx) se guarda 24 h; las 5xx no se guardan. Misma clave y misma petición (método, ruta con query y body idénticos byte a byte): se devuelve la respuesta guardada, con `Idempotent-Replayed: true`, sin volver a ejecutar. Misma clave con otra petición → `422 idempotency_key_reused`. Misma clave mientras la primera sigue en curso → `409 idempotency_key_in_use` (reintenta en unos segundos). Clave mal formada → `422 invalid_idempotency_key`; body de más de 1 MiB → `413`. Ejemplo: `3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14`

Respuestas

200Cliente actualizado.

Esquema Customer

Campos de la respuesta 200
Campo	Tipo	Descripción
`id`obligatorio	string	Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`
`environment`obligatorio	string	Valores: `SANDBOX,` `PRODUCTION`
`external_id`obligatorio	string	Id del usuario en tu sistema (inmutable).
`email`obligatorio	string (email)
`full_name`obligatorio	string \| null
`phone`obligatorio	string \| null	E.164 Ejemplo: `+573001234567`
`legal_id_type`obligatorio	string \| null	Valores: `CC,` `CE,` `NIT,` `PP`
`legal_id_number`obligatorio	string \| null
`metadata`obligatorio	object<string, string>
`payment_methods`obligatorio	array<PaymentMethod>
`payment_methods[].id`obligatorio	string	Ejemplo: `pm_01JB86R800ABCDEFGHJKMNPQRS`
`payment_methods[].type`obligatorio	string	Valores: `CARD,` `NEQUI,` `BANCOLOMBIA_TRANSFER`
`payment_methods[].brand`obligatorio	string \| null	Marca de la tarjeta (VISA, MASTERCARD, …), `NEQUI` o el tipo de cuenta Bancolombia. Ejemplo: `VISA`
`payment_methods[].last4`obligatorio	string \| null	Últimos 4 de la tarjeta, del celular Nequi o de la cuenta Bancolombia. Ejemplo: `4242`
`payment_methods[].exp_month`obligatorio	integer \| null
`payment_methods[].exp_year`obligatorio	integer \| null
`payment_methods[].is_default`obligatorio	boolean	Exactamente un medio `ACTIVE` es el predeterminado (si hay alguno).
`payment_methods[].status`obligatorio	string	Valores: `ACTIVE,` `INVALID`
`payment_methods[].created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`created_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`updated_at`obligatorio	string (date-time)	RFC 3339 en UTC.

Idempotent-Replayed: true si la respuesta es la guardada de una petición anterior con la misma Idempotency-Key.

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).
409: Conflicto. code: already_member, api_key_limit_exceeded, last_owner, invitation_expired, invitation_not_pending, webhook_endpoint_limit_exceeded, plan_name_taken (param name), customer_external_id_taken (con resource_id y param external_id; en POST /v1/checkout-sessions, customer.external_id), last_payment_method_in_use, payment_method_not_active, idempotency_key_in_use, tenant_not_ready (el entorno no tiene credenciales de Wompi verificadas), checkout_session_completed, checkout_session_expired, checkout_session_canceled, plan_archived, subscription_exists (con resource_id), subscription_version_conflict (reintenta), payment_method_required, subscription_not_pausable, subscription_not_paused, subscription_not_changeable, subscription_cancel_at_period_end_not_allowed, subscription_cancel_not_scheduled, portal_disabled (el tenant deshabilitó el portal en el entorno).
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 -X POST https://api.paygumi.com/v1/customers/{id}/payment-methods/{pmId}/default \
  -H "Authorization: Bearer pgm_test_..." \
  -H "Idempotency-Key: 3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14"

Respuesta 200

{
  "id": "cus_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "external_id": "string",
  "email": "cliente@ejemplo.co",
  "full_name": "string",
  "phone": "+573001234567",
  "legal_id_type": "CC",
  "legal_id_number": "string",
  "metadata": {},
  "payment_methods": [
    {
      "id": "pm_01JB86R800ABCDEFGHJKMNPQRS",
      "type": "CARD",
      "brand": "VISA",
      "last4": "4242",
      "exp_month": 1,
      "exp_year": 0,
      "is_default": false,
      "status": "ACTIVE",
      "created_at": "2026-11-01T05:00:00Z"
    }
  ],
  "created_at": "2026-11-01T05:00:00Z",
  "updated_at": "2026-11-01T05:00:00Z"
}

Clientes

Registrar un cliente

Parámetros

Cuerpo (application/json, RegisterCustomerRequest)

Respuestas

Errores

Ver un cliente

Parámetros

Respuestas

Errores

Editar un cliente

Parámetros

Cuerpo (application/json, UpdateCustomerRequest)

Respuestas

Errores

Quitar un medio de pago

Parámetros

Respuestas

Errores

Marcar un medio de pago como predeterminado

Parámetros

Respuestas

Errores

Cuerpo (application/json, `RegisterCustomerRequest`)

Cuerpo (application/json, `UpdateCustomerRequest`)