Message Structure

A JSON message request consists of an action (in case of a payment), a header, and a number of logical blocks (e.g. transaction, card, customer, redirect, etc.) contained in a “body” block.

The response consists of a result, possibly an error block and a number of logical blocks contained in a “body” block.

The blocks and fields for each API method are defined in the next chapter. Below, the generic action, header and results are described.

Request Message Structure

The request message is composed of:

  • Header and Body blocks

Header

The header of the JSON message request contains the field that identifies the party making the request.

Field
Type
Required¹
Description
businessId
String(64)
Required
The ID provided to identify your company.

Body

Field
Type
Required¹
Description
transaction
object
Required
The transaction object.
dba
object
Conditional
Block with merchant data.
card
object
Conditional
Block with card data, required for credit card transactions.
threeDSecure
object
Optional block to provide 3D Secure data from external MPI.
bank
object
Conditional
Block needed for bank account transactions.
option
object
Conditional
Block to set options for the payment process.
customer
object
Consumer specific data, needed for some alternative payment methods and fraud checks.
billingAddress
object
Conditional
Billing address data of the consumer, needed for specific brands and for AVS and fraud checks.
shippingAddress
object
Conditional
Shipping address data of the consumer, needed for certain brands (e.g. PayPal) and fraud checks.
"header":{"businessId":"2010"}

"body" : {
    "card" : {...},
    "transaction" : {...}
}

Response Message Structure

The response message is composed of:

  • Result and Description objects
  • Header and Body blocks

Result

AceHub API uses the “result” field in the response body as the primary and most important indication of success or failure. The “result” field should be used as basis for further processing rather than evaluating any other field first.

Field
Type
Required¹
Description
result
Number(5)
Required
The main result that determines the way a merchant can/should process the transaction described in this section.
description
String
Required
A short description of the result.

Header

Field
Type
Required¹
Description
requestTimestamp
Date-time
Required
The combined date and time in UTC (ISO8601).
requestCode
String
Required
An internally-generated tracking code.

Body

Field
Type
Required¹
Description
transaction
block
Conditional
Transaction data.
redirect
block
Returned in case of payments where the consumer needs to be redirected to a bank.
card
block
Conditional
Card data.
threeDSecure
block
Conditional
3D Secure result. See the 3D Secure section for more information.
bank
block
Contains the bank responses.
token
block
Conditional
Block containing the token information. It will be returned if the "tokenize" field is set to "true" in the payment request. See the Tokenization section for further information.
error
block
Contains the error(s) displayed when the transaction resulted in an error.
{
  "result": 2,
  "description": "Pending",

  "header": {
      "requestTimestamp": "2017-05-29T10:47:19Z",
      "requestCode": "105.156b8b78-e0dd-4b2f-8665-7e2223f5770b"
  },

  "body": {
      "transaction": {...}
  }
}

¹Required fields

required
The field or object is mandatory.

conditional
The field or object is mandatory if some conditions are fulfilled.

Note: The fields or objects without any label are optional.

What's next