redocly logo API docs by Redocly

Merchant Initiated Host to Host API (v1.1)

Download OpenAPI specification:Download

Support: support@ifsf.org License: IFSF License

Group: Electronic Business to Business

Definition: Interface for a merchant to initiate a transaction (using merchant applications) and ask for issuer authorization

Referenced Standards:

Scope: IFSF

Part of: Payments Working Group

Payment

Payment request and reversal advice

POST/clients/{clientID}/events/{correlationID}/paymentRequests

POST to process a payment request (Post-Pay)

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

Request Body schema: application/json
required
any (cardReqObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The details may also be in clear or encrypted as appropriate. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC (the choice is identified by the context element).

required
any (paymentContextReqObject)

Payment context supplies further context and conditions of the transaction. The cases considered are: MSR, CNP, ICC, TOKEN_RFID and TOKEN

encryptedCustomerData
string (cryptoKeyType) [ 6 .. 2048 ] characters

The encryption key data type used to transmit a key. Use base 58 encoding.

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject1)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "card": {
    },
  • "paymentContext": {
    },
  • "encryptedCustomerData": "string",
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "paymentRequestsResponse": {
    }
}

POST/clients/{clientID}/events/{correlationID}/paymentReversalAdvices

POST to process a payment reversal advice

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

Request Body schema: application/json
adviceReason
string (adviceReasonReversalENUMType) <= 40 characters
Enum: "CUSTOMER_CANCEL" "RESPONSE_ERROR" "SIGNATURE" "TIMEOUT" "CARD_DECLINED" "UNABLE_TO_COMPLETE"

indicates why the advice is sent - online reversals

required
any (cardAdvObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC. The details may also be in the clear or encrypted as appropriate

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject2)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "adviceReason": "CUSTOMER_CANCEL",
  • "card": {
    },
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "paymentReversalAdvicesResponse": {
    }
}

Pre-Authorization

Pre-Authorization request, completion advice and reversal advice

POST/clients/{clientID}/events/{correlationID}/preAuthorizationRequests

POST to process a pre-authorization request

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

Request Body schema: application/json
required
any (cardReqObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The details may also be in clear or encrypted as appropriate. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC (the choice is identified by the context element).

required
any (paymentContextReqObject)

Payment context supplies further context and conditions of the transaction. The cases considered are: MSR, CNP, ICC, TOKEN_RFID and TOKEN

encryptedCustomerData
string (cryptoKeyType) [ 6 .. 2048 ] characters

The encryption key data type used to transmit a key. Use base 58 encoding.

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject3)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "card": {
    },
  • "paymentContext": {
    },
  • "encryptedCustomerData": "string",
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "preAuthorizationRequestsResponse": {
    }
}

POST/clients/{clientID}/events/{correlationID}/preAuthorizationCompletionAdvices

POST to process a pre-authorization completion advice

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

Request Body schema: application/json
required
any (cardAdvObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC. The details may also be in the clear or encrypted as appropriate

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject4)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "card": {
    },
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "preAuthorizationCompletionAdvicesResponse": {
    }
}

POST/clients/{clientID}/events/{correlationID}/preAuthorizationReversalAdvices

POST to process a pre-authorization reversal advice

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

Request Body schema: application/json
adviceReason
string (adviceReasonReversalENUMType) <= 40 characters
Enum: "CUSTOMER_CANCEL" "RESPONSE_ERROR" "SIGNATURE" "TIMEOUT" "CARD_DECLINED" "UNABLE_TO_COMPLETE"

indicates why the advice is sent - online reversals

required
any (cardAdvObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC. The details may also be in the clear or encrypted as appropriate

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject2)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "adviceReason": "CUSTOMER_CANCEL",
  • "card": {
    },
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "preAuthorizationReversalAdvicesResponse": {
    }
}

Refund

Refund request and reversal advice

POST/clients/{clientID}/events/{correlationID}/refundRequests

POST to process a refund request

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
originalTrx
string (trxUmtiType) [ 1 .. 40 ] characters

Used for refunds to identify the original transaction

openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

Request Body schema: application/json
required
any (cardReqObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The details may also be in clear or encrypted as appropriate. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC (the choice is identified by the context element).

required
any (paymentContextReqObject)

Payment context supplies further context and conditions of the transaction. The cases considered are: MSR, CNP, ICC, TOKEN_RFID and TOKEN

encryptedCustomerData
string (cryptoKeyType) [ 6 .. 2048 ] characters

The encryption key data type used to transmit a key. Use base 58 encoding.

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject1)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "card": {
    },
  • "paymentContext": {
    },
  • "encryptedCustomerData": "string",
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "refundRequestsResponse": {
    }
}

