Autenticación y Cifrado de Requests

🚧 Early Release — Beta

This product is in early access. Parameters, response structures and behaviors may change without prior notice. Do not use this version in production without coordinating with the Kushki integrations team first.

Every call to Kushki ONE Connect is authenticated with a signature you compute from your Business-Code, and the payload travels encrypted. There is one mechanism, and it is the same everywhere.

The mechanism does not change between topologies

Your signing and encryption logic is identical in Cloud, on the local network and on localhost. Write it once. The only difference is the encrypted_http_communication header, which you send only on the local network and localhost.

Always send the encrypted_http_communication header as true

In Local Network and Localhost integrations, send the header encrypted_http_communication: true on every request, in UAT and in production.

If you certify with the header set to false or without sending it, your requests are not signed or encrypted, and when you move to production every call fails with AUTH-001 ("Invalid or expired credentials").

Cloud integrations do not require this header.

Requirements

Before you start:

Your Business-Code: the private key that authenticates your merchant account. The integrations team hands it over during onboarding.

The device's terminalSerial. The integrations team hands it over during onboarding as well.

Business-Code is not private_credential_id

The signing key is your Business-Code. The private_credential_id is a terminal configuration field and is never used to sign requests. Confusing the two returns an authentication error on every call.

What every request carries

Two headers and an encrypted body:

Element	Value
`Authorization`	`Basic` followed by the SHA-512 hash. The `Basic` prefix is required
`timestamp`	Unix timestamp in seconds, in UTC — must fall within ±5 minutes of server time
Body	`{"data": "<iv_hex>:<ciphertext_hex>"}`

The original payload never travels in plain text. Everything documented as a request body across the Kushki ONE guides is the plaintext you encrypt, not what goes on the wire.

Variables you need

Variable	Description
`businessCode`	The private key that authenticates your merchant account
`terminalSerial`	The SmartPOS terminal serial number
`timestamp`	Unix timestamp in seconds, in UTC
`requestData`	The original request payload

General flow

Every request goes through two independent processes that both start from the same requestData. One produces the signature and the other produces the encrypted payload. Both are sent together.

General sign-and-encrypt flow in Kushki ONE Connect

dataWithKey is never sent

dataWithKey exists only to generate the signature. It is neither encrypted nor transmitted. Including the key field inside the encrypted payload causes an authentication error.

Key derivation chain

The three input variables produce exactly two outputs: aesKey for encryption and encodedKeyTimestamp for the signature. The password is the central value of this chain. It changes every minute because it depends on formattedDate, which makes any signed request expire automatically.

Step 1: generate the timestamp

Store this value in a variable at the start of the flow. You reuse it in steps 3, 4 and 6.

One timestamp per request

Never call Date.now() more than once in the same flow. A different timestamp between the signature, the encryption and the header is the quietest cause of authentication errors.

Step 2: generate formattedDate in UTC

Always compute in UTC

A time zone offset is one of the most frequent causes of an invalid signature. Use the getUTC* methods, never their local-time counterparts.

Step 3: generate the temporary password

Step 4: build dataWithKey

This is a copy of requestData with the key field added. It is used only for signing.

Step 5: generate the signature

Resulting headers:

Authorization: Basic <hash>
timestamp: <timestamp>

Step 6: encrypt the payload

Only requestData is encrypted, without the key field.

Step 7: assemble the final request

The headers are the same across methods. What changes is how you deliver the data field. In Local Network and Localhost, also add the header encrypted_http_communication: true on every request.

Anatomy of a signed and encrypted HTTP request

On POST, PATCH and PUT, the encrypted data goes in the body:

{ "data": "<iv_hex>:<ciphertext_hex>" }

On GET, it goes as a query parameter:

GET /endpoint?data=<iv_hex>:<ciphertext_hex>

Remove every other query parameter from the original request before sending it. This applies to /sync/abort and /async/abort on the local network, and to the print job status endpoint: the identifier they used to carry as a query parameter travels inside the encrypted payload instead.

Operations with no payload sign an empty object

On /abort there is no payload, so what you sign is the literal {} — not an empty string. Two bytes of difference, and the response gives you no hint.

Authentication errors

An invalid signature always returns the same response, with no distinction between causes:

{
  "type": "AUTH",
  "code": "AUTH-001",
  "message": "Invalid or expired credentials"
}

Check these causes in order. They cover the vast majority of cases:

Cause	How you spot it	Fix
`timestamp` in the wrong unit	The value has 13 digits instead of 10	Seconds, not milliseconds
Clock outside the tolerance window	Fails consistently on one machine and works on another	The `timestamp` must fall within ±5 minutes of server time. Sync the clock with NTP
`formattedDate` in local time	The signature fails intermittently depending on the time of day	Compute the date with UTC methods
`key` field included in the encrypted payload	Fails every time, from the very first request	Encrypt `requestData` without `key`; `dataWithKey` is only for signing
`encrypted_http_communication` header missing or set to `false` (Local Network and Localhost)	Passes certification in UAT and fails when you move to production	Send `encrypted_http_communication: true` on every request, in UAT too, and certify again
Empty string signed instead of `{}`	Fails only on `/abort`	Sign the literal `{}`
Body re-serialized after signing	Fails every time, and the payload looks correct	Serialize once, sign that string, send that same string

Never log the full signature

Never write the full value of the Authorization header into your production logs. Log only its presence or absence for diagnostics.

Postman reference script

Set this pre-request script at the collection level so the flow runs automatically on every request. Define the businessCode and terminalSerial variables in your environment.

Accept payments with Kushki ONE

With authentication sorted out, review the card-present payment flows and their sync and async variants.

Authentication errors

Look up the full catalog of error codes, including credentials and permissions.

Autenticación y Cifrado de Requests

Requirements#

What every request carries#

Variables you need#

General flow#

Key derivation chain#

Step 1: generate the timestamp#

Step 2: generate formattedDate in UTC#

Step 3: generate the temporary password#

Step 4: build dataWithKey#

Step 5: generate the signature#

Step 6: encrypt the payload#

Step 7: assemble the final request#

Authentication errors#

Postman reference script#

Requirements

What every request carries

Variables you need

General flow

Key derivation chain

Step 1: generate the timestamp

Step 2: generate formattedDate in UTC

Step 3: generate the temporary password

Step 4: build dataWithKey

Step 5: generate the signature

Step 6: encrypt the payload

Step 7: assemble the final request

Authentication errors

Postman reference script