Crea y administra de forma programática las credenciales de pago (API keys) de tu cuenta de comercio. Usa esta API para provisionar, buscar, habilitar, deshabilitar, actualizar y rotar credenciales sin pasar por la Kushki Console.Todos los endpoints requieren una credencial master. La cabecera Private-Merchant-Id debe pertenecer a una credencial principal o master, que solo puede generar un usuario Credential Master — disponible bajo demanda. Contacta a Kushki para activar este rol.
Modelo de credenciales#
Las credenciales de Kushki siguen una jerarquía master / slave:| Tipo | Descripción |
|---|
master | Credencial raíz de un comercio. Necesaria para llamar a todos los endpoints de esta API. |
slave | Credenciales creadas bajo una master. Se usan en las integraciones de pago del día a día. |
Cada credencial tiene tres identificadores:| Campo | Se usa como |
|---|
credential_id | Referencia interna de Kushki para administrar la credencial |
public_credential_id | Public Key — se usa en las peticiones de frontend y de token |
private_credential_id | Private Key — se usa en las peticiones de backend y de cargo |
Autenticación#
Todos los endpoints requieren el Private-Merchant-Id master como cabecera:
Endpoints#
Crear una credencial#
POST /payment-credentials/v1/credentialCrea una nueva credencial con sus propias llaves pública y privada en tu cuenta de comercio.| Campo | Requerido | Descripción |
|---|
merchant_id | ✅ | ID del comercio al que se asociará la credencial |
alias | ❌ | Nombre descriptivo de la credencial |
enable | ❌ | Indica si la credencial queda activa al crearse. Por defecto: false |
hidden | ❌ | Indica si la credencial se oculta en la Console |
metadata | ❌ | Datos personalizados de clave-valor |
Respuesta: devuelve alias, credential_id, public_credential_id, private_credential_id y metadata.
Buscar credenciales#
POST /payment-credentials/v1/credential/searchDevuelve una lista paginada de credenciales asociadas a un comercio, con filtros opcionales por campo.| Campo | Requerido | Descripción |
|---|
merchantId | ✅ | ID del comercio cuyas credenciales quieres buscar |
limit | ✅ | Cantidad máxima de credenciales a devolver |
offset | ❌ | Posición inicial para la paginación |
filter | ❌ | Objeto para acotar los resultados por alias, merchantId, privateCredentialId, publicCredentialId o credentialId |
Respuesta: arreglo data[] de objetos de credencial anidados bajo _source, más el conteo total.
Búsqueda avanzada#
POST /payment-credentials/v1/credential/suggestionsBusca credenciales por palabra clave. Útil para autocompletado o búsquedas aproximadas por nombre.| Campo | Descripción |
|---|
searchTerm | Palabra clave a buscar en los campos de la credencial |
merchantId | ID del comercio que delimita la búsqueda |
Respuesta: arreglo data[] de credenciales coincidentes con todos los campos en el nivel raíz, más total.
Activar o desactivar#
PATCH /payment-credentials/v1/credential/status/{credentialId}Habilita o deshabilita una credencial. Las credenciales deshabilitadas no se pueden usar para procesar pagos.action | Efecto |
|---|
ACTIVATE | Habilita la credencial |
DEACTIVATE | Deshabilita la credencial — los pagos que la usen serán rechazados |
Devuelve E008 si la credencial ya está en el estado solicitado.
Actualizar credencial#
PATCH /payment-credentials/v1/credential/{credentialId}Actualiza el alias o el metadata de una credencial existente.| Campo | Requerido | Descripción |
|---|
merchantId | ✅ | ID del comercio dueño de la credencial |
alias | ❌ | Nuevo nombre descriptivo |
metadata | ❌ | Datos personalizados de clave-valor actualizados |
Eliminar credencial#
DELETE /payment-credentials/v1/credential/{credentialId}Elimina una credencial de forma permanente. Una vez eliminada, cualquier integración que la use dejará de funcionar.No necesita cuerpo de la petición. Devuelve 200 cuando la operación es exitosa.
Regenerar una credencial#
PATCH /payment-credentials/v1/credential/recover/{public_credential_id}Genera nuevas llaves pública y privada para la credencial indicada.Esta acción reemplaza automáticamente las llaves anteriores en todas las integraciones que las usan. No hay marcha atrás. Cualquier sistema que siga guardando las credenciales anteriores dejará de funcionar inmediatamente después de la regeneración.
public_credential_id (la Public Key actual) como parámetro de ruta.
Referencia de campos de la credencial#
| Campo | Tipo | Descripción |
|---|
credentialId | string | Identificador interno — úsalo en los parámetros de ruta |
publicCredentialId | string | Public Key para las peticiones de frontend y de token |
privateCredentialId | string | Private Key para las peticiones de backend y de cargo |
alias | string | Nombre descriptivo para mostrar |
type | string | master o slave |
enable | boolean | Indica si la credencial está activa actualmente |
hidden | boolean | Indica si está oculta en la interfaz de la Console |
created | integer | Timestamp Unix (ms) de creación |
deleteAt | integer | Timestamp Unix (ms) de eliminación. 0 si no está eliminada |
Códigos de error#
| Código | Mensaje | Causa |
|---|
K004 | ID de comercio o credencial no válido | Private-Merchant-Id no válido o sin autorización |
E003 | Cuerpo de la petición no válido | Cuerpo de la petición mal formado |
E005 | No existen las credenciales | No se encontró el credentialId |
E006 | El ID de comercio no corresponde a la credencial enviada | El ID de comercio no coincide con la credencial enviada |
E008 | Credencial ya se encuentra en estado ACTIVO / INACTIVO | La credencial ya está en el estado de activación solicitado |
Usar la API#
https://api.kushkipagos.com/
Endpoints disponibles#
Crear una credencial
Crea una nueva credencial slave con sus propias llaves pública y privada.
Buscar credenciales
Devuelve una lista paginada y filtrable de las credenciales de un comercio.
Búsqueda avanzada
Busca credenciales por palabra clave para autocompletado o búsquedas aproximadas.
Activar o desactivar
Habilita o deshabilita una credencial por su credentialId.
Actualizar una credencial
Actualiza el alias o el metadata de una credencial existente.
Eliminar una credencial
Elimina de forma permanente una credencial de la cuenta del comercio.
Regenerar una credencial
Emite nuevas llaves pública y privada y reemplaza las anteriores en todas las integraciones.
¿Tienes una sugerencia sobre esta documentación? Contáctanos.
