Payment Credentials
public_credential_id (used for client-side tokenization) and a private_credential_id (used for server-side charges).Master credential required
Private-Merchant-Id header to belong to a main (master) credential — not a regular slave credential. Master credentials are available on demand — contact your Kushki account manager to obtain one.Endpoints at a glance
| Operation | Method | Endpoint |
|---|---|---|
| Create credential | POST | /payment-credentials/v1/credential |
| Search credentials | POST | /payment-credentials/v1/credential/search |
| Advanced search | POST | /payment-credentials/v1/credential/suggestions |
| Activate / Deactivate | PATCH | /payment-credentials/v1/credential/status/{credentialId} |
| Update credential | PATCH | /payment-credentials/v1/credential/{credentialId} |
| Regenerate credential | PATCH | /payment-credentials/v1/credential/recover/{public_credential_id} |
| Delete credential | DELETE | /payment-credentials/v1/credential/{credentialId} |
Create a credential
POST /payment-credentials/v1/credential — generates a new public/private key pair for a merchant.{
"merchant_id": "20000000109815430000",
"alias": "Producción Chile",
"enable": true,
"hidden": false
}201:{
"credential_id": "45fe3a3ebe464ebb100f2aa344b6a095",
"public_credential_id": "4da3fc210f0013bb2abfac6cfbabed65",
"private_credential_id": "c381037a5bfb00f2bd0ee899eb85f11a",
"alias": "Producción Chile"
}| Field | Required | Description |
|---|---|---|
merchant_id | ✅ | The merchant account to create the credential for |
alias | Optional | Human-readable label for the credential |
enable | Optional | true to create the credential as active (default: true) |
hidden | Optional | true to hide the credential from the Kushki Console |
metadata | Optional | Custom key-value metadata |
Search credentials
POST /payment-credentials/v1/credential/search — paginated list of credentials for a merchant.{
"merchantId": "20000000109815430000",
"limit": 20,
"offset": 0,
"filter": {
"alias": "Producción Chile"
}
}{
"total": 3,
"data": [...]
}| Field | Required | Description |
|---|---|---|
merchantId | ✅ | Merchant to search credentials for |
limit | ✅ | Max results per page |
offset | Optional | Pagination offset (0-based) |
filter | Optional | Filter by alias, merchantId, privateCredentialId, publicCredentialId, or credentialId |
Advanced search
POST /payment-credentials/v1/credential/suggestions — retrieve credential details by keyword (alias, ID fragment, etc.).{
"merchantId": "20000000109815430000",
"searchTerm": "Producción"
}{ "total": N, "data": [...] }.Activate or deactivate
PATCH /payment-credentials/v1/credential/status/{credentialId} — enable or disable a credential.{
"action": "DEACTIVATE"
}action value | Effect |
|---|---|
ACTIVATE | Re-enables the credential |
DEACTIVATE | Disables the credential — transactions using this key will be rejected |
Update a credential
PATCH /payment-credentials/v1/credential/{credentialId} — update the alias or metadata of a credential.{
"merchantId": "20000000109815430000",
"alias": "Nuevo alias",
"metadata": {
"env": "production"
}
}Regenerate a credential
PATCH /payment-credentials/v1/credential/recover/{public_credential_id} — generates a new public and private key pair for the credential. The old keys are replaced automatically across all integrations that are using them.⚠️ Key rotation: After calling this endpoint, all integrations using the old public_credential_idorprivate_credential_idwill receive new keys automatically. Plan for a brief transition window.
Delete a credential
DELETE /payment-credentials/v1/credential/{credentialId} — permanently removes a credential. Deleted credentials cannot be recovered.Authentication
Private-Merchant-Id header — but its value must be a main (master) credential's private key, not a regular slave credential:Using the API
🟢 Production
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Available Endpoints
Got a suggestion on this documentation? Contact us.
Modified at 2026-07-31 19:57:17