Programmatically create and manage payment credentials (API keys) for your merchant account. Use this API to provision, search, enable, disable, update, and rotate credentials without going through the Kushki Console.All endpoints require a master credential. The Private-Merchant-Id header must belong to a main or master credential, which can only be generated by a Credential Master user — available on demand. Contact Kushki to activate this role.
Credential Model#
Kushki credentials follow a master / slave hierarchy:| Type | Description |
|---|
master | Root credential for a merchant. Required to call all endpoints in this API. |
slave | Credentials created under a master. Used in day-to-day payment integrations. |
Each credential has three identifiers:| Field | Used as |
|---|
credential_id | Internal Kushki reference for managing the credential |
public_credential_id | Public Key — used in frontend/token requests |
private_credential_id | Private Key — used in backend/charge requests |
Authentication#
All endpoints require the master Private-Merchant-Id as a header:
Endpoints#
Create a Credential#
POST /payment-credentials/v1/credentialCreates a new credential with its own public and private keys under your merchant account.| Field | Required | Description |
|---|
merchant_id | ✅ | Merchant ID to associate the credential with |
alias | ❌ | Friendly name for the credential |
enable | ❌ | Whether the credential is active at creation. Default: false |
hidden | ❌ | Whether to hide the credential in the Console |
metadata | ❌ | Custom key-value data |
Response: returns alias, credential_id, public_credential_id, private_credential_id, and metadata.
Search Credentials#
POST /payment-credentials/v1/credential/searchReturns a paginated list of credentials associated with a merchant, with optional field-level filters.| Field | Required | Description |
|---|
merchantId | ✅ | Merchant ID to search credentials for |
limit | ✅ | Max number of credentials to return |
offset | ❌ | Starting position for pagination |
filter | ❌ | Object to narrow results by alias, merchantId, privateCredentialId, publicCredentialId, or credentialId |
Response: data[] array of credential objects nested under _source, plus total count.
Advanced Search#
POST /payment-credentials/v1/credential/suggestionsSearches credentials by keyword. Useful for autocomplete or fuzzy name lookups.| Field | Description |
|---|
searchTerm | Keyword to search across credential fields |
merchantId | Merchant ID scope for the search |
Response: data[] array of matching credentials with all fields at root level, plus total.
Activate or Deactivate#
PATCH /payment-credentials/v1/credential/status/{credentialId}Enables or disables a credential. Disabled credentials cannot be used to process payments.action | Effect |
|---|
ACTIVATE | Enables the credential |
DEACTIVATE | Disables the credential — payments using it will be rejected |
Returns E008 if the credential is already in the requested state.
Update Credential#
PATCH /payment-credentials/v1/credential/{credentialId}Updates the alias or metadata of an existing credential.| Field | Required | Description |
|---|
merchantId | ✅ | Merchant ID that owns the credential |
alias | ❌ | New friendly name |
metadata | ❌ | Updated custom key-value data |
Delete Credential#
DELETE /payment-credentials/v1/credential/{credentialId}Permanently removes a credential. Once deleted, any integration using it will stop working.No request body needed. Returns 200 on success.
Regenerate a Credential#
PATCH /payment-credentials/v1/credential/recover/{public_credential_id}Generates new public and private keys for the specified credential.This action automatically replaces the old keys across all integrations using them. There is no rollback. Any system still holding the old credentials will stop working immediately after regeneration.
public_credential_id (the current Public Key) as the path parameter.
Credential Fields Reference#
| Field | Type | Description |
|---|
credentialId | string | Internal identifier — use this in path parameters |
publicCredentialId | string | Public Key for frontend and token requests |
privateCredentialId | string | Private Key for backend and charge requests |
alias | string | Friendly display name |
type | string | master or slave |
enable | boolean | Whether the credential is currently active |
hidden | boolean | Whether hidden from the Console UI |
created | integer | Unix timestamp (ms) of creation |
deleteAt | integer | Unix timestamp (ms) of deletion. 0 if not deleted |
Error Codes#
| Code | Message | Cause |
|---|
K004 | ID de comercio o credencial no válido | Invalid or unauthorized Private-Merchant-Id |
E003 | Cuerpo de la petición no válido | Malformed request body |
E005 | No existen las credenciales | credentialId not found |
E006 | El ID de comercio no corresponde a la credencial enviada | Merchant ID does not match the credential provided |
E008 | Credencial ya se encuentra en estado ACTIVO / INACTIVO | Credential is already in the requested activation state |
Using the API#
https://api.kushkipagos.com/
Available Endpoints#
Create a Credential
Creates a new slave credential with its own public and private keys.
Search Credentials
Returns a paginated, filterable list of credentials for a merchant.
Advanced Search
Searches credentials by keyword for autocomplete or fuzzy lookups.
Activate or Deactivate
Enables or disables a credential by credentialId.
Update Credential
Updates the alias or metadata of an existing credential.
Delete Credential
Permanently removes a credential from the merchant account.
Regenerate a Credential
Issues new public and private keys, replacing the old ones across all integrations.
Got a suggestion on this documentation? Contact us.
