Picture

Request/Response Formats - Payment processing

All Payments API commands share a common format, with the specific fields for those commands in a Request node (see the Payments API Reference Documentation).

Requests can be formatted in XML or JSON, and the Accept header should be set to “application/json” or “application/xml” to specify the format of the Response you wish to receive. If no Accept header is specified, JSON is assumed.

Important note: Field names and values in JSON are not case sensitive, but in XML BOTH field names and values are case sensitive. As an example, the “Is3Ds” field must be named using the cases shown and set to “True” or “False”. If you name your field “IS3DS” in XML, the field will be ignored. The tables in the commands section below, show the correct cases to use in XML messages.

All Requests are made by POSTing the following Request structure to the command URI. Version, ApiKey, Request and Signature are supplied for all commands:

In JSON format
 

{

    "Version": "1.1",

    "ApiKey": "YourApiKey",

    "Request": {

      "Field1": Value1,

      "Field2": Value2

    },

    "Signature": "SHA512 hashed Request node contents and passphrase"

}

 

Or in XML
 

<Version>1.1</Version>

<ApiKey>YourApiKey</ApiKey>

<Request>

       <Field1>Value1</Field1>

       <Field2>Value2</Field2>

</Request>

<Signature>SHA512 hashed Request node contents and passphrase</Signature>

If an invalid Version number is specified, the latest is assumed. The ApiKey field contains the unique key issued to you to access this API, and the Signature is a hash of your security token and the contents of the Request node (see the section below for examples). The Fieldx and Valuex fields are specific to each command and are provided in detail in the API Reference Documentation.

Successful responses from each command also share a common format:

In JSON format

 

{

  "Version": "1.1",

  "DateTime": "2018-07-11T13:52:08.5842645Z",

  "Response": {

    "Field1": Value1,

    "Field2": Value2

  }

}

 

Or in XML

 

<Version>1.1</Version>

<Datetime>2018-07-11T13:52:08.5842645Z</Datetime>

<Response>

       <Field1>Value1</Field1>

       <Field2>Value2</Field2>

</Response>

All successful responses contain:

  • the Version number of the Response being delivered (which will match that in the Request if that Version is valid)

  • the current UTC DateTime field (in ISO-8601 format)

  • a Response object with command-specific nodes within it

Unsuccessful responses are similar in format to successful ones, but with an Error object instead of a Response object:

In JSON format

 

{

  "Version": "1.1",

  "DateTime": "2018-07-11T13:52:08.5842645Z",

  "Error": {

    "Code":“String value”,

    "Message": “Human readable message”

    "Details”:{Empty, or a collection of multiple Code and Message objects}   }

}

 

Or in XML

 

<Version>1.1</Version>

<Datetime>2018-07-11T13:52:08.5842645Z</Datetime>

<Error>

       <Code> String Value</Code>

       <Message>Human Readable Message</Message>

       <Details>Empty, or a collection of multiple Code and Message objects</Details>

</Error>

All error responses contain:

  • the Version number of the Response being delivered (which will match that in the Request if that Version is valid)

  • the current UTC DateTime field (in ISO-8601 format)

  • an Error object containing an overall error Code and Message with, optionally, a Detail object containing finer grained error information