redocly logo API docs by Redocly

Issuer Initiated Host to Host API (v1.0)

Download OpenAPI specification:Download

Support: support@ifsf.org License: IFSF License

Group: Electronic Business to Business

Definition: Interface for an issuer to authorize a transaction at a Merchant's fueling dispenser.

Description:

The proposed version of Host-to-Host APIs uses message calls that are equivalent to the Authorization Request, Financial Request and Financial Advice used in the IFSF ISO8583 based H2H standard. For clarity, however, it is not intended that this API is a direct conversion of ISO8583 messages into JSON message structures nor is it intended that this API be completely interoperable with ISO8583. It may be convertible in some limited use cases, but this is not guaranteed.

This proposal enables reusing backend logic and co-existence of traditional and APIs based integration. Limiting the number of APIs to accomplish a payment transaction, also reduces the potential exceptions that might occur executing the payment process; it eliminates the necessity of a stateful handling of multiple APIs, before completing mandatory and optionally information required for authorization and capture of the payment transaction

This approach assumes that the application server accepting the payment requests and sending the Payment APIs has the capability to manage the status of the requests till their completion (responsibility that might reside in an eCommerce platform, or ultimately in a payment terminal connecting into this server

  • depending on the use case).

Background:

Payment APIs enable extending business opportunities and new channels of sales and payment acceptance. As the payment industry has diversified Method of Payments, channels of acceptance and technologies, IFSF has the opportunity to define modern interoperability standards for Fuel Retailers and B2B payment offers.

Benefits of Payment APIs are:

  • Business development: enable new channels of purchase and payment – e.g. eCommerce
  • Cardless payment: enable various forms of token based payment acceptance.
  • Simpler integration: easier to implement integration, more open interoperability.
  • Cheaper development: leverage common industry skills for development of payment.
  • Cheaper platforms: leverage platforms not fully dedicated to payment, that can operate outside of PCI Data Security Standard scope (though security remains a primary concern).
  • Faster and agile flexibility: develop faster, leverage DevOps methodologies.

Use Case Summary:

The use case enables the Issuer App being accepted through the Acquiring agreement of the Merchant; the Issuer manages all the App users and it is in full control of the tokens.

The Acquirer enables the request from the site, plus the unattended sales on the forecourt: the status with the site is maintained by the Acquirer, but the status of the App is maintained by the Issuer; this involves that the status is shared among Acquirer and Issuer.

  • The Issuer Consumer approaches a fueling position, and activates is own application.
  • The Issuer Host determines the identity of the fueling point, and communicates that position to the Merchant Host.
  • The Merchant Host initiates the transaction and requests the Site System to reserve the fueling point.
  • The Issuer Host obtaines authorization for the transaction funds and requests fueling point authorization to Merchant Host.
  • The Merchant Host communicates with the Site System to authorize the fueling point.
  • The Site System confirms the authorization to the Merchant Host which in turn reports to the Issuer Host.
  • The Issuer Consumer fuels.
  • The Site System sends a finalization.
  • The Issuer Host sends EFT receipt information to the Merchant Host for the Site System to merge with transaction receipt.
  • The Issuer Host collects complete transaction receipt from Merchant Host.

Additional Alternate Flows are supported:

  • Code Verification generated entered at the OPT and validated by the site or 'Merchant Host'
  • Site and fueling point identification through QR, Site and Fueling Point or any other unique Point of Interaction Identifier.
  • The customer may also buy non fuels products

Out Of Scope:

  • Loyalty / Discounts.
  • Refunds.

Architecture:

This API uses RESTFul Web Services, associating required functionality with resources and operations on those resources. For handling unsolicited events from the service provider to the client, it uses HTML5 constructs such as Server Sent Events and Web Sockets. The interfaces are "highly cohesive" and "loosely coupled" in order to provide maximum flexibility to the implementer, and to allow implementation as micro-services, if that construction is useful to the implementer.

Referenced Standards:

Scope: IFSF

Part of: Payments Working Group

Transaction authorization

start transaction, cancel transaction, authorization

POST to start sale transaction at site

POST to start sale transaction at site and reserve fueling point. The response includes the transaction umti and can include a validation code

Authorizations:
apikeyoauth2
header Parameters
openretailing-application-sender
required
string <= 100 characters

The controlling device identification

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

transmission date / time

Request Body schema: application/json
object

This is the schema used to provide different options to identify the point of interaction. This can be:

  • POIType = FP: The object must include fuelingPointID and siteID.
  • POIType = POS: The object may include the POS ID and potentially a unique transaction identification code for that POS (can also use a STAC or a scanned QR/BAR Code).

Country should be included for multi-country implementations.

object

Receipt prompts, car wash prompts, etc

Responses

Request samples

Content type
application/json
{
  • "POI": {
    },
  • "customerPreferences": {
    }
}

Response samples

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

POST to authorize a sale transaction

POST to authorize a sale transaction (a code may be required)

If code is required, the transaction will not be started until the code is validated

Authorizations:
apikeyoauth2
path Parameters
UMTI
required
string [ 1 .. 40 ] characters

UMTI (Unique Message Transaction Identifier)

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

The controlling device identification

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

transmission date / time

Request Body schema: application/json
required
object

