B2B Mobile Transaction APIs - Methods

• B2B request and response structure
• B2B Status responses
• Alphabetical methods list
• By purpose methods list
• Methods

B2B request and response structure

All calls to the WLW B2B Gateway are structured by extending the API's root request and response data objects.

B2B requests

All calls to the B2B gateway must be passed as an extended instance of the B2BRequest root, which identifies the caller to the gateway. Each request instance must follow the naming convention <methodName>Request, as shown in the following updateMobileTransactionRequest sample excerpt.

1{
2"updateMobileTransactionRequest": {
3"messageHeader": {
4  "environmentId": "sandbox",
5  "versionId": "versionId",
6  "messageId": "messageId",
7  "partnerId": "partnerId"
8},
9}

B2B responses

The B2B Gateway returns a response instance using the same root structure. The B2BResponse object is the parent for all responses from the gateway, as shown in the following updateMobileTransactionResponse sample excerpt.

1{
2"updateMobileTransactionResponse": {
3"messageHeader": {
4  "partnerId": "partnerId",
5  "messageId": "messageId",
6  "versionId": "versionId",
7  "environmentId": "sandbox"
8},
9"status": {
10  "statusCode": "FAILED",
11  "statusDescription": "Failure",
12  "statusDetails": [ {
13    "statusCode": "370",
14    "statusDescription": "Tender not supported",
15    "statusType": "PLATFORM"
16  }]
17},
18"configurationDetails": [],
19}

B2B Status responses

Every response from the B2B Gateway includes a Status instance that communicates the outcome of the call using the following structure:

1"status": {
2"statusCode": "<var>Enum. Main Outcome</var>",
3"statusDescription": "<var>Description of the code</var>",
4"statusDetails": [ {
5  "statusCode": "<var>Raw Data</var>",
6  "statusDescription": "<var>Raw Data</var>",
7  "statusType": "<var>Enum. Origin of the status result</var>"
8}]
9},

The high level statusCode value identifies the overall outcome of the call as one of three possibilities; SUCCESS, PARTIAL_SUCCESS, or FAILED. Each of the platform components and external parties involved in the lifecycle of the call can contribute its own result, so the statusDetails attribute class contains the set of all results that contributed to the ultimate outcome as raw data, along with a statusType enum to identify whether the result originated within the platform or was passed by an external system.

For example, if a request fails at the gateway, the statusDetails will reflect the gateway error, such as:

1"statusDetails": [{
2"statusCode": "386",
3"statusDescription": "CreateCustomer Error",
4"statusType": "PLATFORM"
5}]

On the other hand, a call that completes successfully may include StatusDetail instances from both the platform and the external processor:

1"status": {
2"statusCode": "SUCCESS",
3"statusDescription": "Success",
4"statusDetails": [ {
5  "statusCode": "100",
6  "statusDescription": "Success",
7  "statusType": "PLATFORM"
8},
9{
10  "statusCode": "1000",
11  "statusDescription":"Approved",
12  "statusType": "EXTERNAL_PROCESSOR"
13}]
14},

In addition, certain calls may also contain more specific payment-related responses in the paymentResult attribute of any of the PaymentResult instances of the UpdateMobileTransaction response.

The endpoint descriptions in this chapter include a status section intended to list the various statuses that might be returned in the StatusDetails response for that call. See the Status Codes section of this guide for comprehensive lists of the different types of status codes.

Alphabetical methods list

• cancelMobileTransaction
• cancelPaymentAccountEnrollment
• continuePaymentAccountEnrollment
• createCustomer
• createDevice
• enrollCustomerAndProvisionCard
• invokeAdditionalProcess
• obtainMobileDeviceCheckoutToken
• refreshCustomerCardBalances
• releaseMobileDeviceCheckoutToken
• retrieveCustomer
• retrieveCustomerBlockedDevices
• retrieveCustomerCardInfo
• retrieveCustomerDevices
• retrieveIncompletePaymentAccountEnrollments
• retrieveMobileTransactionMetadata
• retrieveMobileTransactionMetadata webhook
• retrievePaginatedUserReceipts
• retrieveUserReceiptByPaydiantRefId
• startPaymentAccountEnrollment
• updateCustomer
• updateCustomerCard
• updateDeviceBlockStatus
• updateMobileTransaction

By purpose methods list

See Method documentation in the B2B Customer Care API Guide for information about abbreviations used in the method documentation descriptions.

cancelPaymentAccountEnrollment

Delete a pending payment account enrollment instance and cancel the pending registration of that account.

Request

Extend B2bRequest to create a cancelPaymentAccountEnrollmentRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to return a cancelPaymentAccountEnrollmentResponse instance populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the cancelPaymentAccountEnrollmentResponse.

cancelMobileTransaction

Abort a transaction that is in progress. WLW returns a confirmation of the cancelation result.

Request

Extend B2bRequest to create a cancelMobileTransactionRequest instance to pass to the API endpoint that includes:

Response

The extends B2bResponse to create a cancelMobileTransactionResponse with no additional attributes.

Status codes

The following status codes may be returned in the StatusDetails attribute of the cancelMobileTransactionResponse.

continuePaymentAccountEnrollment

Submit the additional information requested by the authorizer to continue a multi-step or single step in-progress payment account enrollment.

Request

Extend B2bRequest to create a continuePaymentAccountEnrollmentRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to create a continuePaymentAccountEnrollmentResponse populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the continuePaymentAccountEnrollmentResponse.

createCustomer

Associate a mobile wallet profile with a unique identity in the WLW platform that can engage in mobile transactions.

Request

Extend B2bRequest to create a createCustomerRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to create a createCustomerResponse populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the createCustomerResponse.

createDevice

Uniquely identify a mobile device in the WLW platform and associate it with a WLW customer identity.

Request

Extend B2bRequest to create a createDeviceRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to create a createDeviceResponse populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the createDeviceResponse.

enrollCustomerAndProvisionCard

Use an existing PayPal profile to register a customer and associated device in the WLW platform while automatically enrolling PayPal as a registered tender for the wallet.

Request

Extend B2bRequest to create a enrollCustomerAndProvisionCardRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to return a enrollCustomerAndProvisionCardResponse instance populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the enrollCustomerAndProvisionCardResponse.

invokeAdditionalProcess

Insert a secondary process into the flow of a transaction either before or after the principle payment authorization.

1POST /b2b-gateway/v2/transactions/mobile/additionalprocess

Request

Extend B2bRequest to create an invokeAdditionalProcessRequest object to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to return an invokeAdditionalProcessResponse instance populated with:

Status codes

THE Status instance returned in the invokeAdditionalProcessResponse will return a top level statusCode of SUCCESS OR FAILED, indicating the overall result of the call. This value is mapped by the connector based on the results from the external processor. The statusDetails instance will provide the underlying statuses from the platform and/or the external processor that contributed to the overall status result.

Additional process successfully executes:

Required data is missing:

Internal platform error caused failure:

Processor is unresponsive:

obtainMobileDeviceCheckoutToken

Request a checkout token that represents a newly-initiated transaction. This method returns a checkout token that can be used to generate a QR code, transmit a blue-tooth signal, or provide another means of secure transmission. The POS terminal can capture the checkout token and request to participate in the transaction.

Request

Extend B2bRequest to create an obtainMobileDeviceCheckoutTokenRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to create an obtainMobileDeviceCheckoutTokenResponse instance populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the obtainMobileDeviceCheckoutTokenResponse.

refreshCustomerCardBalances

Returns the current balances in the wallet of a specific customer.

Used to show the current balance to the wallet user in the app.

Request

Extend B2bRequest to create a refreshCustomerCardBalancesRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to create a refreshCustomerCardBalances with no additional attributes.

releaseMobileDeviceCheckoutToken

Cancel a generated checkout token that has not yet been scanned. This action is typically invoked when the app screen changes. For example, the user switches to the location finder from the pay screen or puts the app into the background by answering a phone call or text. WLW returns a confirmation of the release result.

Once a checkout token is released, it is no longer valid for transaction initiation. When the app focus returns to the payment screen, a new token must be requested using obtainMobileDeviceCheckoutToken.

Request

Extend B2bRequest to create a releaseMobileDeviceCheckoutTokenRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to create a releaseMobileDeviceCheckoutTokenResponse with no additional attributes.

Status codes

The following status codes may be returned in the StatusDetails attribute of the releaseMobileDeviceCheckoutTokenResponse.

retrieveCustomer

Returns the property values for a mobile wallet user profile. You can then use the returned values to pre-populate various fields in the app, such as address or zip code for a payment account enrollment, or to update certain profile properties.

Request

Extend B2bRequest to create a retrieveCustomerRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to return a retrieveCustomerResponseinstance populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the retrieveCustomerResponse.

retrieveCustomerBlockedDevices

Return the set of devices associated with a customer that have ever been blocked due to suspected fraudulent activity.

Request

Extend B2bRequest to create a retrieveCustomerBlockedDevicesRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to return a retrieveCustomerBlockedDevicesResponse instance populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the retrieveCustomerBlockedDevicesResponse.

retrieveCustomerCardInfo

Get the platform record for a specific payment account in the customer's mobile wallet; or leave the paymentAccountUri value empty to get the set of all payment accounts registered to the wallet.

Request

Extend B2bRequest to create a retrieveCustomerCardInfoRequest instance to pass to the API endpoint that includes:

Response

The platform extends the v1 B2bResponse to return a retrieveCustomerCardInfoResponse instance populated with:

retrieveCustomerDevices

Get the set of devices associated with a mobile wallet profile in the WLW platform. This information can provide identifying information about a device (such as deviceUri) required by other endpoints related to that device.

Request

Extend B2bRequest to create a retrieveCustomerDevicesRequest instance to pass with to API endpoint that includes:

Response

The Platform extends the v1 B2bResponse to return a retrieveCustomerDevicesResponse populated with:

retrieveIncompletePaymentAccountEnrollments

Get the set of payment account enrollments that were started but not completed. Use this method as a means to either resume or cancel the enrollment.

Request

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

Response

The Platform extends B2bResponse to return a retrieveIncompletePaymentAccountEnrollmentsResponse populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the retrieveIncompletePaymentAccountEnrollmentsResponse.

retrieveMobileTransactionMetadata

Get information from the platform that is necessary for the wallet to progress through the current step of the transaction, such as the list of supported tenders, recalculated amount due, event completion, etc.

In the DISCOVERY phase of the transaction, the wallet must obtain data such as the amount due, the merchant’s supported tenders, and other metadata, so the wallet user can determine how much to pay and what payment account to use to make the payment. retrieveTransactionMetadata enables the WLW platform to return the information that is needed for the specified step and any additional metadata required to complete the step, such as customer or fuel data.

Request

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

Response

The platform extends B2bResponse to return a retrieveMobileTransactionMetadataResponse instance populated with:

Status Codes

The following status codes may be returned in the StatusDetails attribute of the retrieveMobileTransactionMetadataResponse.

retrieveMobileTransactionMetadata webhook

In a standard implementation, the Merchant App Server submits a retrieveMobileTransactionMetadataRequest, then polls the WLW platform repeatedly for the response. The alternative webhook option allows the app server to simply consume lifecycle event notifications pushed from the platform. For this implementation, the Merchant creates the endpoint and provides WLW with the information it needs to configure the connector to use that endpoint.

To implement this technique of retrieving the transaction metadata:

• Create the new endpoint in the Merchant App Server as described here.
• Provide the new endpoint URL to WLW so it can be identified in your configuration property file.
• Configure the endpoint to use HTTPS and basic authentication.
• If your Merchant App Server does not use VPN, allowlist the endpoint so that it will accept only the WLW IP address. If the Merchant App Server uses VPN, allowlisting is not required.

When a LifeCycleEventType occurs, the WLW connector or data center calls the merchant's endpoint to push the metadata to the App Server. If the data is properly received, the Merchant App Server returns a standard HTTP success (200) response to WLW to acknowledge that the Merchant App Server successfully received the transaction metadata. If WLW does not receive the success response, WLW retries the push a configurable number of times before timing out.

If using the webhook push implementation, configure the transaction timeout to call the standard retrieveMobileTransactionMetadata with polling to retrieve the data.

See also Sample webhook payload for a sample payload that is an example of the data that is pushed for a FUEL_PUMP_ACTIVATED portion of the transaction. The data is pushed in a JSON object. Null fields are not sent.

retrieveMobileTransactionMetadata webhook push data

The following data is sent in the push notification as a JSON object when a relevant life cycle event for the transaction fires.

retrieveMobileTransactionMetadata webhook response

Configure a retrieveMobileTransactionMetadataResponse instance to return a statusCode value in response to the push.

retrievePaginatedUserReceipts

Get a set of receipts for a particular mobile wallet user for transactions that occurred within a specified range of time.

1POST /b2b-gateway/records/userreceipt/timeboxedpaginated

Request

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

Response

The platform extends B2bResponse to return a retrievePaginatedUserReceiptsResponse populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the retrievePaginatedUserReceiptsResponse.

retrieveUserReceiptByPaydiantRefId

Get the details for a specific receipt based on its unique transaction identifier.

Request

Issue a GET request, in which you specify the PaydiantTransactionRefId string value as an inline parameter of the URL.

Response

The platform extends B2bResponse to return a retrieveUserReceiptByPaydiantRefIdResponse populated with:

Status Codes

The following status codes may be returned in the StatusDetails attribute of the retrieveUserReceiptByPaydiantRefIdResponse.

retrieveSupportedTenderTypes

Get the set of tender types that the issuing partner has configured as supported payment accounts in the wallet and the metadata required for each one. This data allows you to present the user with a payment account enrollment form that is tailored to the type of account being added.

Request

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

Response

The platform extendsB2bResponse to return a retrieveSupportedTenderTypesResponse populated with:

startPaymentAccountEnrollment

Initiate the process to add a payment instrument to a mobile wallet as a valid tender.

Request

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

Response

The platform extends B2bResponse to return a startPaymentAccountEnrollmentResponse instance populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the startPaymentAccountEnrollmentsResponse.

updateCustomer

Change the editable properties of a mobile wallet user profile.

Request

Extend B2bRequest to create a updateCustomerRequest instance that includes:

Response

The platform extends B2bResponse to return a updateCustomerResponse instance with no additional payload.

Status codes

The following status codes may be returned in the StatusDetails attribute of the updateCustomerResponse.

updateCustomerCard

Used to update card metadata for tenders and accounts in a customer’s wallet.

This method works only when the Issuing partner has allowed cards to be updated.

Request

Extend B2bRequest to create a updateCustomerCardRequest instance to pass to the API endpoint that includes:

Response

The platform extends B2bResponse to return a updateCustomerCard instance populated with:

updateDeviceBlockStatus

Set a device's status to blocked or unblocked.

Request

Extend B2bRequest to create an updateDeviceBlockStatusRequest instance to submit to the API endpoint that includes:

Response

The platform extends B2bResponse to return an updateDeviceBlockStatusResponse populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the updateDeviceBlockStatusResponse.

updateMobileTransaction

Submit updated transaction data relevant to the current step (flow rule) of the transaction.

For example, in the SUBMIT_PAYMENT_TENDERS phase of the transaction, the wallet is expected to pass the payment account that the user has elected to use as tender for the transaction. WLW returns information that confirms receipt of the update and any additional metadata needed by the wallet to enable the next flow rule to operate.

Request

Extend B2bRequest to create an updateMobileTransactionRequest instance that includes:

Response

The platform extends B2bResponse to return an updateMobileTransactionResponse instance populated with:

Status codes

The following status codes may be returned in the StatusDetails attribute of the updateMobileTransactionResponse.

Next

• B2B Mobile Transaction Data Objects