Sell

Purpose

Implements the Sell transaction with a payment gateway.

Mandatory

Yes, for those plugins that use 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
`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": "0",
        "enable_tokens": "1"    },
    "environment": {
        "lang": "en",
        "notify_url": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/ProcessNotificationJsonPlugin/swep/action/notify/EActivityID/52/",
        "return_url": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/JsonRedirectPaymentOk/swep/action/notify/EActivityID/52/",
        "return_url_3dsecure": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/JsonCallback3D/swep/action/notify/EActivityID/52/",
        "return_url_failed": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/JsonRedirectPaymentFailed/swep/action/return/EActivityID/52/",
        "return_url_ok": "https://example.sandboxes.int.zone/bss-www/nologin/srv/BM/JsonRedirectPaymentOk/swep/action/return/EActivityID/52/",
        "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": 36,
        "total": "12.00",
        "currency": "USD",
        "description": "Payment for Order SO000013."    },
    "payment_method": {
        "token": "c88f6f3a875267486f4f6072bb226752",
        "paymethod_name": "**** **** **** 9359",
        "external_id": "d7ae3e102c5e8c3111b011882ce5fc2b",
        "initial_status": "OK",
        "exp_date": "12/2021"    },
    "transaction_category": "C",
    "transaction_moto": true,
    "transaction_initiator": "MIT",
    "plugin": "Demo",
    "action": "Sell",
    "ref_no": 52,
    "transaction_amount": "12.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 the Sell 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. `AUTHCALL`: The request is successfully processed but the payment gateway requires the Auth Code to be sent in the Capture request. `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 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": "1641367015"    }
}

Example

The Stripe plugin implements the Sell method. The example below shows how it was implemented:

Example

Copy

function Stripe_Sell($params) {
    Stripe_Trace('Sell', $params);
    $doc_info = $params['document_info'];
    $description = $doc_info['description'];
    $amount = $params['transaction_amount'];
    $currency = $params['currency_iso'];
    $precision = Stripe_GetCurrencyPrecision($currency);

    try {
        Stripe_SetApiKey($params);
        $paymentIntentParams = [
            'confirmation_method' => 'automatic',
            'amount' => $amount * $precision,
            'currency' => $currency,
            'description' => $description,
            'payment_method_types' => ['card'],
            'customer' => $params['payment_method']['customer_id'],
            'payment_method' => $params['payment_method']['payment_method_id'],
            'confirm' => true,
            'error_on_requires_action' => true,
        ];

        if ($params["transaction_initiator"] == "MIT") {
            if (isset($params["transaction_moto"]) && $params["transaction_moto"]) {
                $paymentIntentParams["payment_method_options"] = [
                    'card' => [ 'moto' => true ]
                ];
            } else {
                $paymentIntentParams["off_session"] = true;
            }
        }

        $intent = PaymentIntent::create($paymentIntentParams);

        if ($intent->status === 'succeeded') {
            return [
                STATUS => STATUS_APPROVED,
                TRANSACTION_DETAILS => [
                    "trans_id" => $intent->charges->data[0]['id']
                ]
            ];
        }

        return [
            STATUS => STATUS_DECLINED,
            TEXT => [
                'vendor_message' => pa_localized_string('request_failed'),
                'customer_message' => pa_localized_string('canceled')
            ]
        ];
    } catch (Base $e) {
        return Stripe_HandleException($e);
    }
}

Sell

Purpose

Mandatory

Input Parameters

Response

Example

See Also