3.41. Connecting Party Callbacks

General information

If Connecting Party specified a callback URL, Payment Gateway sends an HTTP GET message to the callback URL whenever transaction reaches final status, no matter if the result is approved, declined or other final status. This gives Connecting Party better control of how the transaction is processed, for example to add appropriate records to Connecting Party internal accounting system.

Warning

Connecting Party server needs to respond to this GET request with 200 OK status RFC, or else Payment Gateway will continue to send the callback 30 times for 14 days applying the progressive timeline.

Please remember, callbacks are guaranteed to report Connecting Party about transaction status. Connecting Party on their side must provide a means of preventing receiving the same callback twice – in case of network or other technical problems. It is recommended to check status, type, orderid and client_orderid to prevent duplication of transactions on Connecting Party side.

Callback URLs can be specified by Connecting Party in the following ways:

• By sending server_callback_url or notify_url in initial transaction request. If server_callback_url is sent, Connecting Party will receive a callback only for the initial transaction (ex. sale approved). If notify_url is sent instead, Connecting Party will receive a callback for the initial transaction (ex. sale approved) and for any new transaction types applied to the same transaction (ex. reversal, chargeback).
• By specifying the callback URL on endpoint level. Each transaction type can have it’s own callback URL.

Only the following ports are allowed in callback URL:

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

Customizable Callback URL

Simple callback URL contains all parameters listed in Callback Parameters. Customizable callback URL is a fully defined URL with all the parameters Connecting Party target page or script would require. Customizable URL allows Connecting Party to define own parameter names, whereas the actual parameters values are defined by use of macros with the following format ${parameter_name}. Thus pay.billblend.com substitutes respective parameter values into final customized URL before calling it. Available macros are listed in Callback Macros.

Example of simple callback URL:

https://connectingparty.com/sale_completed.php

Example of customized callback URL:

https://connectingparty.com/sale_completed.php?cardholder_name=${name}&tx_status=${status}&order_id=${merchant_order}

Callback Parameters

Note

The system automatically adds the following parameters to callback URL.

* – these parameters are not defined by default. Please contact tech support to include these fields in callback.

Callback Macros

Callback Request Example

https://connectingparty.com/api/integration/check/pay/server?token=some_token
&serial-number=b8e5b762-c116-407e-a591-82a458e1
&merchant_order=preauth_1171
&client_orderid=preauth_1171
&processor-tx-id=e0a0572f-2154-737c-8ea7-92410
&orderid=57792
&status=approved
&amount=1.50
&currency=EUR
&descriptor=%D0%90+%D0%94%D0%B5%D0%BD%%D0%B3%D0%B8+-+card+registration
&original-gate-descriptor=%D0%90+%D0%940%BD%D1%8C%D0%B3%D0%B8+-+card+registration&gate-partial-capture=enabled
&type=preauth
&name=CARDHOLDER+NAME
&card-exp-month=6
&card-exp-year=2024
&email=22701231%40example.com
&processor-rrn=21660934567
&approval-code=265470
&control=bbd11a020f6bsdkfgjh23e24def54991bfb63c5&last-four-digits=0214
&bin=220220&card-type=VISA
&phone=%2B71914454778
&bank-name=Rabobank
&card-hash-id=235479750
&card-country-alpha-three-code=RUS
&ips-src-payment-product-code=VISA
&ips-src-payment-product-name=VISA
&ips-src-payment-type-code=Unknown
&ips-src-payment-type-name=VISA+Unknown
&initial-amount=1.50
&transaction-date=2022-06-15+12%3A37%3A02+CEST

Callback to Status Parameters Mapping

Callback Signature Check Example on Java

You may see an example how to check the callback signature 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();
    }

}