Fuel API - Methods

The Fuel Integration API methods enable a fuel retailer or technology provider to create cloud services that can process mobile payments at the pump. The following methods are described in this guide:

Note: The paydiantTransactionRefId refers to the WLW unique identifier.

StoreLocationID in different methods

During onboarding, a merchant identifies each of its acceptance locations with a unique identifier that is meaningful within the merchant’s system, which is stored as the storeCode for that location. When the WLW platform requests data from the merchant relative to a specific store, such as with the retrieveSiteInformation and pumpAuthorization calls, WLW identifies the store using this storeCode value, passed as the storeLocationID.

However, since the identifier provided by the merchant is not necessarily unique across WLW’s entire platform, but rather, only within the merchant’s system, when the merchant calls the WLW platform (such as with the upateFuelEvent call), it must identify the location such that it is unique to WLW, as well. For this reason, the storeLocationId value for inbound calls to WLW’s B2B API is comprised of the merchant’s location identifier plus WLW’s shortName value for the merchant as a prefix (<shortName> storeCode).

For example, say a Fuel Site identifies a location as 123 and WLW’s shortname for the Fuel Site is ABC. WLW will reference the storeLocationID in calls to the Fuel Site as 123 while the Fuel Site will be expected to reference the storeLocationID in calls to WLW as ABC123. The following table shows the expected values for each of the methods exposed in the B2B Fuel API.

Method Attribute Value
retrieveSiteInformation or pumpAuthorization storeLocationID 123
updateFuelEvent storeLocationID abc123

retrieveSiteInformation

Returns information about the Fuel Site including information about available Pumps as well as car wash product details.

GET
Resource URL: Provided by Partner

Request

Attribute Description
storeLocationID Required String
Unique identifier of a specific acceptance location associated with a specific merchant. This code is provided by the merchant/fuel processor when the location is onboarded in WLW. WLW stores this code as storeCode. See StoreLocationID in different methods for more information.

Response

Note: For successful transactions, use HTTP 200. For error conditions, use the HTTP code range 400/500. See http://en.wikipedia.org/wiki/List_of_HTTP_status_codes for more information.

Attribute Description
storeLocationID Required String
Unique identifier of a specific acceptance location associated with a merchantId. See StoreLocationID in different methods for information about this value.
additionalData Optional KeyValue
Set of custom key value pairs that provide additional information or settings.
fuelPumps Optional FuelPump
Array representing available pumps at the site.
latitude Optional String
Latitude of the location.
longitude Optional String
Longitude of the location.
siteResources Optional SiteResource
Array representing other available services, such as car washes.
status Required Status Code
Statement returned indicating whether the originating call failed or succeeded.

For example requests and responses, see the retrieveSiteInformation samples in both Use Cases and JSON Full Examples.

pumpAuthorization

A request to the site that initiates the pump authorization process. Includes any associated loyalty and or car wash selections.

POST
Resource URL: Provided by Partner

Request

Attribute Description
storeLocationID Required String
Unique identifier of a specific acceptance location associated with a merchantId. See StoreLocationID in different methods for information about this value.
fuelTicket Optional FuelTicket
Object that describes user selections based on site information.
thirdPartyLoyaltyInstrument Optional LoyaltyInstrument
Identifies a loyalty account which is related to this transaction for points accrual or redemption, but which is not part of the WLW-managed loyalty program.
paydiantTransactionRefId Contextual String
A unique transaction identifier generated by the WLW service. Once the WLW service returns a value for this attribute, the value must be included in all subsequent calls.
customerSelectedPaymentInstrument Required PaymentInstrument
The set of objects that represent each payment account that the user has elected to use in the current transaction.
walletIssuerId Optional String
A unique identifier that describes the mobile wallet that initiated the transaction.

Response

Attribute Description
status Required Status Code
Statement returned from the POS-Gateway indicating whether the originating call failed or succeeded.
paydiantTransactionRefId Contextual String
A unique transaction identifier generated by the WLW service. Once the WLW service returns a value for this attribute, the value must be included in all subsequent calls.

For example requests and responses, see the pumpAuthorization samples in both Use Cases and JSON Full Examples.

fuelCancel

POST
Resource URL: Provided by Partner

A request to the site that disables an activated fuel pump per request from the mobile user. This action is distinct from the updateFuelEvent (SUBMIT_FUEL_CANCEL), which is a cancellation initiated by the fuel site and communicated to the platform.

Note: You must invoke this call prior to initiation of the Fuel_Begin event, which is typically triggered when the fuel pump handle is lifted to dispense fuel.

Request

