Get subscription history

---

POST /api/v1/integrator/subscription/history

This POST method allows the integrator to retrieve the history of all payment attempts related to a specific subscription in Keepz.

Request details

When sending request to Keepz, these four parameters must always be included in the query parameters:

identifier

• Unique ID of the integrator in the Keepz system.
• Provided by Keepz during the integration process.

encryptedData

• Contains the actual request payload encrypted using a randomly generated symmetric key and IV (Initialization Vector).

encryptedKeys

• Contains the AES key and IV used to encrypt encryptedData.

aes

• Boolean flag indicating that the request uses AES-based symmetric encryption (needed for backward compatibility with older encryption methods).

For details on the encryption process, see the Encryption Guide documentation.

Parameters

The following parameters form the actual subscription history payload. They must be included inside the encryptedData parameter, which is encrypted and passed in the request as shown above.

Parameter	Type	Required	Description	Possible values
subscriptionId	string (UUID v4)	✅	Unique ID of the subscription in the Keepz system. Provided when subscription was created.

Response details

✅ Success Response

If the request is valid, the API returns an encrypted payload:

{
  "encryptedData": "string",
  "encryptedKeys": "string",
  "aes": true
}

encryptedData

• Contains the actual response payload encrypted using a randomly generated symmetric key and IV (Initialization Vector).

encryptedKeys

• Contains the AES key and IV used to encrypt encryptedData.

aes

• Boolean flag indicating that the request uses AES-based symmetric encryption (needed for backward compatibility with older encryption methods).

For details on the decryption process, see the Encryption Guide documentation.

Inside encryptedData, the following parameters are available after decryption:

Parameter	Type	Possible Values / Format	Description
time	string (ISO-8601 datetime)	e.g. 2025-09-08T10:21:33Z	Execution time of the subscription attempt.
status	string	ACQUIRING_IN_PROCESS, COMPLETED, FAILED, REFUNDED_BY_KEEPZ, REFUNDED_BY_INTEGRATOR, REFUNDED_BY_OPERATOR, PARTIALLY_REFUNDED	Current status of the attempt.
refundTime	string (ISO-8601 datetime) | null		Timestamp when refund occurred, if applicable.
refundedAmount	number (decimal)		Amount refunded, if applicable.
failReason	string		Reason for failure, if the attempt failed.

❌ Error Response

If an error occurs, the response is returned without encryption (plain JSON):

{
  "message": "Integrator order not found",
  "statusCode": 6005,
  "exceptionGroup": 5
}

Parameter	Type	Description
message	string	Error message. Details are provided in the dedicated section below.
statusCode	number	Error status code. Details are provided in the dedicated section below.
exceptionGroup	number	Error group. Details are provided in the dedicated section below.