CheckStatus

Purpose

Checks the transaction's current status on a payment gateway.

Mandatory

No.

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`	The 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": {
        "auth_code": "",
        "format": "json",
        "gateway_url": "https://demo-payment-gateway.com",
        "test_mode": "0"    },
    "environment": {
        "lang": "en",
        "notify_url": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/ProcessNotificationJsonPlugin/swep/action/notify/EActivityID/94/",
        "return_url": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/JsonRedirectPaymentOk/swep/action/notify/EActivityID/94/",
        "return_url_3dsecure": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/JsonCallback3D/swep/action/notify/EActivityID/94/",
        "return_url_failed": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/JsonRedirectPaymentFailed/swep/action/return/EActivityID/94/",
        "return_url_ok": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/JsonRedirectPaymentOk/swep/action/return/EActivityID/94/",
        "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": 76,
        "total": "5.00",
        "currency": "USD",
        "description": "Refund"    },
    "payment_method": {
        "token": "ef85e6c9c293c655898b5a60a5786e3a",
        "paymethod_name": "**** **** **** 5062",
        "external_id": "a5955ff876d79e48daa82361b97c2daa",
        "initial_status": "OK",
        "exp_date": "5/2025"    },
    "transaction_category": "C",
    "transaction_moto": true,
    "transaction_initiator": "MIT",
    "plugin": "Example",
    "action": "checkstatus",
    "ref_no": 94,
    "transaction_amount": "5.00",
    "currency_iso": "USD",
    "current_lang": "en",
    "client_ip": "10.194.251.101"}

Response

An associative array that contains the following keys:

Param name	Description	Type
`STATUS`	(Mandatory) The method execution status. Valid values for the CheckStatus 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. `FRAUD`: The request is successfully processed and the payment gateway declined the transaction due to a suspected fraud. `3DSECURE`: The request is successfully processed and the payment gateway requires a customer to be redirected to an Authentication page at the 3D Secure Gateway server. `PENDING`: The request is successfully processed, but the transaction 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 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 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 display it in the provider's UI. So, 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",
}

Example

The Stripe plugin implements the CheckStatus method. The example below shows how it is implemented:

Example

Copy

function Stripe_CheckStatus($params)
{
    Stripe_Trace('CheckStatus', $params);

    try {
        Stripe_SetApiKey($params);
        $charge = Charge::retrieve($params['previous_transaction_data']['trans_id']);
        $status = $charge['paid'] ? STATUS_APPROVED : STATUS_DECLINED;

        $response = [];
        $response[STATUS] = $status;

        if (isset($charge['failure_message'])) {
            $response[TEXT] = ['vendor_description' => $charge['failure_message']];
        }

        return $response;

    } catch (Base $e) {
        return Stripe_HandleException($e);
    }
}