Method redeemCertificate

Description

The method is used to redeem a certificate. Once redeemed, the certificate cannot be used again. Called after the checkCertificate method.

Partial Redemption

Partial redemption of a certificate may be available to the provider. In this case, the balance of the certificate may be redeemed multiple times. You can determine whether partial redemption is possible by the allow_partial_redeem parameter in the checkCertificate method. The number of remaining redemptions is available in the available_number_of_uses parameter. Partial redemption is performed by passing the amount parameter and specifying the amount of the balance to be partially redeemed. Note that if the remaining balance after the last available partial redemption is executed, it will not be used.

Request parameters (data)

Parameter	Type	Description
code	string	Mandatory. Certificate code.
pin	string	Secret pin code of the certificate
amount	int	In case of partial redemption it is necessary to specify which part of the certificate balance is to be written off. If this parameter is not passed, the normal full redemption will be performed. If this parameter is not passed after successful partial redemptions, full redemption will be performed for the remaining amount of the certificate balance. The certificate balance is available in the checkCertificate method, parameter balance.

Response parameters (data)

Parameter	Type	Description
ok	integer
msg	string	Message about performed operation
transaction_id	string	Deprecated. The identifier of the performed certificate redemption operation. This parameter is left for backward compatibility, you should not use it. You should use the identifiers from transactions_ids instead. The transactions_id will not occur in the transactions_ids list.
transaction_ids	List<int>	Identifiers of certificate redemption transactions that have been performed. Although the method returns a list of transaction identifiers, this list will always contain at most one item in the case of a vendor certificate redemption.

Example

# Get the value for the SIG substitution
# SECRET in this case is the key stored by the client to sign API requests
$ echo -n 'redeemCertificate{"code":"00342-999-999-999","pin":"9999"}SECRET' | sha256sum - | awk '{print $1}'

# Use the client's known ID and the generated SIG to execute the request
$ curl 'https://api.giftery.es/v1/?cmd=redeemCertificate&id=ID&in=json&out=json&data=%7B%22code%22%3A%2200342-999-999-999%22%2C%22pin%22%3A%229999%22%7D&sig=SIG'

Result of a successful request

{
  "status": "ok",
  "data": {
    "ok": 1,
    "msg": "Certificate redeemed",
    "transaction_id": "9999",
    "transaction_ids": [
      999
    ]
  }
}

Result in case of error

{
    "status": "error",
    "error": {
        "code": 1402,
        "text": "Certificate not found"
    }
}

Error code	Description
1402	The certificate could not be found according to the provided code. It is necessary to check if the code has been transferred correctly. The pin code is checked only if the certificate was found.
1403	The certificate has been blocked. The reason for the blocking can be clarified with the personal manager.
3304	The error occurs when trying to redeem the certificate again