Callback

Purpose

Processes callback data received from a payment gateway.

Mandatory

No.

Important: Officially, Callback is not Mandatory, meaning a plugin can be registered without implementing it. However, in practice, all plugin interaction scenarios— Modal, Redirect, Tokenizing, and 3D Secure—depend on the Callback method.

Input Parameters

An associative array that contains the following values:

Param name	Description	Type
`callback_params`	The parameters received from the payment gateway.	array
`config`	The plug-in configuration values saved in the Billing database.	array
`environment`	The Billing environment information.	Environment
`account_info`	The account's details.	AccountDetails
`vendor_info`	The vendor's details.	AccountDetails
`document_info`	The payment document description.	DocumentInfo
`transaction_category`	The transaction category for merchant-initiated payments (relevant and available only for `transaction_initiator` = MIT). Possible values are: `C`: for Unscheduled Credential on File payments, `R`: for recurring payments (payments at regular intervals).	string
`transaction_moto`	The parameter that defines whether it is the MOTO transaction. Possible values are: true: for MIT payments on behalf of a customer, `transaction_moto` is not sent: for CIT payments and recurring or renewing MIT payments.	boolean
`transaction_initiator`	The transaction initiator. Possible values are: `CIT`: for customer-initiated payments, `MIT`: for merchant-initiated payments. Note: For information on CIT and MIT definition conditions refer to the respective table in Supporting Mastercard and Visa Transaction Frameworks.	string
`ref_no`	The Billing transaction identifier.	integer
`transaction_amount`	The transaction amount.	double
`currency_iso`	The currency of the transaction amount in the ISO format (for example, USD or EUR).	string
`current_lang`	The current language.	string
`client_ip`	The IP from the client computer.	string

The example of input parameters is shown below as a JSON object:

Example of input parameters

Copy

