Payment Gateway Support

XML Gateway API

XML Gateway API

The XML gateway API is a programming interface that resides on transaction servers which communicate directly to credit card processing networks. The programming interface requires that the merchant, or their web programming staff, be sufficiently knowledgeable in programming skills in any programming or object oriented scripting language. The XML Gateway API accepts the credit card purchasers information, and produces an authorization or decline directly from the merchant bank.

The XML Gateway API provides methods to perform the following operations: AUTH, SALE, SETTLE, CREDIT, VOID and QUERY. The information is passed via 128bit SSL https post in XML format. That post occurs in the background from the merchant's server. Thus the purchaser never leaves the merchant's website. The authorization information is returned in XML format with full error trapping and reporting to indicate the success or failure of the transaction.

General Requirements

What do I need to send to the XML Gateway?

<?xml version="1.0" encoding="UTF-8"?>
<TRANSACTION>
<FIELDS>

<FIELD KEY="merchant">transaction center id</FIELD> # assigned by gateway
<FIELD KEY="processor_id">processorID</FIELD> # assigned by gateway
<FIELD KEY="gateway_id">gatewayID</FIELD> # assigned by gateway
<FIELD KEY="operation_type">auth/sale</FIELD>
<FIELD KEY="order_id">MUST BE UNIQUE ASSIGNED</FIELD>
<FIELD KEY="total">(In US Dollars. Example 59.99 No $ signs.)</FIELD>
<FIELD KEY="card_name">(Visa, Amex, Discover or MasterCard)</FIELD>
<FIELD KEY="card_number">15|16 digit credit card number</FIELD>
<FIELD KEY="card_exp">MMYY</FIELD>
<FIELD KEY="cvv2">3 digit cvv2 code</FIELD> # not required
<FIELD KEY="owner_name">name</FIELD>
<FIELD KEY="owner_street">address</FIELD>
<FIELD KEY="owner_city">city</FIELD>
<FIELD KEY="owner_state">state AA</FIELD>
<FIELD KEY="owner_zip">zip</FIELD>
<FIELD KEY="owner_country">country AA</FIELD>
<FIELD KEY="owner_email">Email of customer </FIELD> # not required
<FIELD KEY="owner_phone">Phone of customer</FIELD> # not required
<FIELD KEY="recurring">0-no 1-yes</FIELD>
<FIELD KEY="recurring_type">Null if recurring =0</FIELD>
<FIELD KEY="remote_ip_address">Customer IP Address</FIELD> # not required

</FIELDS>
</TRANSACTION>

What is the response that I get back from the XML Gateway (for operation_type auth or sale)?

<?xml version="1.0" encoding="UTF-8"?>
<RESPONSE>
<FIELDS>

<FIELD KEY="status">0-error 1-success 2-declined</FIELD>
<FIELD KEY="auth_code">character code sent by the bank </FIELD>
<FIELD KEY="auth_response">message from the bank </FIELD>
<FIELD KEY="avs_code">avs code from the bank</FIELD>
<FIELD KEY="cvv2_code">cvv2 code from the bank</FIELD>
<FIELD KEY="order_id">echoed back from original post</FIELD>
<FIELD KEY="reference_number">returned for use with credits/voids/settles</FIELD>
<FIELD KEY="error">error text</FIELD>

</FIELDS>
</RESPONSE>

  • recurring_type options: Daily, weekly, biweekly, monthly, quarterly, semiannually, annually
  • order_id options: Only these characters are accepted: a-z, A-Z, 0-9, @, hyphen (-), space, comma (,), and a period (.).
    There is also a length restriction with a low limit of 1 and a max of 50 characters.
  • Operation Types:
    • Auth- Just gets the card authorized, it does not settle the transaction.
    • Sale- Authorizes the card and settles the transaction.
  • Status: If it is 0, the response will look like this:

    <FIELD KEY="status">0</FIELD>
    <FIELD KEY="auth_code"></FIELD>
    <FIELD KEY="auth_response"></FIELD>
    <FIELD KEY="avs_code"></FIELD>
    <FIELD KEY="cvv2_code"></FIELD>
    <FIELD KEY="order_id">WHATEVER WAS SENT IN</FIELD>
    <FIELD KEY="reference_number"></FIELD>
    <FIELD KEY="error">DESCRIPTIVE ERROR MESSAGE</FIELD>

    Notice most fields are blank when status = 0! If the status is a 1 or 2 then the fields will be field in with the appropriate responses
  • reference_number: This is the number used in later operations to reference specific transactions for credits, voids and settles.

Error XML Responses

Malformed fields or bad XML in all cases will be returned in the XML response defined for the operation type sent in with the error field defined. For operation types that cannot be induced from incoming fields, a generic XML response will come back with simply an error field defined with the reason for the failure.

Example Error:

<?xml version="1.0" encoding="UTF-8"?>
<RESPONSE>
<FIELDS>
<FIELD KEY="error">DESCRIPTIVE ERROR MESSAGE</FIELD>
</FIELDS>
</RESPONSE>

For a more detailed description on how to setup the XML Gateway API, and to view PERL and ASP script samples, view this document.

Article written by Stacey D.