Message Format

Transaction messages supported by InterPay’s integration interface consist of simple strings of name/value pairs, which can be sent using either SSL or HTTPS GET or POST methods. The system is designed to offer flexibility in both request submission and response formatting.

• HTTPS GET Method:
  The GET method is useful if your platform can perform HTTPS page retrievals. You can send a request as part of the URL, and the response is delivered back in a "Web page" format. Using a web browser is a convenient way to test connectivity before fully implementing your interface.

  • GET requests are sent over port 1443 for all SSL-encrypted traffic.
  • The MIME type of the response is text/plain, and the information returned is not formatted for display to the cardholder.

• HTTPS POST Method:
  With the POST method, you can pass data either in the URL (similar to GET) or in the body of the request. For body-based requests, data can be formatted as either:

  • JSON: A structured data format.
  • Tag/Value: A simple format using field names and values.

• Flexibility in Data Transmission:
  Whether GET or POST is used, InterPay™ supports sending requests as raw HTTP strings without headers or with full HTTP headers, depending on your platform’s capability.

Gateway Requests

All requests are delivered in one of two formats: tag/value pairs or JSON. The choice of format allows for integration with a wide variety of platforms and workflows.

Tag/Value Format:

Requests are constructed by concatenating a series of fields and their values, separated by ampersands (&):

field1=value1&field2=value2&field3=value3

• Field values must be URL-encoded to allow special characters.
• If an ampersand (&) is needed within a field value, send it as a double ampersand (&&) to avoid confusion with field separators.

For structured data, fields can represent groups using nested brackets:

&fieldGroup=[subfield1=value1&subfield2=value2][subfield1=value3&subfield2=value4]

JSON Format:

Requests can also be submitted as JSON objects, either in the URL or the body of a POST request. JSON provides a structured and readable format for complex data exchanges:

{
  "field1": "value1",
  "field2": "value2",
  "fieldGroup": [
    { "subfield1": "value1", "subfield2": "value2" },
    { "subfield1": "value3", "subfield2": "value4" }
  ]
}

Protocol Support:

• SSL/HTTPS: All requests are securely transmitted over SSL-encrypted channels on port 1443.
• Testing Note: Before full integration, use a browser to send GET requests and confirm connectivity.

Gateway Responses

InterPay™ ensures response formatting matches the request format for seamless integration:

• If the request is in tag/value format, the response will also be in tag/value format.
• If the request is in JSON format, the response will be in JSON format.
• If HTTP headers are included in the request, they will also be included in the response.

Custom Formatting:

You can specify the desired response format by including parameters in the URL or body of the request:

• To explicitly request JSON formatting, add the appropriate header or query parameter.
• For raw HTTP requests, the response will mirror the raw format of the input request.

MIME Type:

• Responses for GET requests will have the MIME type text/plain, ensuring compatibility with browser-based testing tools.
• POST responses may include additional metadata in headers when sent using HTTP.

Error Handling:

Errors will be returned in the same format as the original request.