XML API

XML API integration is ideal for businesses that want to:

  • Completely control the checkout process.

  • Directly integrate with Converge.

  • Collect payment data using their own servers and pass that information to Converge for processing.

important

In XML API, you must include system fields marked as required. In addition, you may pass custom created fields and any other fields you would like to be stored with the transaction. Example: ssl_description, ssl_merchant_txn_id or ssl_invoice

note

Support for GET Method is deprecated for Process.do and ProcessXML.do and should not be used to post transaction requests to Converge.

This list provides an overview of the XML API integration method:

  • Ease of Integration: Hard
  • Service Provider PCI: PCI Level 1
  • Merchant PCI DSS Self-Assessment Questionnaire (SAQ) Type: SAQ D
  • Customization: Extensive
  • Most Suited for These Market Segments:
    • Retail
    • Restaurant/Service
    • Mail Order / Telephone Order
    • eCommerce
  • Most Applicable To These Transactions
    • Card Present – Hand-Keyed Transactions
    • Card Present – Swiped Transactions
    • Card Present – EMV Transactions
    • Card Not Present – eCommerce Transactions
    • Card Not Present – Back Office/MOTO Transactions

note

For card-present transactions, we strongly recommend reviewing the capabilities before starting a direct integration with Converge.

important

PCI requirements for Integrated Partners:

  • If a partner has access to payment card data, one is required to validate PCI compliance as a PCI Level 1 Service Provider annually. This requires the submission of a Report on Compliance (ROC) based on an on-site audit completed by a Qualified Security Assessor (QSA) before processing.
  • Subsequently, Card Brand registration is also required. PCI validation must be completed and documentation provided in order to execute the registration process with each card brand network annually.

Demo Endpoint:  https://api.demo.convergepay.com/VirtualMerchantDemo/processxml.do

Production Endpoint:  https://api.convergepay.com/VirtualMerchant/processxml.do

Implementation Guidelines

Converge doesn’t expect a fully validated XML document, but an XML-formatted request assigned to URL encoded variables called xmldata. Only the Converge-specific elements for the transaction itself are supported.

note

Make sure you include xmldata= with all xml api requests to Converge.

Here is a valid example with which xmldata= is included with any API request.

xmldata=
<txn>
<ssl_merchant_id>my_merchant_id</ssl_merchant_id>
<ssl_user_id>my_user_id</ssl_user_id>
<ssl_pin>my_pin</ssl_pin>
....
</txn>

XML has a special set of characters that cannot be used in normal XML strings. Special characters must be URL encoded to avoid problems.

For example, this XML string is invalid:

<ssl_company>A & B Company</ssl_company>

And this XML string is valid:

<ssl_company>A &amp; B Company</ssl_company>

The following special characters should be URL encoded:

  • Control characters (values 0x01 to 0x1f, and 0x7f)

  • 8-bit ASCII values (values > 0x7f)

  • Any of the following characters:

    • ’ ’ (space character)

    • ‘“’ (double quote)

    • ‘#’ (hash or pound)

    • ‘<’ (less than)

    • ‘>’ (greater than)

    • ’' (back slash)

    • ‘^’ (circumflex)

    • ‘`’ (backquote)

    • ‘{’ (left squiggly bracket or brace)

    • ‘|’ (vertical bar)

    • ‘}’ (right squiggly bracket or brace)