{
    "callback_params": {
        "EActivityID": "18",
        "expires": "6/2024",
        "public_name": "**** **** **** 5578",
        "returnResult": "ok",
        "token": "3fc930b0309d5c9e3412ae9585ffa440",
        "txn_id": "1639745578"    },
    "config": {
        "auth_code": "421",
        "format": "json",
        "gateway_url": "https://plugin-gateway-url.com",
        "test_mode": "1"    },
    "environment": {
        "lang": "en",
        "notify_url": "https://example.sandboxes.int.zone/aps/2/resources/82699957-0fa8-44c4-a514-428434a7d3de/bss/redirect/18/notify",
        "return_url": "https://example.sandboxes.int.zone/aps/2/resources/82699957-0fa8-44c4-a514-428434a7d3de/bss/redirect/18/callback",
        "return_url_3dsecure": "https://example.sandboxes.int.zone/aps/2/resources/82699957-0fa8-44c4-a514-428434a7d3de/bss/redirect/18/3dsecure",
        "return_url_failed": "https://example.sandboxes.int.zone/aps/2/resources/82699957-0fa8-44c4-a514-428434a7d3de/bss/redirect/18/fail/callback",
        "return_url_ok": "https://example.sandboxes.int.zone/aps/2/resources/82699957-0fa8-44c4-a514-428434a7d3de/bss/redirect/18/ok/callback",
        "system_host": "bss.int.zone"    },
    "vendor_info": {
        "id": 1,
        "type": 0,
        "vendor_id": null,
        "is_corporate": true,
        "name": "ServicePro",
        "lang": "en",
        "admin_fname": "Charlie",
        "admin_mname": null,
        "admin_lname": "Root",
        "admin_email": "root@test.oss",
        "admin_phone": {
            "country_code": "1",
            "area_code": "408",
            "number": "4567890",
            "extention": null
        },
        "admin_fax": {
            "country_code": null,
            "area_code": null,
            "number": null,
            "extention": null
        },
        "billing_fname": "Charlie",
        "billing_mname": null,
        "billing_lname": "Root",
        "billing_email": "root@test.oss",
        "billing_phone": {
            "country_code": "1",
            "area_code": "408",
            "number": "4567890",
            "extention": null
        },
        "billing_fax": {
            "country_code": null,
            "area_code": null,
            "number": null,
            "extention": null
        },
        "technical_fname": "Charlie",
        "technical_mname": null,
        "technical_lname": "Root",
        "technical_email": "root@test.oss",
        "technical_phone": {
            "country_code": "1",
            "area_code": "408",
            "number": "4567890",
            "extention": null
        },
        "technical_fax": {
            "country_code": null,
            "area_code": null,
            "number": null,
            "extention": null
        },
        "tax_ex_number": null,
        "address_address1": "500 SW 39th Street, Suite 200",
        "address_address2": null,
        "address_city": "Renton",
        "address_state": "WA",
        "address_zip": "98057",
        "address_country": "us"    },
    "account_info": {
        "id": 1000001,
        "type": 3,
        "vendor_id": 1,
        "is_corporate": true,
        "name": "Hayes, Lindgr",
        "lang": "en",
        "admin_fname": "Derick",
        "admin_mname": null,
        "admin_lname": "Reilly",
        "admin_email": "sheldon.bosco5663@ingrammicro.tld",
        "admin_phone": {
            "country_code": "1",
            "area_code": "907",
            "number": "3935919",
            "extention": null
        },
        "admin_fax": {
            "country_code": "1",
            "area_code": "907",
            "number": "3935919",
            "extention": null
        },
        "billing_fname": "Derick",
        "billing_mname": null,
        "billing_lname": "Reilly",
        "billing_email": "sheldon.bosco5663@ingrammicro.tld",
        "billing_phone": {
            "country_code": "1",
            "area_code": "907",
            "number": "3935919",
            "extention": null
        },
        "billing_fax": {
            "country_code": "1",
            "area_code": "907",
            "number": "3935919",
            "extention": null
        },
        "technical_fname": "Derick",
        "technical_mname": null,
        "technical_lname": "Reilly",
        "technical_email": "sheldon.bosco5663@ingrammicro.tld",
        "technical_phone": {
            "country_code": "1",
            "area_code": "907",
            "number": "3935919",
            "extention": null
        },
        "technical_fax": {
            "country_code": "1",
            "area_code": "907",
            "number": "3935919",
            "extention": null
        },
        "tax_ex_number": null,
        "address_address1": "132 Blackwell Street",
        "address_address2": null,
        "address_city": "Shemya",
        "address_state": "AK",
        "address_zip": "99501",
        "address_country": "us"    },
    "document_info": {
        "id": 19,
        "total": "1.00",
        "currency": "USD",
        "description": "Pre-authorization Charge"    },
    "transaction_category": "C",
    "transaction_moto": true,
    "transaction_initiator": "MIT",
    "plugin": "Demo",
    "action": "Callback",
    "ref_no": 18,
    "transaction_amount": "1.00",
    "currency_iso": "USD",
    "current_lang": "en",
    "client_ip": "10.194.251.244"}

Response

An associative array that contains the following keys:

