Listen to Webhooks

Configuring Webhooks

To configure webhooks

1. Go to the Webhooks page.

2. Click on the Edit button.

3. Consider adding only https url for higher success rate.

4. Click on Save.

To edit the number of requests that can be received by the webhook:

1. Click on the Edit Button beside the rate.

2. Enter the desired number of requests per minute.

3. Click Save.

Webhook guide

The webhook should accept the request body as a string. This string should be Base64 encoded and encrypted using the encryption key specified on the key page.

Encryption procedure

• Method to encrypt:

fun encrypt(
   stringToEncrypt: String,
   password: String,
): String {
   try {
       val salt = "your api key"
       val ivParameterSpec: IvParameterSpec = AESUtil.generateIv()
       val key: SecretKey = AESUtil.getKeyFromPassword(password, salt)
       return AESUtil.encryptPasswordBased(stringToEncrypt, key, ivParameterSpec)
   } catch (ex: Exception) {
       throw BadRequestException()
   }
}

• Method To decrypt:

fun decryptWithPassword(toDecrypt: String, password: String): String {
   return try {
       val salt = "your api key"
       val ivParameterSpec: IvParameterSpec = AESUtil.generateIv()
       val key: SecretKey = AESUtil.getKeyFromPassword(password, salt)
       AESUtil.decryptPasswordBased(
           toDecrypt, key, ivParameterSpec
       )
   } catch (ex: Exception) {
       throw BadRequestException()
   }
}

• Method to decode the request:

String(
Base64.getDecoder().decode(
   		decryptWithPassword(
      	 		request,
       		"encryptionKey"
        )
    )
)

You can find the API key here.

After sucessfully decrypting the request, convert it to a JSON object with the following structure:

{
  "transactionCode": "",
  "state": "",
  "paymentInstrument": "",
  "paymentSubInstrument": "",
  "currency": {
    "code": "",
    "name": "",
    "knownName": "",
    "serviceable": false,
    "notServiceableMessage": "",
    "decimalPrecision": 0,
    "id": "",
    "lastUpdated": null,
    "createdDate": null,
    "dataStatus": ""
  },
  "amount": 0.0,
  "cancelReason": null,
  "comment": "",
  "extraCustomerInfo": ""
}

To send the transactionCode in the provided JSON after encrypting it:

1. Encrypt the transactionCode:

   encrypt(
       Base64.getEncoder().encodeToString(payload.transactionCode.encodeToByteArray()),
       "encryptionKey"
   )

2. Wrap the encrypted string in JSON format:

   {
     "response": "encrypted string"
   }

3. Return it with the response code HTTPStatusCode 200.

Example of Webhook Controller:

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.stereotype.Component;
import java.util.*;
import javax.crypto.SecretKey;
import javax.crypto.spec.IvParameterSpec;

@RestController
@RequestMapping("/paymentProvider/webhook/change/webhook")
class CustomController {

    @PostMapping
    fun customWebHookResponse(
        @RequestBody request: String
    ): ResponseEntity<OutgoingWebHookResponse> {
        val payload = ConverterStringToObjectList.getSingleObject<OutGoingWebHookPayload>(
            decode(
                decryptWithPassword(
                    request,
                    "encryptionKey"
                )
            )
        );
        return ResponseEntity(
            OutgoingWebHookResponse(
                encrypt(
                    encode(payload.transactionCode),
                    "encryptionKey"
                )
            ), HttpStatus.OK
        );
    }

    fun encrypt(
        stringToEncrypt: String,
        password: String,
    ): String {
        try {
            val salt = "your api key";
            val ivParameterSpec: IvParameterSpec = AESUtil.generateIv();
            val key: SecretKey = AESUtil.getKeyFromPassword(password, salt);
            return AESUtil.encryptPasswordBased(stringToEncrypt, key, ivParameterSpec);
        } catch (ex: Exception) {
            throw ex;
        }
    }

    fun decryptWithPassword(
        toDecrypt: String,
        password: String
    ): String {
        return try {
            val saltFinal = "your api key";
            val ivParameterSpec: IvParameterSpec = AESUtil.generateIv();
            val key: SecretKey = AESUtil.getKeyFromPassword(password, saltFinal);
            AESUtil.decryptPasswordBased(toDecrypt, key, ivParameterSpec);
        } catch (ex: Exception) {
            throw ex;
        }
    }

    fun encode(toEncode: String): String {
        return Base64.getEncoder().encodeToString(toEncode.encodeToByteArray());
    }

    fun decode(toDecode: String): String {
        return String(Base64.getDecoder().decode(toDecode));
    }
}

Example of response model:

data class OutgoingWebHookResponse(
   val response: String = "",
)

Example of request model:

data class OutGoingWebHookPayload(
   var transactionCode: String = "",
   var state: String = "",
   var paymentInstrument: String = "",
   var paymentSubInstrument: String ?= null,
   var currency: Currency = Currency(),
   var amount: BigDecimal = BigDecimal.ZERO,
   var cancelReason: String ?= null,
   var comment: String = "",
   var extraCustomerInfo: String = "",
)

data class Currency(
   var code: String = "",
   var name: String = "",
   var knownName: String = "",
   var serviceable: Boolean = false,
   var notServiceableMessage: String? = "",
   var decimalPrecision: Int = 0,
   var id: String = "",
   var lastUpdated: ZonedDateTime = ZonedDateTime.now(),
   var createdDate: ZonedDateTime = ZonedDateTime.now(),
   var dataStatus: String = "",
)

Encryption/Decryption in Other Languages

Clear Pending Webhooks

Steps to Clear Pending Webhooks for a Merchant.

1. Navigate to the Merchants section.
2. Go to the Merchant Details page.
3. Click on the Clear button where the red arrow is pointing.

View Pending Webhook calls

To view the pending webhooks for a merchant:

1. Go to the Merchants section.
2. Navigate to the Merchant Details page.
3. Check the Merchant Pending Webhooks count, which is highlighted in the red rectangle box.