Attribute Description
storeLocationID Required String
Unique identifier of a specific acceptance location associated with a merchantId. See StoreLocationID in different methods for information about this value.
pumpNumber Required String
Merchant-assigned identifier of the fuel pump to turn off.
paydiantTransactionRefId Contextual String
A unique transaction identifier generated by the WLW service. Once the WLW service returns a value for this attribute, the value must be included in all subsequent calls.
processedPayment Required PaymentResult
The PaymentResult object that represents the payment authorization completed in conjunction with the fuel pre-auth.

Note: The customerSelectedPaymentInstrument and authAmount attributes were deprecated as of version 8.10.

Response

Attribute Description
storeLocationID Required String
Unique identifier of the acceptance location associated with the transaction.
status Required Status Code
Statement returned from the POS-Gateway indicating whether the originating call failed or succeeded.
paydiantTransactionRefId Contextual String
A unique transaction identifier generated by the WLW service. Once the WLW service returns a value for this attribute, the value must be included in all subsequent calls.

FuelCancel Status Codes

Status Code Status Message Connector Response
200 SUCCESS SUCCESS
201 Fuel Cancel Declined DECLINED
241 Processing error. PROCESSING_ERROR
242 Message security error. Please contact Customer Care. GATEWAY_PROCESSING_ERROR
242 Server error occurred. Please try later. GATEWAY_PROCESSING_ERROR
246 Timeout occurred. Please try again. OPERATION_TIMEOUT
250 Invalid locationID. Data is not found for the given locationID. INVALID_INPUTS

updateFuelEvent

Updates the transaction with the current information about the fuel event.

In the following tables, the requirements for each flow rule are indicated by the values in the 1, 2, 3, 4, and 5 columns where:

1 = SUBMIT_PRE_AUTH

2 = SUBMIT_SECONDARY_ID_FOR_VALIDATION

3 = SUBMIT_FUEL_CANCEL

4 = SUBMIT_FUEL_BEGIN

5 = SUBMIT_FUEL_END

For example, paydiantTransactionRefId is required for all these flow rules. See the .xsd for complete flow requirements.

Note: When submitting the flow rule of Submit_Secondary_Validation_ID, the WLW Platform has the ability to manage a configurable number of retries in the cloud. If the WLW Cloud returns a Status with Status Code 4xx - Invalid Secondary ID, your system should prompt the user to retry entering the Secondary ID. When the user reaches the maximum number of retries, the WLW Cloud returns Status Code 4xx - Transaction Canceled.

POST URL/b2b-gateway/transactions/fuelevent

Authentication: Required

Content Type: Application/json

Request

Name Definition
paydiantTransactionRefId Required for all flow rules String
A unique transaction identifier generated by the WLW service. Once the WLW service returns a value for this attribute, the value must be included in all subsequent calls.
transactionFlowRules Required for all flow rules transactionFlowRule
The set of enum values that represent the specific events or steps within the transaction to which this call applies. For each flow rule that is specified in the call, the corresponding data value must be passed in the call. Valid values are:
- SUBMIT_PRE_AUTH
- SUBMIT_SECONDARY_ID_FOR_VALIDATION
- SUBMIT_FUEL_CANCEL
- SUBMIT_FUEL_BEGIN
- SUBMIT_FUEL_END
- SUBMIT_FUEL_RECEIPT
paymentCharge Required for 1, 5 PaymentCharge
The details about the payment or partial payment that the fuel pump is requesting be submitted to the payment processor for processing and authorization.
FuelReceipt Required for 5 FuelReceipt
The collection of data that fully describes all the activity associated with a fuel purchase.
SecondaryIdentifier Required for 2 String
A randomly generated access code submitted by the mobile wallet user in conjunction with payment selection for the purpose of confirming a pre-authorization charge.
reconciliationInfo Required for 1, 5 ReconciliationInfo
Data that is delivered from the fuel site that is typically leveraged for reconciliation purposes.
storeLocationID Required for all flow rules String
Unique identifier of a specific acceptance location associated with a merchantId. See StoreLocationID in different methods for more information.
pumpNumber Required for all flow rules String
Number used to identify the pump dispensing the gas.

Response

Note: For successful transactions, use HTTP 200. For error conditions, use the HTTP code range 400/500. See http://en.wikipedia.org/wiki/List_of_HTTP_status_codes for more information.

Name Definition
messageHeader Required for all flow rules MessageHeader
Passes the property values that identify the calling service.
status Required for all flow rules Status Code
Statement returned from the WLW platform indicating whether the originating call failed or succeeded.
paymentResult Required for 1, 5 PaymentResult
The set of objects that represents each individual payment authorization made in conjunction with a pre-authorization transaction.
additionalPaymentResult Optional PaymentResult
Additional payment result object used to accommodate payments split across different payment types such as transactions using loyalty points.
paydiantTransactionRefId Required for all flow rules String
A unique transaction identifier generated by the WLW service. Once the WLW service returns a value for this attribute, the value must be included in all subsequent calls.