Param name	Description	Type
`STATUS`	(Mandatory) The method execution status. Valid values for the Callback method are: `APPROVED`: The request was successfully processed. `REDIRECT`: (v21.4 and later) The request is successfully processed and the customer is redirected to the payment gateway. `PENDING`: The request processing has the pending status in the Payment Gateway. The `NEXT_TRANSACTION_GAP` parameter may be used together with this status, so Billing can schedule the CheckStatus method call to verify whether the status is changed in the payment gateway. Refer to the `NEXT_TRANSACTION_GAP` parameter for details. `DECLINED`: The request processing failed. The reason can be sent in the `TEXT` parameter. `ERROR`: An error occurred while processing the request. The error reason can be sent in the `TEXT` parameter.	string
`TEXT`	(Optional) The array that contains the following parameters: `customer_message`: Contains text that will be displayed to a customer as a status message (String, optional). `vendor_message`: Contains text that will be displayed to a vendor (String, optional).	array
`REDIRECT_HASH`	(Mandatory when `STATUS` is `REDIRECT`) Provides information for the redirect. The parameters are: `url`: The URL where a customer is redirected (String, mandatory). `attrs`: Parameters and values that will be used for the redirect (Array, mandatory). `method`: The method used to pass the data: `GET`, `POST`. If not set, the `POST` method will be used (String, optional).	array
`TRANSACTION_DETAIL`	(Optional) The array that will be associated with the current transaction and will be represented back in an unchanged form as the value of the `previous_transaction_data` parameter at the next call of transaction processing methods of the plugin. Note: Billing looks up the `trans_id` parameter that identifies a transaction on the gateway side to show it in the provider's UI. We highly recommend that you use this parameter.	array
`NEXT_TRANSACTION_GAP`	(Optional) The delay, in seconds, to dispatch the CheckStatus method call. This parameter may be used when the `STATUS` parameter is `PENDING`. When Billing receives this parameter, it will schedule the CheckStatus method call event to be dispatched in `NEXT_TRANSACTION_GAP` seconds. It may be useful when the payment gateway expects API consumers to actively check a transaction status.	integer
`ADD_NEW_METHOD`	(Optional) When this array is returned in the `Callback` response, Billing tries to add a new payment method. For example, it creates a token after the redirect (for details, see Tokenizing a Payment Method). The parameters are: `paymethod_name`: The payment method name to be created and stored in Billing (String, mandatory). `exp_date`: The payment method expiration date. It is passed using the MM/YYYY format (String, optional). `external_id`: The ID created by the payment gateway. Synchronizing that ID with the payment method in Billing is a good practice and can help in a manual conciliation (String, optional). `initial_status`: The token initial status in Billing. Possible values are `OK` or `PENDING`. If not present, the `OK` value will be assumed (String, optional). Other custom name-value pairs are allowed. They will be stored and passed to the plugin with the next payment operation.	array
`NOTIFY_RESPONSE`	(Optional) The array that can produce a response on the Notify URL request. The parameters are: `body`: The HTTP response body (String, mandatory). `content_type`: The HTTP header that indicates the media type of the resource in the response body (available values are `text/plain, text/html, application/json)` (String, mandatory).

The example of a response is shown below as a JSON object:

Response example

Copy

{
    "STATUS": "APPROVED",
    "TEXT": {
        "vendor_message": "Success"    },
    "TRANSACTION_DETAILS": {
        "desc": "Success",
        "trans_id": "1639746155"    },
    "ADD_NEW_METHOD": {
        "token": "c1e1a46894acf4ac3ded8b0a84659f14",
        "external_id": "1639746155",
        "paymethod_name": "**** **** **** 6155",
        "external_id": "770a32fd0854c54854922a7340467733",
        "initial_status": "OK",
        "exp_date": "3/2026"    }
}

Example

The built-in Demo plugin implements the Callback method. The example below shows how this plugin implements it:

Example

Copy

function Demo_Callback( $params ) {
    $callback_params = $params['callback_params'];

    $result = $callback_params['returnResult'];
    $txn_id = $callback_params['txn_id'];

    switch ($result) {
        case 'ok' :
            $status = STATUS_APPROVED;
            $desc   = 'Success';

            if (isset($callback_params['token']) && isset($callback_params['public_name'])) {
                $new_method = array(
                    'token' => $callback_params['token'],
                    'paymethod_name' => $callback_params['public_name'],
                    // External ID is used to identify Payment Method
                    'external_id' => md5($callback_params['token']),
                    'initial_status' => PAYMETHOD_STATUS_OK
                    );
            }

            if (isset($new_method) && isset($callback_params['expires'])) {
                $new_method['exp_date'] = $callback_params['expires'];
            }

            break;

        case 'fail' :
            $status = STATUS_DECLINED;
            $desc   = 'Declined';
            break;

        default :
            $status = STATUS_ERROR;
            $desc   = "Unknown status '$result'";
            break;
    };

    $details['desc'] = $desc;
    $details['trans_id'] = $txn_id;

    $response = array(
        STATUS              => $status,
        TEXT                => array( 'vendor_message' => $desc ),
        TRANSACTION_DETAILS => $details
    );

    if (isset($new_method)) {
        $response[ADD_NEW_METHOD] = $new_method;
    }

    return $response;
}

Callback

Purpose

Mandatory

Input Parameters

Response

Example

See Also