{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Merchant Gateway","description":"Developer documentation for the WHMCS API — the","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"merchant-gateway","__idx":0},"children":["Merchant Gateway"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow the steps below to create a third party gateway module."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Merchant Gateway is one where a customer enters credit card details in WHMCS. The payment processes in the background. This can also include 3D Secure when the user leaves your site. Examples include PayPal Pro, Authorize.net, and AIM."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementation-guide","__idx":1},"children":["Implementation guide"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Delete the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yourmodulename_link"]}," function from the module template since this is only required for ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payment-gateways/third-party-gateway","title":"Third Party Gateways"},"children":["Third Party Gateway"]}," modules."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter the gateway-specific code for processing the payment capture into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yourmodulename_capture"]}," function. Typically, this takes the format of an HTTP/Curl request to the gateway provider's API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the gateway supports 3D Secure (Verified by Visa or MasterCard Secure Code) refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payment-gateways/3d-secure","title":"3D Secure Process"},"children":["3D Secure"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If your payment gateway supports refunds, implement support for ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payment-gateways/refunds","title":"Refunding Transactions"},"children":["Refunds"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"variables","__idx":2},"children":["Variables"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following parameters are passed to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_capture"]}," function along with all ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payment-gateways/configuration","title":"Configuration Parameters"},"children":["defined configuration parameters"]}," and their values."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["invoiceid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoice ID number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Description (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Company Name - Invoice #xxx"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["amount"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["float"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["xxx.xx"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["currency"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Currency code (for example, GBP or USD)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["cardtype"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card type (for example, Visa or MasterCard)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["cardnum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["cardexp"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card expiry date (format: MMYY)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["cardstart"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card start date (format: MMYY)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["cardissuenum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card issue number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["cccvv"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only available for card holder present initiated payment attempts."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["clientdetails"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An array of client details that includes the following indices: firstname, lastname, email, address1, address2, city, state, postcode, country (ISO code), model (an instance of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<a href=\"https://classdocs.whmcs.com/\">WHMCS/User/Client</a>"]},"), and phonenumber."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["companyname"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Company Name"]}," setting in WHMCS."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["systemurl"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The URL to the client area of the WHMCS installation."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response","__idx":3},"children":["Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following return parameters are supported."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["status"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One of either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["declinereason"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The reason why a transaction was declined."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["transid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Transaction ID returned by the payment gateway."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["fee"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["float"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(Optional) The transaction fee returned by the payment gateway."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["rawdata"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string or array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The raw data returned by the payment gateway for logging to the gateway log to aid in debugging."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["gatewayid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payment-gateways/tokenised-remote-storage","title":"Tokenised Remote Storage"},"children":["Tokenised Remote Storage"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-return","__idx":4},"children":["Example Return"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The capture function should always return an array containing information about the transaction attempt. This should take the following format:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"return array(\n    'status' => 'success',\n    'rawdata' => $responseData,\n    'transid' => $transactionId,\n    'fee' => $feeAmount,\n);\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a successful capture, the status should be returned as the string ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For payments that are pending and do not require an immediate payment in WHMCS, the status should be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For anything else, return a status that indicates the reason for failure. Common failure response status values include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The raw data you return will be recorded to the gateway log to aid in debugging. It can accept either a string or an array."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"simple-example","__idx":5},"children":["Simple Example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below is a demonstration of a capture function that submits a payment capture request and receives a JSON response. For a more complete example, please refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/WHMCS/sample-merchant-gateway","title":"Sample Merchant Gateway module on GitHub"},"children":["Sample Merchant Gateway module on GitHub"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"function yourmodulename_capture($params) {\n\n    $postfields = [\n        'invoiceid' => $params['invoiceid'],\n        'amount' => $params['amount'],\n        'currency' => $params['currency'],\n        'cardnumber' => $params['cardnum'],\n        'cardexpiry' => $params['cardexp'],\n        'cardcvv' => $params['cccvv'],\n        'card_holder_name' => $params['clientdetails']['firstname']\n            . ' - ' . $params['clientdetails']['lastname'],\n        'card_address' => [\n            'address_line_1' => $params['clientdetails']['address1'],\n            'city' => $params['clientdetails']['city'],\n            'state' => $params['clientdetails']['state'],\n            'postcode' => $params['clientdetails']['postcode'],\n            'country' => $params['clientdetails']['country'],\n        ],\n    ];\n\n    $ch = curl_init();\n    curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/api/capture');\n    curl_setopt($ch, CURLOPT_POST, 1);\n    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postfields));\n    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);\n    $response = curl_exec($ch);\n    curl_close($ch);\n\n    $data = json_decode($response);\n\n    if ($data->success == 1) {\n        $return = [\n            'status' => 'success',\n            'transid' => $data->transaction_id,\n            'fee' => $data->fee,\n            'rawdata' => $data,\n        ];\n    } else {\n        $return = [\n            'status' => 'declined',\n            'declinereason' => $data->decline_reason,\n            'rawdata' => $data,\n        ];\n    }\n    return $return;\n}\n"},"children":[]}]},"headings":[{"value":"Merchant Gateway","id":"merchant-gateway","depth":1},{"value":"Implementation guide","id":"implementation-guide","depth":2},{"value":"Variables","id":"variables","depth":2},{"value":"Response","id":"response","depth":2},{"value":"Example Return","id":"example-return","depth":3},{"value":"Simple Example","id":"simple-example","depth":2}],"frontmatter":{"title":"Merchant Gateway","seo":{"title":"Merchant Gateway"}},"lastModified":"2026-08-03T17:00:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/payment-gateways/merchant-gateway","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}