For example requests and responses, see the updateFuelEvent samples in both Use Cases and JSON Full Examples.

Settlement

An extended instance of the B2bRequest object that signals the Fuel Site’s closing of a specified transaction period and initiates settlement processing for the transactions that completed during the identified period.

POST
URL/b2b-gateway/settlement

Authentication: Required

Content Type: application/json

Request

Attribute Description
b2bRequest Required b2brequest
Includes the messageHeader attribute identifying the authorization credentials of the calling entity.
tenant Required Tenant
Identifies the WLW partner authorized to submit calls to the B2B gateway.
transactionInfo Required TransactionInfo
Encapsulates the details about the location in which the relevant settlement transactions are being processed.
settlementInfo Optional SettlementInfo
Details the settlement period and total amount of transactions included in the settlement period.

Response

Attribute Description
tenant Required TenantIdentifier
Identifies the WLW partner authorized to submit calls to the B2B gateway.
transactionInfo Required TransactionInfo
Encapsulates the details about the location in which the relevant settlement transactions are being processed.
settlementInfo Required SettlementInfo
Details the settlement period and total amount.
status Required Status Code
Details the outcome of the request.

For reference, see the settlement sample in JSON Full Examples.

pingGateway

Used to verify that the connection between the B2B Gateway and the fuel site is functioning properly to ensure that the transaction is not terminated due to a connection interruption. This functionality is typically used to eliminate connectivity as a factor during issue troubleshooting.

GET
URL/b2b-gateway/pinggateway

Authentication: Required

Request

echo ping b2b gateway request

Response

Status Code Description
200 (OK) Operation Successful
404 (SERVICE_UNAVAILABLE) Gateway Down / Incorrect URL
405 (METHOD_NOT_AVAILABLE) Method not available
503 (NOT_FOUND) Times out / Connection interrupted
500 (INTERNAL_SERVER_ERROR) Internal Server Error

retryUpdateFuelEvent

Retries a pre-auth capture that failed at the pump. Used by a customer care team to recover funds.

POST
URL/b2b-gateway/v2/transactions/retryfuelevent

Request

Extend B2bRequest to create a retryUpdateFuelRquest instance to submit to the API endpoint that includes:

Attribute Description
tenant Required TenantIdentifier
Identifies the fuel partner.
paydiantReferenceId Required String
WLW’s unique identifier of the transaction.
transactionFlowRule Required TransactionFlowRule
Indicates the flow rule of the transaction.
paymentCharge Optional PaymentCharge
The set of individual payment instances submitted by the mobile wallet toward completion of transaction payment in full.
fuelReceipt Optional FuelReceipt
Lists the specifics of this pay-at-the-pump transaction.
redeemedOffers Optional RedeemedOffer
Details of a discount or coupon that is included in this transaction.
SecondaryIdentifier Optional String
A randomly generated access code submitted by the mobile wallet user in conjunction with payment selection for the purpose of confirming a pre-authorization charge.
reconciliationInfo Optional ReconciliationInfo
Data that is delivered from the fuel site that is typically used for reconciliation purposes.
acceptanceLocationUri Required String
Unique URI that identifies the location where the transaction took place.
pumpNumber Required String
Fuel site's identification of the fuel pump where the transaction took place.

Response

Attribute Description
tenant Required TenantIdentifier
Identifies the fuel partner.
paymentResult Optional paymentResult
Defines the outcome of a specific payment authorization request.
additionalPaymentResults Optional paymentResult
Used to provide additional information about the payment result of the transaction being retried.
paydiantReferenceId Required String
WLW’s unique identifier of the transaction.

lookupTransaction

Used to retrieve the information about a transaction.

POST
URL/b2b-gateway/v2/transactions/lookup

Request

Extend B2bRequest to create a lookupTransaction instance to submit to the API endpoint that includes:

Attribute Description
paydiantReferenceId Required String
Unique identifier for the transaction with the WLW (Paydiant) platform.
tenant Required TenantIdentifier
Identifies the partner site where this transaction took place.

Response

Attribute Description
tenant Required TenantIdentifier
Identifies the partner site where this transaction took place.
paydiantReferenceId Required String
Unique identifier for the transaction with the WLW (Paydiant) platform.
acceptanceLocationUri Optional String
Unique URI that identifies the location where the transaction took place.
ticket Optional Ticket
A container for details about the merchant's request for payment.
externalEvents Optional ExternalEvent
Identifies an action that occurred outside the immediate transaction or mobile wallet that affects the processing of the transaction, such as a social media share that earns loyalty points.