This is the schema used to provide different options to identify the point of interaction. This can be:

  • POIType = FP: The object must include fuelingPointID and siteID.
  • POIType = POS: The object may include the POS ID and potentially a unique transaction identification code for that POS (can also use a STAC or a scanned QR/BAR Code).

Country should be included for multi-country implementations.

object
object
Array of objects <= 100 items

list of products authorized for sale

object

This is the schema used to define the validation code

object

Data for the payment method for the mobile transaction. Payment mechanism, ISO, first 6, last 4, card type, etc.

Responses

Request samples

Content type
application/json
{
  • "POI": {
    },
  • "maxTrxAmount": {
    },
  • "paymentInfo": {
    }
}

Response samples

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

Cancel transaction request

Send DELETE to terminate transaction flow. Depending on the state of the transaction, different results will occur:

  • If transaction was not yet authorized, any reservation will be cleared and no trxDetails will be returned.
  • If transaction was authorized but dispensing had not yet started, the authorization will be cancelled and no 'trxDetails` will be returned.
  • If fueling already started, the Merchant Host responds with an error message saying that transaction can not be canceled after dispensing starts
  • If fueling was completed, the Merchant Host will clear the transaction at the site and return the actual dispensed volume in trxDetails.
Authorizations:
apikeyoauth2
path Parameters
UMTI
required
string [ 1 .. 40 ] characters

UMTI (Unique Message Transaction Identifier)

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

The controlling device identification

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

transmission date / time

required
string or string

Reason why the transaction was canceled

Array of objects <= 100 items

list of products authorized for sale

required
Array of objects <= 50 items

EFT / transaction receipt

Responses

Response samples

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

Transaction information

transaction details, completion, receipts

Get transaction request

Use GET to retrieve transaction information

Authorizations:
apikeyoauth2
path Parameters
UMTI
required
string [ 1 .. 40 ] characters

UMTI (Unique Message Transaction Identifier)

Responses

Response samples

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

Get receipt request

GET to retrieve receipt data

Authorizations:
apikeyoauth2
path Parameters
UMTI
required
string [ 1 .. 40 ] characters

UMTI (Unique Message Transaction Identifier)

Responses

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "receipt": [
    ]
}

Post completion

POST to send EFT receipt and retrieve transaction receipt which combines EFT and merchant information. The transaction state changes to "completed"

Authorizations:
apikeyoauth2
path Parameters
UMTI
required
string [ 1 .. 40 ] characters

UMTI (Unique Message Transaction Identifier)

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

The controlling device identification

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

transmission date / time

Request Body schema: application/json
Array (<= 50 items)
alignment
string <= 10 characters
Enum: "Left" "Right" "Center" "Justified"

Text line Printer(/Display) alignment of text line

height
string <= 6 characters
Enum: "Single" "Double" "Half"

Text line Printer(/Display) height of chars

width
string <= 6 characters
Enum: "Single" "Double"

Text line Printer(/Display) widht of chars

string or string

Text line Printer(/Display) style of chars

text
required
string <= 100 characters

100 character description.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "statusReturn": {
    },
  • "receipt": [
    ]
}

Post EFT receipt (optional)

POST to send EFT receipt (optional)

Authorizations:
apikeyoauth2
path Parameters
UMTI
required
string [ 1 .. 40 ] characters

UMTI (Unique Message Transaction Identifier)

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

The controlling device identification

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

transmission date / time

Request Body schema: application/json
Array (<= 50 items)
alignment
string <= 10 characters
Enum: "Left" "Right" "Center" "Justified"

Text line Printer(/Display) alignment of text line

height
string <= 6 characters
Enum: "Single" "Double" "Half"

Text line Printer(/Display) height of chars

width
string <= 6 characters
Enum: "Single" "Double"

Text line Printer(/Display) widht of chars

string or string

Text line Printer(/Display) style of chars

text
required
string <= 100 characters

100 character description.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "timestamp": "2009-11-20T17:30:50",
  • "result": "success",
  • "error": "ERRCD_OK",
  • "message": "Operation completed successfully"
}

Reconciliation

Reconciliation messages

Reconciliation (issuer vs merchant)

POST to reconcile

Both Issuer and Merchant totals will include trx count and trx total, grouped by country, currency and issuer.

If for the same IssuerID, two Reconciliation requests are received with the same DateTime, the response will de "200, ERRCD_DONE, Duplicated Request. No new reconciliation totals will be calculated, and the same results should be returned as per the previous request.

Authorizations:
apikeyoauth2
header Parameters
openretailing-application-sender
required
string <= 100 characters

The controlling device identification

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

transmission date / time

Request Body schema: application/json
issuerDateTime
string <date-time> [ 10 .. 30 ] characters
Array of objects <= 1000 items

This is the schema used to provide reconciliation totals from issuer and merchant

Responses

Request samples

Content type
application/json
{
  • "issuerDateTime": "2021-11-29T16:03:25.766Z",
  • "issuerReconciliationTotals": [
    ]
}

Response samples

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

Merchant Events

Merchant Server Sent Events

Merchant related events subscription.

Returns a URL to receive an event stream to notify the selected events to the client. Event data field conforms to the schema described in ..\schemas\ MerchantEventObject where each type of event returned is described.

Authorizations:
apikeyoauth2
query Parameters
eType
Array of strings <= 20 items [ items <= 40 characters ]
Items Enum: "trxStateChange" "masterChanges"

List of the type of events to subscribe to.

Responses

Response samples

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