Auth

Purpose

Implements the Auth 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`	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": {
        "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/25/notify",
        "return_url": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/25/callback",
        "return_url_3dsecure": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/25/3dsecure",
        "return_url_failed": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/25/fail/callback",
        "return_url_ok": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/25/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": "Shields-Hilpe",
        "lang": "en",
        "admin_fname": "Yolando",
        "admin_mname": null,
        "admin_lname": "Upton",
        "admin_email": "misty.dietrich8864@ingrammicro.tld",
        "admin_phone": {
            "country_code": "1",
            "area_code": "704",
            "number": "7002528",
            "extention": null
        },
        "admin_fax": {
            "country_code": "1",
            "area_code": "704",
            "number": "7002528",
            "extention": null
        },
        "billing_fname": "Yolando",
        "billing_mname": null,
        "billing_lname": "Upton",
        "billing_email": "misty.dietrich8864@ingrammicro.tld",
        "billing_phone": {
            "country_code": "1",
            "area_code": "704",
            "number": "7002528",
            "extention": null
        },
        "billing_fax": {
            "country_code": "1",
            "area_code": "704",
            "number": "7002528",
            "extention": null
        },
        "technical_fname": "Yolando",
        "technical_mname": null,
        "technical_lname": "Upton",
        "technical_email": "misty.dietrich8864@ingrammicro.tld",
        "technical_phone": {
            "country_code": "1",
            "area_code": "704",
            "number": "7002528",
            "extention": null
        },
        "technical_fax": {
            "country_code": "1",
            "area_code": "704",
            "number": "7002528",
            "extention": null
        },
        "tax_ex_number": null,
        "address_address1": "1975 Snyder Avenue",
        "address_address2": null,
        "address_city": "Charlotte",
        "address_state": "NC",
        "address_zip": "28202",
        "address_country": "us"    },
    "document_info": {
        "id": 20,
        "total": "12.00",
        "currency": "USD",
        "description": "Payment for Order SO000006."    },
    "payment_method": [],
    "transaction_category": "C",
    "transaction_moto": true,
    "transaction_initiator": "MIT",
    "plugin": "Demo",
    "action": "Auth",
    "ref_no": 25,
    "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 Auth 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 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 a status message (String, optional), `vendor_message`: Contains text that will be displayed to a vendor (String, optional).	array
`REDIRECT_HASH`	(Mandatory) 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 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 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 with the 3DSECURE status is shown below as a JSON object:

3DSECURE response example

Copy

{
    "STATUS": "3DSECURE",
    "REDIRECT_HASH": {
        "url": "https://demo-payment-gateway.com/3dsecure.php",
        "method": "POST",
        "attrs": {
            "PaReq": "700b9660219f34f304a583296a7771bd",
            "TermUrl": "https://example.sandboxes.int.zone/aps/2/resources/0d0fffb6-26df-4274-8843-c6ceecebf181/bss/redirect/29/3dsecure",
            "amount": "12.00",
            "currency": "USD"        }
    }
}

The example of a response with the APPROVED status is shown below as a JSON object:

APPROVED response example

Copy

{
    " STATUS ": " APPROVED ",
    " TRANSACTION_DETAILS ": {
        " trans_id ": "1641305320",
        " PaRes ": "CE099D7E208DC921E259B48AADEF36C1",
        " Enrolled ": "Y"    }
}

Example

The built-in Demo plugin supports the 3D Secure flow, therefore it implements the Auth method. The example below shows how this plugin implements the Auth method:

Example

Copy

function Demo_Auth( $params ) {
        if (!isset($params['payment_method'])) {
                return Demo_Redirect($params);
        }

        if ( !$params['config']['3dsecure'] ) {
                return array(
                        STATUS => STATUS_APPROVED,
                        TRANSACTION_DETAILS => array(
                                'trans_id' => _Demo_FakeTransactionId()
                        )
                );
        }

        if (isset($params['previous_transaction_data'])) {

                $result = array();
                if ($params['previous_transaction_data']['Enrolled'] === 'Y') {
                        $result[STATUS] = STATUS_APPROVED;
                } else {
                        $result[STATUS] = STATUS_DECLINED;
                        $result[TEXT] = array(
                                'vendor_message'   => 'Rejected by 3D Secure',
                                'customer_message' => 'Rejected by 3D Secure'
                        );
                }

                $result[TRANSACTION_DETAILS] = array(
                        'trans_id' => _Demo_FakeTransactionId(),
                        'PaRes'    => $params['previous_transaction_data']['PaRes'],
                        'Enrolled' => $params['previous_transaction_data']['Enrolled']
                );

                return $result;
        }

        return array(
                STATUS => STATUS_3DSECURE,
                REDIRECT_HASH => array(
                        'url' => 'https://demo-payment-gateway.com/3dsecure.php',
                        'method' => 'POST',
                        'attrs' => array(
                                'PaReq'    => md5( (string) time() ),
                                'TermUrl'  => $params['environment']['return_url_3dsecure'],
                                'amount'   => $params['transaction_amount'],
                                'currency' => $params['currency_iso'],
                        )
                )
        );
}

Auth

Purpose

Mandatory

Input Parameters

Response

Example

See Also