Fuel API - Methods
Last updated: Aug 15th, 6:19am
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:
-
retrieveSiteInformation -
pumpAuthorization -
fuelCancel -
updateFuelEvent -
settlement -
pingGateway -
retryUpdateFuelEvent -
lookupTransaction
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
KeyValueSet of custom key value pairs that provide additional information or settings. |
fuelPumps |
Optional
FuelPumpArray representing available pumps at the site. |
latitude |
Optional String Latitude of the location. |
longitude |
Optional String Longitude of the location. |
siteResources |
Optional
SiteResourceArray representing other available services, such as car washes. |
status |
Required
Status CodeStatement 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
PaymentResultThe 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
transactionFlowRuleThe 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
PaymentChargeThe 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
FuelReceiptThe 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
ReconciliationInfoData 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
MessageHeaderPasses the property values that identify the calling service. |
status |
Required for all flow rules
Status CodeStatement returned from the WLW platform indicating whether the originating call failed or succeeded. |
paymentResult |
Required for 1, 5
PaymentResultThe set of objects that represents each individual payment authorization made in conjunction with a pre-authorization transaction. |
additionalPaymentResult |
Optional
PaymentResultAdditional 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.
POSTURL/b2b-gateway/settlement
Authentication: Required
Content Type: application/json
Request
| Attribute | Description |
|---|---|
b2bRequest |
Required
b2brequestIncludes the messageHeader attribute identifying the authorization credentials of the calling entity. |
tenant |
Required
TenantIdentifies the WLW partner authorized to submit calls to the B2B gateway. |
transactionInfo |
Required
TransactionInfoEncapsulates the details about the location in which the relevant settlement transactions are being processed. |
settlementInfo |
Optional
SettlementInfoDetails the settlement period and total amount of transactions included in the settlement period. |
Response
| Attribute | Description |
|---|---|
tenant |
Required
TenantIdentifierIdentifies the WLW partner authorized to submit calls to the B2B gateway. |
transactionInfo |
Required
TransactionInfoEncapsulates the details about the location in which the relevant settlement transactions are being processed. |
settlementInfo |
Required
SettlementInfoDetails the settlement period and total amount. |
status |
Required
Status CodeDetails 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.
GETURL/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.
POSTURL/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
TenantIdentifierIdentifies the fuel partner. |
paydiantReferenceId |
Required String WLW’s unique identifier of the transaction. |
transactionFlowRule |
Required
TransactionFlowRuleIndicates the flow rule of the transaction. |
paymentCharge |
Optional
PaymentChargeThe set of individual payment instances submitted by the mobile wallet toward completion of transaction payment in full. |
fuelReceipt |
Optional
FuelReceiptLists the specifics of this pay-at-the-pump transaction. |
redeemedOffers |
Optional
RedeemedOfferDetails 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
ReconciliationInfoData 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
TenantIdentifierIdentifies the fuel partner. |
paymentResult |
Optional
paymentResultDefines the outcome of a specific payment authorization request. |
additionalPaymentResults |
Optional
paymentResultUsed 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.
POSTURL/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
TenantIdentifierIdentifies the partner site where this transaction took place. |
Response
| Attribute | Description |
|---|---|
tenant |
Required
TenantIdentifierIdentifies 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
TicketA container for details about the merchant's request for payment. |
externalEvents |
Optional
ExternalEventIdentifies 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. |