POST/clients/{clientID}/events/{correlationID}/refundReversalAdvices

POST to process a refund reversal advice

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
originalTrx
string (trxUmtiType) [ 1 .. 40 ] characters

Used for refunds to identify the original transaction

openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

Request Body schema: application/json
adviceReason
string (adviceReasonReversalENUMType) <= 40 characters
Enum: "CUSTOMER_CANCEL" "RESPONSE_ERROR" "SIGNATURE" "TIMEOUT" "CARD_DECLINED" "UNABLE_TO_COMPLETE"

indicates why the advice is sent - online reversals

required
any (cardAdvObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC. The details may also be in the clear or encrypted as appropriate

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject2)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "adviceReason": "CUSTOMER_CANCEL",
  • "card": {
    },
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "refundReversalAdvicesResponse": {
    }
}

Offline

Offline payment advice, offline refund advice

POST/clients/{clientID}/events/{correlationID}/offlinePaymentAdvices

POST to process an offline payment advice. Note: the offline advice use the request schemas as they need to send complete payment information

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

Request Body schema: application/json
adviceReason
string (adviceReasonOfflineENUMType) <= 40 characters
Enum: "ISSUER_UNAVAILABLE" "TERMINAL_PROCESSED" "ICC_PROCESSED" "STAND_IN" "MANUAL_VOUCHER"

indicates why the advice is sent - offline payment and refund

required
any (cardAdvObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC. The details may also be in the clear or encrypted as appropriate

encryptedCustomerData
string (cryptoKeyType) [ 6 .. 2048 ] characters

The encryption key data type used to transmit a key. Use base 58 encoding.

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject6)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "adviceReason": "ISSUER_UNAVAILABLE",
  • "card": {
    },
  • "encryptedCustomerData": "string",
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "offlinePaymentAdvicesResponse": {
    }
}

POST/clients/{clientID}/events/{correlationID}/offlineRefundAdvices

POST to process an offline refund advice Note: the offline advice use the request schemas as they need to send complete payment information

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

correlationID
required
string (trxUmtiType) [ 1 .. 40 ] characters

Correlation ID is a mandatory unique identifier assigned by the client to each customer transaction, which in this context means a group of related messages linked to a single customer event, such as an authorisation and a subsequent reversal. This specification does not define how the correlation ID is derived, because suitable method is dependent on the design of the client and source of transactions. Possibilities could be a sequentially incrementing counter (similar to STAN found in ISO 8583 interfaces), a combination of individual fields (e.g. terminal ID and reliable timestamp) or a GUID

header Parameters
originalTrx
string (trxUmtiType) [ 1 .. 40 ] characters

Used for refunds to identify the original transaction

openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

payloadSignatureAlgorithm
required
string (description40BaseType) <= 40 characters

Header signature algorithm that specify an algorithm used for the signature

payloadSignature
required
string (description100BaseType) <= 100 characters

Header signature that carries a signature/MAC of the message payload

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

Request Body schema: application/json
adviceReason
string (adviceReasonOfflineENUMType) <= 40 characters
Enum: "ISSUER_UNAVAILABLE" "TERMINAL_PROCESSED" "ICC_PROCESSED" "STAND_IN" "MANUAL_VOUCHER"

indicates why the advice is sent - offline payment and refund

required
any (cardAdvObject)

The Card object conveys the details of the payment card used for the transaction. Depending on how the transaction was initiated, it may contain different card details read from the card. The use cases considered are: MSR, CNP, ICC, TOKEN and NFC. The details may also be in the clear or encrypted as appropriate

encryptedCustomerData
string (cryptoKeyType) [ 6 .. 2048 ] characters

The encryption key data type used to transmit a key. Use base 58 encoding.

required
object (merchantObject)

provides information about the merchant selling the goods

required
object (merchantPointOfInteractionObject)

This is the schema used to identify the point of interaction. POIBatchNumber was removed because it does not apply to H2H SiteID, Country and FuelingPointID were added trxMatchingID is equivalent to poiTraceNo in CGI language moved from capabilities to main object terminalID is included in CGI. Is it necessary in Issuer initiated?

