Void

Purpose

Implements the Void transaction with a payment gateway.

Mandatory

No. However, Billing expects the Void method to be implemented by plugins that support tokenizination.

Input Parameters

An associative array that contains the following values:

Param name	Description	Type
`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
`payment_method`	Attributes of the previously saved payment method. This contains name-value pairs returned by the `ADD_NEW_METHOD` parameter.	array
`previous_transaction_data`	(Optional) Data saved in the previous transaction. This contains name-value pairs returned previously in the `TRANSACTION_DETAILS` array.	array
`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

{
    "config": {
        "3dsecure": "1",
        "enable_tokens": "1"    },
    "environment": {
        "lang": "en",
        "notify_url": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/70/notify",
        "return_url": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/70/callback",
        "return_url_3dsecure": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/70/3dsecure",
        "return_url_failed": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/70/fail/callback",
        "return_url_ok": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/70/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": 1000002,
        "type": 3,
        "vendor_id": 1,
        "is_corporate": false,
        "name": "PHILIP Huel, Nicolas",
        "lang": "en",
        "billing_fname": "Philip",
        "billing_mname": null,
        "billing_lname": "Hoeger",
        "billing_email": "philip.hoeger9934@ingrammicro.tld",
        "billing_phone": {
            "country_code": "1",
            "area_code": "314",
            "number": "8634391",
            "extention": null
        },
        "billing_fax": {
            "country_code": "1",
            "area_code": "314",
            "number": "8634391",
            "extention": null
        },
        "tax_ex_number": "XXXX01001",
        "address_address1": "575 Barfield Lane",
        "address_address2": null,
        "address_city": "Indianapolis",
        "address_state": "IN",
        "address_zip": "46254",
        "address_country": "us"    },
    "document_info": {
        "id": 51,
        "total": "1.00",
        "currency": "USD",
        "description": "Pre-authorization Charge"    },
    "payment_method": {
        "token": "19ea22d89478f23b8b5f84a85d5506d2",
        "paymethod_name": "**** **** **** 0860",
        "external_id": "893ba75be58109638633958abeabccb8",
        "initial_status": "OK",
        "exp_date": "7/2026"    },
    "previous_transaction_data": {
        "desc": "Success",
        "trans_id": "1641400860"    },
    "transaction_category": "C",
    "transaction_moto": true,
    "transaction_initiator": "MIT",
    "plugin": "Demo",
    "action": "Void",
    "ref_no": 70,
    "transaction_amount": "1.00",
    "currency_iso": "USD",
    "current_lang": "en",
    "client_ip": "10.194.250.249"}

Response

An associative array that contains the following keys:

Param name	Description	Type
`STATUS`	(Mandatory) The status of the method execution. Valid values for Void method are: `APPROVED`: The request is successfully processed and the payment gateway approved the transaction. `DECLINED`: The request is successfully processed and the payment gateway declined the transaction. `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. `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 the status message (String, optional), `vendor_message`: Contains text that will be displayed to a vendor (String, optional).	array
`TRANSACTION_DETAIL`	(Optional) The array that will be associated with the current transaction and will be represented back in its 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 display 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

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

Response example

Copy

{
    "STATUS": "APPROVED",
    "TRANSACTION_DETAILS": {
        "trans_id": "1641400865"    }
}

Example

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

Example

Copy

function Demo_Void( $params ) {
    if (!isset($params['previous_transaction_data'])) {
        throw new Exception('No previous transaction data');
    }

    return array(
        STATUS => STATUS_APPROVED,
        TRANSACTION_DETAILS => array(
            'trans_id' => _Demo_FakeTransactionId()
        )
    );
}

Void

Purpose

Mandatory

Input Parameters

Response

Example

See Also