3.40. 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 gate.goldenapple.com.cy 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

The system automatically adds the following parameters to callback URL.

Callback Parameter	Description
status	See Status List for details.
merchant_order	Connecting Party order identifier, same as client_orderid.
client_orderid	Connecting Party order identifier.
orderid	gate.goldenapple.com.cy transaction id.
type	Transaction type, sale reversal chargeback
amount	Actual transaction amount. This value can be changed during the transaction flow.
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	Payer’s email.
approval-code	Authorization approval code, if any.
last-four-digits	Last four digits of Payer’s credit card number.
bin	Bank BIN of Payer’s credit card.
card-type	Type of Payer’s credit card (VISA, MASTERCARD, etc).
phone	Payer’s phone number.
bank-name	Payer’s 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 chargeback or fraud operation.
processor-rrn	Bank Retrieval Reference Number.
comment	Comment in case of Return transaction
rapida-balance	Current balance for Connecting Party registered in Rapida system (only if balance check active)
control	Checksum is used to ensure that it is gate.goldenapple.com.cy (and not a fraudster) that initiates the callback to Connecting Party. 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.
merchantdata	The value passed by Connecting Party in initial request.
serial-number	Serial number of the request.
processor-tx-id	Transaction id set by processor.
processor-auth-credit-code	Reserved
card-hash-id	Unique hash of the particular card, does not change.
verified-3d-status	Will return AUTHENTICATED if a transaction was approved by 3DS.
processor-credit-rrn	Retrieval Reference 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).
card-country-alpha-three-code	Three letter country code of source card issuer. See Card Country Codes for details.
destination-card-country-alpha-three-code	Three letter country code of destination card issuer. See Card Country Codes for details.
initial-amount	Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow.
seller-commission	Total commission for processed transaction.
acquirer-commission	Acquirer commission for processed transaction.
exchange-rate	Basic exchange rate for currency conversion.
effective-exchange-rate	Actual exchange rate, applied during currency conversion.
orig-amount	Contains the original request amount if it was converted on auxiliary endpoint in Parallel form integration.
orig-currency	Contains the original request currency if it was converted on auxiliary endpoint in Parallel form integration.

Callback Macros

gate.goldenapple.com.cy Callback Macros name	Description
${status}	Transaction status, ex. approved, declined, processing, etc.
${merchant_order}	Connecting Party order identifier, same as client_orderid.
${orderid}	gate.goldenapple.com.cy transaction id.
${type}	Transaction type, ex. sale, return, chargeback, etc.
${amount}	Transaction amount.
${descriptor}	Payment descriptor of the gate through which the transaction has been processed.
${error_message}	Error message: when ${status} is declined.
${name}	Cardholder Name.
${email}	Payer’s email.
${last-four-digits}	Last four digits of Payer’s credit card number.
${bin}	Bank BIN of Payer’s credit card.
${card-type}	Type of Payer’s 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 chargeback or fraud operation.
${processor-rrn}	Bank Retrieval Reference Number.
${approval-code}	Bank approval code.
${comment}	Comment in case of Return transaction.
${rapida-balance}	Current balance for Connecting Party registered in Rapida system (only if balance check active).
${control}	Checksum is used to ensure that it is gate.goldenapple.com.cy (and not a fraudster) that initiates the callback to Connecting Party. 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.
${merchantdata}	The value passed by Connecting Party in initial request.

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 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
first-name	first-name
last-name	last-name
country	country
state	state
city	city
zip_code	zip_code
address1	address1
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
purpose	purpose
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
original-gate-descriptor	original-gate-descriptor
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
initial-amount	initial-amount
seller-commission	seller-commission
acquirer-commission	acquirer-commission
exchange-rate	exchange-rate
effective-exchange-rate	effective-exchange-rate
card-country-alpha-three-code	card-country-alpha-three-code
destination-card-country-alpha-three-code	destination-card-country-alpha-three-code

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();
    }

}