Capture

Purpose

Implements the Capture transaction with a payment gateway.

Mandatory

Yes, if the plugin supports 3D Secure.

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/41/notify",
        "return_url": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/41/callback",
        "return_url_3dsecure": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/41/3dsecure",
        "return_url_failed": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/41/fail/callback",
        "return_url_ok": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/41/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": 1000003,
        "type": 3,
        "vendor_id": 1,
        "is_corporate": true,
        "name": "Test",
        "lang": "en",
        "admin_fname": "Test",
        "admin_mname": null,
        "admin_lname": "Test",
        "admin_email": "test@test.com",
        "admin_phone": {
            "country_code": "1",
            "area_code": "122",
            "number": "1222323",
            "extention": null
        },
        "admin_fax": {
            "country_code": null,
            "area_code": null,
            "number": null,
            "extention": null
        },
        "billing_fname": "Test",
        "billing_mname": null,
        "billing_lname": "Test",
        "billing_email": "test@test.com",
        "billing_phone": {
            "country_code": "1",
            "area_code": "122",
            "number": "1222323",
            "extention": null
        },
        "billing_fax": {
            "country_code": null,
            "area_code": null,
            "number": null,
            "extention": null
        },
        "technical_fname": "Test",
        "technical_mname": null,
        "technical_lname": "Test",
        "technical_email": "test@test.com",
        "technical_phone": {
            "country_code": "1",
            "area_code": "122",
            "number": "1222323",
            "extention": null
        },
        "technical_fax": {
            "country_code": null,
            "area_code": null,
            "number": null,
            "extention": null
        },
        "tax_ex_number": null,
        "address_address1": "sdf",
        "address_address2": null,
        "address_city": "Moscow",
        "address_state": "MOW",
        "address_zip": "12333",
        "address_country": "ru"    },
    "document_info": {
        "id": 27,
        "total": "12.00",
        "currency": "USD",
        "description": "Payment for Order SO000009."    },
    "payment_method": [],
    "previous_transaction_data": {
        "trans_id": "1641310376",
        "PaRes": "1165af9s8d4f61",
        "Enrolled": "Y"    },
    "transaction_category": "C",
    "transaction_moto": true,
    "transaction_initiator": "MIT",
    "plugin": "Demo",
    "action": "Capture",
    "ref_no": 41,
    "transaction_amount": "12.00",
    "currency_iso": "USD",
    "current_lang": "en",
    "client_ip": "10.194.250.240"}

Response

An associative array that contains the following keys:

Param name	Description	Type
`STATUS`	(Mandatory) The method execution status. Valid values for the Capture 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.	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
`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. 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": "PENDING",
    "TRANSACTION_DETAILS": {
        "trans_id": "1641310376",
        "param": "myParam"    },
    "NEXT_TRANSACTION_GAP": 5
}

Example

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

Example

Copy

function Demo_Capture( $params ) {
    $transaction_result = array(
        STATUS => STATUS_APPROVED,
        TRANSACTION_DETAILS => array(
            'trans_id' => _Demo_FakeTransactionId()
        )
    );
    $is_3dsecure = $params['config']['3dsecure'];
    if ($is_3dsecure === '1') {
        $transaction_result = array(
            STATUS => STATUS_PENDING,
            TRANSACTION_DETAILS => array(
                'trans_id' => _Demo_FakeTransactionId(),
                'param' => 'myParam'
            ),
            'NEXT_TRANSACTION_GAP' => 5
        );
    }

    return $transaction_result;
}

Capture

Purpose

Mandatory

Input Parameters

Response

Example

See Also