saleContext
required
string (description16BaseType) <= 16 characters

16 character description.

required
object (trxObject5)

Transaction collects information related to the authorisation transaction.

Responses

Request samples

Content type
application/json
{
  • "adviceReason": "ISSUER_UNAVAILABLE",
  • "card": {
    },
  • "encryptedCustomerData": "string",
  • "merchant": {
    },
  • "POI": {
    },
  • "saleContext": "string",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "offlineRefundAdvicesResponse": {
    }
}

Reconciliation

Reconciliation advice

POST/clients/{clientID}/reconciliation

POST to process a reconciliation

Authorizations:
apikeyoauth2
path Parameters
clientID
required
string (description40BaseType) <= 40 characters

Client ID is assigned by the server to each client, and is agreed before communications is possible. This ID is not used for business processing purposes and can be chosen arbitrarily, but could be a merchant ID or terminal ID or other suitable identifier that is already available.

header Parameters
openretailing-application-sender
required
string (description100BaseType) <= 100 characters

Merchant host device connected that can run transactions for different clients

transmissionDateTime
required
string <date-time> (dateTimeType) [ 10 .. 30 ] characters

transmission date / time

Request Body schema: application/json
batchNumber
number

Batch Number indicates the reconciliation batch to which this message is closing. The batch number is assigned by the API client

businessDate
string <date-time> (dateTimeType) [ 10 .. 30 ] characters
dateTimeClosure
string <date-time> (dateTimeType) [ 10 .. 30 ] characters
object (merchantObject)

provides information about the merchant selling the goods

object (merchantReconciliationTotalsObject)

This is the merchant reconciliation totals schema

traceNumber
number

Trace Number is an API client assigned transaction number. This should be a sequentially incrementing number that is unique to each new message sent

Responses

Request samples

Content type
application/json
{
  • "batchNumber": 0,
  • "businessDate": "2019-08-24T14:15:22Z",
  • "dateTimeClosure": "2019-08-24T14:15:22Z",
  • "merchant": {
    },
  • "totals": {
    },
  • "traceNumber": 0
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "reconciliationResponse": {
    }
}

Sensitive Objects Definition

Sensitive objects definition only (not related to H2H uses cases)

POST/customerDataDefinitionOnly

POST to document the "encryptedCustomerData" property content

Authorizations:
apikeyoauth2
Request Body schema: application/json
emailAddress
string (emailAddressType) <= 320 characters

email address (valid according RFC 3696).

billingAddress
Array of strings (description100BaseType) [ 0 .. 5 ] items [ items <= 100 characters ]

Customer billing addres

driverID
string (description16BaseType) <= 16 characters

16 character description.

string or string (driverEntryModeEENUMType)

DriverID entry mode

fleetID
string (description40BaseType) <= 40 characters

40 character description.

string or string (fleetEntryModeEENUMType)

FleetID entry mode

odometer
string (decimal12BaseType) ^-?[0-9]{0,12}(\.[0-9]{1,5})?$

12,5 decimal value

string or string (odometerEntryModeEENUMType)

Odometer entry mode

vehicleNumber
string (description16BaseType) <= 16 characters

16 character description.

string or string (vehicleEntryModeEENUMType)

Vehicle number entry mode

Responses

Request samples

Content type
application/json
{
  • "emailAddress": "string",
  • "billingAddress": [
    ],
  • "driverID": "string",
  • "driverEntryMode": "KEY_ENTRY",
  • "fleetID": "string",
  • "fleetEntryMode": "KEY_ENTRY",
  • "odometer": "string",
  • "odometerEntryMode": "KEY_ENTRY",
  • "vehicleNumber": "string",
  • "vehicleEntryMode": "KEY_ENTRY"
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    }
}

POST/sensitiveCardDetailsReq

POST to document the "sensitiveCardDetailsReq" property content

Authorizations:
apikeyoauth2
Request Body schema: application/json
context
required
string (cardContextENUMType) <= 6 characters

Context identifies the different use cases related to cards. By selecting the context the corresponding schema can be found

track2
required
string (track2DataType) [ 8 .. 40 ] characters

Track 2 is the track 2 read from the magnetic stripe or track 2 equivalent read from the ICC

required
object (expDateObject)
PAN
required
string (PANType)

It contains the encrypted PAN or DPAN and accompanying control information embedded within a JWE data structure

Responses

Request samples

