Signature-Based Authentication

To secure API communications, a digital signature is created using an RSA-2048 private key that is generated by the Payment Gateway. From this private key, a corresponding public key is derived. You must register this public key with the Payment Gateway, which then uses it to verify the authenticity of the signature on your API requests.

Here’s how we do it in simple terms:

• Private Key Generation: The Payment Gateway creates a secret RSA-2048 private key. This private key is used to generate a digital signature for your API requests.

• Public Key Creation: A matching public key is then generated from the private key. Unlike the private key, the public key can be shared.

• Registration:: You need to send this public key to the Payment Gateway so that it can register it.

• Verification: When you send an API request, the Payment Gateway uses the registered public key to verify the digital signature. This process ensures that the request is genuine and hasn’t been tampered with.

Example of generating a private key and converting it to DER format:

openssl genpkey -out rsakey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048
openssl rsa -in rsakey.pem -inform pem -out rsakey.der -outform der

Example of generating a public key based on private key in DER format:

openssl rsa -in rsakey.der -inform der -pubout -outform der -out rsapubkey.der

The signature must be passed in the HTTP request header with the name X-Signature, and the signature data must be encoded in Base64 format.

Signature String Format

The concatenation of request parameter strings is used as the data to be signed, converted to a byte representation using UTF-8 encoding. If the parameter value is missing or equals null, the - character is added to the string. The | character should be used as a separator between values.

Parameters should be concatenated in a strict order, also we should give attention to the following points:

• The amount must have the number of digits after decimal point corresponding to the currency of the operation, for example if the currency is Iraqi dinar then the number of digits after the decimal point should be 3 digits.
• The requestId parameter is always required for authentication by signature for each operation in the payment gateway.

Example of formatting a signature string

With the following payment creation request /payment for the terminalId = 012345:

{
  "requestId": "6b3d1423-644e-4ec7-92dd-b837e62294e4",
  "amount": 10,
  "withoutAuthenticate": true,
  "currency": "IQD",
  "paymentData": {
    "paymentType": "CARD",
    "pan": null,
    "expDate": "2505",
    "cvv": "000",
    "cardHolder": "JOHN DOE"
  }
}

The string for forming the signature will look like this:

012345|6b3d1423-644e-4ec7-92dd-b837e62294e4|10.000|IQD|true|-|-|-

The set of parameters for each payment operation

Depending on the type of operation, a different set of parameters is used to generate the signature, keep in mind, always follow the strict order of the parameters when concatenating the string:

createPayment /payment

• terminalId
• requestId
• amount
• currency
• withoutAuthenticate
• recurrent
• paymentToken

getPaymentStatus /payment/{paymentId}/status

• terminalId
• requestId
• paymentId

refundPayment /payment/{paymentId}/refund

• terminalId
• requestId
• amount
• paymentId

cancelPayment /payment/{paymentId}/cancel

• terminalId
• requestId
• amount
• paymentId

cancelPaymentByRequest /payment/cancel/by/request/{paymentRequestId}

• terminalId
• requestId
• amount
• paymentRequestId

refundPaymentByRequest /payment/refund/by/request/{paymentRequestId}

• terminalId
• requestId
• amount
• paymentRequestId

getPaymentStatusByRequest /payment/status/by/request/{paymentRequestId}

• terminalId
• requestId
• paymentRequestId