Payment Credentials

Payment Credentials lets you programmatically manage the API keys associated with your merchant account. Use it to create additional credential sets, rotate keys when they are compromised, control which credentials are active, and keep your integrations organised with aliases and metadata.

Prerequisite — Credential Master user

All endpoints require a master credential to authenticate. This master credential is tied to a Credential Master user account, which Kushki provisions on demand. Contact your Kushki account team to request one.

Operations 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 keys	`PATCH`	`/payment-credentials/v1/credential/recover/{public_credential_id}`
Delete credential	`DELETE`	`/payment-credentials/v1/credential/{credentialId}`

Create a credential

Call POST /payment-credentials/v1/credential to generate a new public/private key pair under your merchant account.

Request:

{
  "merchant_id": "20000000103802320000",
  "alias": "Integración ecommerce",
  "enable": true,
  "hidden": false
}

Response:

{
  "credential_id": "f4c644b64951620ab8952ad58pl63901",
  "public_credential_id": "345213d7d1c64ba28eb88a3b4f1ab0b9",
  "private_credential_id": "c381037a5bfb00f2bd0ee899eb85fllq",
  "alias": "Integración ecommerce",
  "metadata": null
}

Field	Required	Description
`merchant_id`	Yes	Your merchant identifier.
`alias`	No	Human-readable label for this credential.
`enable`	No	`true` to activate immediately (default).
`hidden`	No	`true` to hide from the Kushki Console.
`metadata`	No	Custom key-value pairs for your own tracking.

Search credentials

Call POST /payment-credentials/v1/credential/search to retrieve credentials for a merchant with optional filtering and pagination.

{
  "merchantId": "20000000103802320000",
  "limit": 10,
  "offset": 0,
  "filter": {
    "alias": "ecommerce",
    "credentialId": "f4c644b64951620ab8952ad58pl63901"
  }
}

Field	Required	Description
`merchantId`	Yes	Merchant to query.
`limit`	Yes	Number of results to return.
`offset`	No	Pagination offset.
`filter.alias`	No	Filter by credential alias.
`filter.credentialId`	No	Filter by credential ID.
`filter.publicCredentialId`	No	Filter by public key.
`filter.privateCredentialId`	No	Filter by private key.

The response returns a data array of credential objects and a total count.

Advanced search

Call POST /payment-credentials/v1/credential/suggestions to find credentials by a free-text keyword search across aliases and IDs.

{
  "merchantId": "20000000103802320000",
  "searchTerm": "ecommerce"
}

Activate or deactivate

Call PATCH /payment-credentials/v1/credential/status/{credentialId} to enable or disable a credential without deleting it.

{
  "action": "DEACTIVATE"
}

`action` value	Effect
`ACTIVATE`	Re-enables a previously deactivated credential.
`DEACTIVATE`	Disables the credential — requests using it will be rejected.

Update a credential

Call PATCH /payment-credentials/v1/credential/{credentialId} to change the alias or metadata of an existing credential. The public/private keys are not affected.

{
  "merchantId": "20000000103802320000",
  "alias": "Nuevo alias",
  "metadata": { "env": "production" }
}

Regenerate keys

Call PATCH /payment-credentials/v1/credential/recover/{public_credential_id} to rotate the public and private keys for a credential. Kushki automatically propagates the new keys to all active integrations that were using the old ones.

WARNING

Key rotation is immediate. Ensure your systems can handle the transition before regenerating keys in production.

Delete a credential

Call DELETE /payment-credentials/v1/credential/{credentialId} to permanently remove a credential. This action cannot be undone — any integration still using the deleted credential will immediately stop working.

Authentication

All endpoints use your master credential's Private Key:

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Create Credential

Generate a new public/private key pair under your merchant account.

Search Credentials

Retrieve credentials with pagination and optional filters by alias or ID.

Advanced Search

Find credentials using a free-text keyword across aliases and identifiers.

Activate / Deactivate

Enable or disable a credential without deleting it.

Update Credential

Change the alias or metadata of an existing credential.

Regenerate Keys

Rotate the public and private keys. Old keys are automatically replaced across active integrations.

Delete Credential

Permanently remove a credential. This action cannot be undone.

Got a suggestion on this documentation? Contact us.

Operations at a glance#

Create a credential#

Search credentials#

Advanced search#

Activate or deactivate#

Update a credential#

Regenerate keys#

Delete a credential#

Authentication#

Using the API#

Available Endpoints#