Content type
application/json
Example
{
  • "context": "MSR",
  • "track2": "stringst",
  • "expiry": {
    },
  • "PAN": "string"
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    }
}

POST/sensitiveCardDetailsOff

POST to document the "sensitiveCardDetailsOff" property content

Authorizations:
apikeyoauth2
Request Body schema: application/json
context
required
string (cardContextENUMType) <= 6 characters

Context identifies the different use cases related to cards. By selecting the context the corresponding schema can be found

track2
required
string (track2DataType) [ 8 .. 40 ] characters

Track 2 is the track 2 read from the magnetic stripe or track 2 equivalent read from the ICC

required
object (expDateObject)
PAN
required
string (PANType)

It contains the encrypted PAN or DPAN and accompanying control information embedded within a JWE data structure

Responses

Request samples

Content type
application/json
Example
{
  • "context": "MSR",
  • "track2": "stringst",
  • "expiry": {
    },
  • "PAN": "string"
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    }
}

POST/sensitiveCardDetailsAdv

POST to document the "sensitiveCardDetailsAdv" property content

Authorizations:
apikeyoauth2
Request Body schema: application/json
context
required
string (cardContextENUMType) <= 6 characters

Context identifies the different use cases related to cards. By selecting the context the corresponding schema can be found

track2
required
string (track2DataType) [ 8 .. 40 ] characters

Track 2 is the track 2 read from the magnetic stripe or track 2 equivalent read from the ICC

required
object (expDateObject)
PAN
required
string (PANType)

It contains the encrypted PAN or DPAN and accompanying control information embedded within a JWE data structure

Responses

Request samples

Content type
application/json
Example
{
  • "context": "MSR",
  • "track2": "stringst",
  • "expiry": {
    },
  • "PAN": "string"
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    }
}

Transaction / response complete schemas

Transaction / response complete schemas (not related to H2H uses cases)

POST/transactions

Post to document complete transaction object definition. This schema may be useful for programmers to define transaction object including all the attributes independent of the type of request / advice

Authorizations:
apikeyoauth2
Request Body schema: application/json
string or string (currencyEENUMType)

ISO-4217 / UN/ECE REC 09 Codes

approvedAmount
string (decimal16BaseType) ^-?[0-9]{0,16}(\.[0-9]{1,5})?$

16,5 decimal value

originalAmount
string (decimal16BaseType) ^-?[0-9]{0,16}(\.[0-9]{1,5})?$

16,5 decimal value

transactionAmount
string (decimal16BaseType) ^-?[0-9]{0,16}(\.[0-9]{1,5})?$

16,5 decimal value

object (amountObject)

The amount object contains the amounts – both monetary and volume related amounts

object (amountObject)

The amount object contains the amounts – both monetary and volume related amounts

object (amountObject)

The amount object contains the amounts – both monetary and volume related amounts

authorizationCode
string (description16BaseType) <= 16 characters

16 character description.

batchNumber
number

Batch Number indicates the reconciliation batch to which this transaction is assigned. The batch number is assigned by the API client.

dateTimeLocal
string <date-time> (dateTimeType) [ 10 .. 30 ] characters
Array of objects (transactionLineObject) [ 0 .. 100 ] items

List of the item(s) purchased in this transaction.

string or string (serviceLevelEENUMType)

Indicates the service rendered at the site, if known and applicable

transactionID
string (trxUmtiType) [ 1 .. 40 ] characters

Unique Message Transaction Identifier

traceNumber
number

Trace Number is an API client assigned transaction number. This should be a sequentially incrementing number that is unique to each new message sent.

Responses

Request samples

Content type
application/json
{
  • "currency": "AED",
  • "approvedAmount": "string",
  • "originalAmount": "string",
  • "transactionAmount": "string",
  • "approvedLimit": {
    },
  • "originalLimit": {
    },
  • "transactionLimit": {
    },
  • "authorizationCode": "string",
  • "batchNumber": 0,
  • "dateTimeLocal": "2019-08-24T14:15:22Z",
  • "transactionLines": [
    ],
  • "serviceLevel": "FULL",
  • "transactionID": "string",
  • "traceNumber": 0
}

Response samples

Content type
application/json
{
  • "statusReturn": {
    }
}

POST/responses

Post to document complete response object definition. This schema may be useful for programmers to define response object including all the attributes independent of the type of request / advice

Authorizations:
apikeyoauth2
Request Body schema: application/json
string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "statusReturn": {
    }
}