2.1. Merchant Callbacks

When ENDPOINT is created for Merchant’s website callback URLs might be defined for any type of transaction type and transaction status.

These callback URLs will be called when the transaction is completed, whether approved, declined or reaching error or unknown state. This gives a Merchant better control how the transaction is processed on Merchant’s side, for example to add appropriate records to Merchant’s internal accounting system.

Please remember, callbacks are guaranteed to report merchant about transaction status. Merchants on their side must provide a means of preventing receiving the same callback twice - in case of network or other technical problems.

2.1.1. Callback simple URL

If you want to make sure that the customer has paid for the item, you should specify a callback URL. If you do, SolidPayments sends an HTTP GET message to the callback URL whenever a purchase completed, no metter if the result is approved or declined. Your server needs to answer this GET message 200 OK status RFC, or else SolidPayments will continue to send the callback 30 times for 14 days applying the progressive timeline. Simple form of Sale or Return callback is just an URL to Merchant’s target page or script without any parameters, for example https://www.i-cool-merchant.com/sale.php. You can use only following ports in callback URL:

  • for HTTP 80, 8080
  • for HTTPS 443, 8443

In this case the system automatically adds the following parameters to callback URL.

Sale, Return Callback Parameters

SolidPayments Callback Parameter Description
status See Status List for details.
merchant_order Merchant order identifier, client_orderid
client_orderid Merchant order identifier
orderid SolidPayments transaction id
type Transaction type, sale reversal chargeback
amount Transaction amount
currency Transaction currency
descriptor Payment descriptor of the gate through which the transaction has been processed.
error_code Error Code
error_message Error Message
name Cardholder Name
email Customer’s email
approval-code Authorization approval code, if any
last-four-digits Last four digits of customer credit card number.
bin Bank BIN of customer credit card.
card-type Type of customer credit card (VISA, MASTERCARD, etc).
phone Customer phone number.
bank-name Customer bank name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
gate-partial-reversal Processing gate support partial reversal (enabled or disabled).
gate-partial-capture Processing gate support partial capture (enabled or disabled).
reason-code Reason code for chargebak or fraud operation.
processor-rrn Bank Receiver Registration Number.
comment Comment in case of Return transaction
rapida-balance Current balance for merchants registered in Rapida system (only if balance check active)
control Checksum is used to ensure that it is SolidPayments (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation status + orderid + merchant_order + merchant_control. The callback script MUST check this parameter by comparing it to SHA-1 checksum of the above concatenation. See Callback authorization through control parameter for more details about generating control checksum.
merchantdata Reserved
serial-number Serial number of the request.
processor-tx-id Transaction id set by processor.
processor-auth-credit-code Reserved
card-hash-id Unique identifier of card.
verified-3d-status Will return AUTHENTICATED if a transaction was approved by 3D.
processor-credit-rrn Reference Retrieval Number set by acquirer.
processor-credit-arn Acquirer card reference number for credit card.
processor-debit-arn Acquirer card reference number for debit card.
eci Electronic Commerce Indicator (Visa).
ips-src-payment-product-code Code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-product-name Decrypted code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-code Type of card code set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-name Decrypted code for type of card set by multinational financial service. (Visa/Mastercard)
initial-amount Amount, set in initiating transaction, without any fees or commissions.

2.1.2. Sale, Return, Chargeback customizable callback URL

Customizable callback URL is a fully defined URL with all the parameters Merchant’s target page or script would require. Customizable URL allows defining Merchant’s own parameter names, whereas the actual parameters values are defined by use of macros with the following format ${parameter_name}. Thus SolidPayments substitutes respective parameter values into final customized URL before calling it.

Example:

https://www.i-cool-merchant.com/sale_completed.php?cardholder_name= ${name}&tx_status=${status}&order_id=${merchant_order}

Sale, Return Callback Macros

SolidPayments Callback Macros name Description
${status} Transaction status, approved declined processing
${merchant_order} Merchant order identifier, client_orderid
${orderid} SolidPayments transaction id
${type} Transaction type, sale return chargeback
${amount} Transaction amount
${descriptor} Payment descriptor of the gate through which the transaction has been processed.
${error_message} Error message: when ${status} meaning declined
${name} Cardholder Name
${email} Customer’s email
${last-four-digits} Last four digits of customer credit card number.
${bin} Bank BIN of customer credit card.
${card-type} Type of customer credit card (VISA, MASTERCARD, etc).
${card-exp-month} Card expiration month.
${card-exp-year} Card expiration year.
${gate-partial-reversal} Processing gate support partial reversal (enabled or disabled).
${gate-partial-capture} Processing gate support partial capture (enabled or disabled).
${reason-code} Reason code for chargebak or fraud operation.
${processor-rrn} Bank Receiver Registration Number.
${approval-code} Bank approval code.
${comment} Comment in case of Return transaction
${rapida-balance} Current balance for merchants registered in Rapida system (only if balance check active)
${control} Checksum is used to ensure that it is SolidPayments (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation status + orderid + merchant_order + merchant_control. The callback script MUST check this parameter by comparing it to SHA-1 checksum of the above concatenation. See Callback authorization through control parameter for more details about generating control checksum.
${merchantdata} Reserved

2.1.3. Callback authorization through control parameter

The checksum is used to ensure that the callback is sent to the merchant by SolidPayments, and not by a fraudster. WARNING! If Merchant does not check the “control” parameter in the callback script, a fraudster might use the callback URL to carry out fraudulent activities on the Merchant’s system. This SHA-1 checksum (the “control” parameter) is created by concatenation of the parameters’ values in the following order:

  • status
  • orderid
  • merchant_order
  • merchant_control_key

The complete string example may look as follows:

approved123invoice-1AF4B5DE6-3468-424C-A922-C1DAD7CB4509

Encrypt the string using SHA-1 algorithm. The resultant string yields the “control” parameter which is required for authorizing the callback. For the example the “control” above will take the following value:

5bc8ee48f9ba37c0fd1e0b052a9bc105c6df87e1

2.1.4. Callback to Status Parameters Mapping

The following table contains a correspondence between callback parameters and status response fields.

Callback parameter Name Status parameter Name
amount amount
approval-code approval-code
bin bin
card-type card-type
last-four-digits last-four-digits
bank-name bank-name
name name
card-exp-month card-exp-month
card-exp-year card-exp-year
client_orderid merchant-order-id
comment comment
descriptor descriptor
dest-bin dest-bin
dest-card-type dest-card-type
dest-last-four-digits dest-last-four-digits
dest-bank-name dest-bank-name
email email
error_code error-code
error_message error-message
gate-partial-capture gate-partial-capture
gate-partial-reversal gate-partial-reversal
loyalty-balance loyalty-balance
loyalty-bonus loyalty-bonus
loyalty-message loyalty-message
loyalty-program loyalty-program
merchant_order merchant-order-id
merchantdata merchantdata
orderid paynet-order-id
phone phone
processor-rrn processor-rrn
processor-tx-id processor-tx-id
rapida-balance rapida-balance
reason-code reason-code
serial-number serial-number
status status
type transaction-type

2.1.5. Callback Signature check example on Java

You may see an example how to check the callback siganture using JAVA programming language below:

import org.junit.Test;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

import static org.junit.Assert.assertEquals;

public class TestCallbackSignatureExampleTest {

    @Test
    public void test() {
        String digest3 = calculateCallbackSignature("approved", 123, "invoice-1", "AF4B5DE6-3468-424C-A922-C1DAD7CB4509");
        assertEquals("5bc8ee48f9ba37c0fd1e0b052a9bc105c6df87e1", digest3);
    }

    public String calculateCallbackSignature(String aTransactionStatus, long aOrderId, String aMerchantOrderId, String aMerchantControlKey) {
        String text   = aTransactionStatus + aOrderId + aMerchantOrderId + aMerchantControlKey;
        byte[] buffer = text.getBytes(StandardCharsets.UTF_8);
        byte[] shaSum = sha(buffer);
        return toHexString(shaSum);
    }

    /**
    * Calculates the SHA-1 digest and returns the value as a <code>byte[]</code>.
    *
    * @param data
    *            Data to digest
    * @return SHA-1 digest
    */
    private static byte[] sha(byte[] data) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA");
            return digest.digest(data);
        } catch (NoSuchAlgorithmException e) {
           throw new IllegalStateException("Couldn't calculate SHA-1 digest", e);
        }
    }

    /**
     * Converts bytes to hex string
     */
    private static String toHexString(byte[] data) {
        StringBuilder sb = new StringBuilder();
        for (byte b : data) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) {
                sb.append('0');
            }
            sb.append(hex);
        }
        return sb.toString();
    }

}