B2B Mobile Transaction APIs - 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.

{
"updateMobileTransactionRequest": {
  "messageHeader": {
    "environmentId": "sandbox",
    "versionId": "versionId",
    "messageId": "messageId",
    "partnerId": "partnerId"
  },
}

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.

{
"updateMobileTransactionResponse": {
  "messageHeader": {
    "partnerId": "partnerId",
    "messageId": "messageId",
    "versionId": "versionId",
    "environmentId": "sandbox"
  },
  "status": {
    "statusCode": "FAILED",
    "statusDescription": "Failure",
    "statusDetails": [ {
      "statusCode": "370",
      "statusDescription": "Tender not supported",
      "statusType": "PLATFORM"
    }]
  },
  "configurationDetails": [],
}

B2B Status responses

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

"status": {
  "statusCode": "Enum. Main Outcome",
  "statusDescription": "Description of the code",
  "statusDetails": [ {
    "statusCode": "Raw Data",
    "statusDescription": "Raw Data",
    "statusType": "Enum. Origin of the status result"
  }]
},

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:

"statusDetails": [{
  "statusCode": "386",
  "statusDescription": "CreateCustomer Error",
  "statusType": "PLATFORM"
}]

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

"status": {
  "statusCode": "SUCCESS",
  "statusDescription": "Success",
  "statusDetails": [ {
    "statusCode": "100",
    "statusDescription": "Success",
    "statusType": "PLATFORM"
  },
  {
    "statusCode": "1000",
    "statusDescription":"Approved",
    "statusType": "EXTERNAL_PROCESSOR"
  }]
},

Note: This guide references some B2B API endpoints that were exposed prior to the Mobile Transaction API and return a Status object that uses a different data structure. Methods that return the earlier Status object are noted in this guide.

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

By purpose methods list

Purpose Name Description
Enrollment and Payment Accounts startPaymentAccountEnrollment Begin the payment account enrollment process.
continuePaymentAccountEnrollment Submit additional information requested by the authorizer to continue the payment account enrollment process.
refreshCustomerCardBalances Returns the current balances in the wallet of a specific customer.
retrieveIncompletePaymentAccountEnrollments Fetch any pending payment account enrollments.
cancelPaymentAccountEnrollment Stop a payment account enrollment.
retrieveCustomerCardInfo Fetch the set of payment accounts registered to a customer.
enrollCustomerAndProvisionCard Reserved for internal PayPal use at this time.
updateCustomerCard Used to update card metadata for tenders and accounts in a customer wallet.
Customers createCustomer Create a customer identifier in the WLW platform.
retrieveCustomer Look up a customer's WLW profile.
updateCustomer Edit a customer's WLW profile.
Devices createDevice Create a device identifier that is associated with a WLW customer profile.
retrieveCustomerDevices Fetch the set of devices associated with a WLW customer profile.
retrieveCustomerBlockedDevices Fetch a list of devices associated with a customer that have been blocked due to suspected fraudulent activity.
updateDeviceBlockStatus Set the status of a registered device to blocked or unblocked.
Tokens obtainMobileDeviceCheckoutToken Request a checkout token to initiate a WLW transaction.
releaseMobileDeviceCheckoutToken Clear a checkout token that was not paired with an acceptance terminal.
Transactions retrieveMobileTransactionMetadata
retrieveMobileTransactionMetadata webhook
Request updated data from the WLW platform based on the current step of the transaction.
updateMobileTransaction Submit updated data to the WLW platform based on the current step of the transaction.
invokeAdditionalProcess Insert a step into a transaction flow that is outside the standard payment authorization process.
Receipts retrievePaginatedUserReceipts Look up a set of receipts for a particular mobile wallet user for transactions that occurred within a specified range of time.
retrieveUserReceiptByPaydiantRefId Look up a specific receipt based on its unique identifier.
updateCustomerCard Edit the information of a customer's card.

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.

POST URL/b2b-gateway/v2/customers/cards/multistep/cancel

Request

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

Attribute Description
customerIdentifier Required EntityIdentifier
Identifies the customer initiating the enrollment.
deviceIdentifier Required EntityIdentifier
Identifies the device where the enrollment originated.
paydiantCorrelationId Required String
WLW’s identifier of the enrollment instance, as returned in the startPaymentAccountEnrollment response.

Response

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

Attribute Description
paydiantCorrelationId Required String
WLW’s identifier of the enrollment instance that was cancelled
customerIdentifier Required EntityIdentifier
Identifies the customer initiating the enrollment.
deviceIdentifier Required EntityIdentifier
Identifies the device where the enrollment originated.

Status codes

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

Status Code Description
100 SUCCESS
The enrollment cancelation was successful.
300 FAILURE
A generic failure occurred.
301 ENTITY_NOT_EXISTING
The enrollment specified in the request could not be found.
304 INVALID_ARGUMENTS
Arguments specified in the request are not valid.
386 ERROR
Unrecoverable error occurred.

cancelMobileTransaction

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

POST URL/b2b-gateway/v2/transactions/mobile/cancel

Request

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

Attribute Description
tenant Required TenantIdentifier
Defines the WLW tenant used to issue the mobile wallet app.
customerUri Required String
WLW’s unique identifier for the user of the mobile wallet associated with the device.
deviceUri Required String
WLW’s unique identifier for the mobile device that is associated with a mobile wallet user in the WLW platform. See note below.
deviceUniqueId Required String
The device manufacturer’s unique identifier for the device, which is collected when the device is linked with wallet registration. See note below.
paydiantReferenceId Optional String
WLW’s unique identifier of the transaction.

Note: For deviceUri and deviceUniqueId: The value needs to be unique to the device but the value does not have to match the value generated by the WLW platform. It can be a unique value from the device or an external ID unique for each device. If you do not use a WLW value, use this format:

deviceUniqueId = UUID of the device or some external ID unique for the device
deviceUri = <client_name>:<device_type>#<deviceUniqueId>

For example: deviceUri = bp.uk.bpme:android#342d233211

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.

Status Code Description
100 SUCCESS
The transaction cancelation was successful.
304 INVALID_ARGUMENTS
Arguments specified in the request are not valid.
386 ERROR
An unrecoverable error occurred.

continuePaymentAccountEnrollment

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

PUT URL/b2b-gateway/v2/customers/cards/multistep

Request

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

Attribute Description
customerIdentifier Required EntityIdentifier
Identifies the customer initiating the enrollment.
enrollmentInformation Required PaymentAccountEnrollmentInformation
A summary of the in-progress enrollment details which should include populated values for the AdditionalData properties requested in the enrollment response.
deviceIdentifier Required EntityIdentifier
Identifies the device where the enrollment originated.

Response

The platform extends B2bResponse to create a continuePaymentAccountEnrollmentResponse populated with:

Attribute Description
enrollmentInformation Required PaymentAccountEnrollmentInformation
A summary of the in-progress enrollment details. The enrollmentState attribute of this object indicates whether the enrollment has completed in this step (END) or requires secondary details in order to continue (MORE_INFO).
customerIdentifier Required EntityIdentifier
Identifies the wallet user profile for this transaction.
deviceIdentifier Required EntityIdentifier
Identifies the device where the enrollment originated.

Status codes

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

Status Code Description
100 SUCCESS
The enrollment continued successfully.
304 INVALID_ARGUMENTS
Arguments specified in the request are not valid.
386 ERROR
An unrecoverable error occurred.

createCustomer

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

Note: All transactions must identify a valid WLW customer and device, but device and identity authentication and verification is the responsibility of the Issuer’s application service layer.

POST URL/b2b-gateway/v2/customers

Request

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

Attribute Description
customer Required Customer
Provides user profile information of the device owner.

Response

The platform extends B2bResponse to create a createCustomerResponse populated with:

Attribute Description
customerUri Optional String
WLW’s unique identifier for the customer wallet profile that was just created.

Status codes

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

Status Code Description
100 SUCCESS
The customer profile was created successfully.
304 INVALID_ARGUMENTS
External ID cannot be NULL.
Arguments specified in the request are not valid.
386 ERROR
An unrecoverable error occurred.
389 ISSUING_PARTNER_DOES_NOT_ALLOW_STUB_ACCOUNTS
Issuing Partner is not configured to support stub customer records.
423 CUSTOMER ALREADY EXISTS

createDevice

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

Note: You do not need to create the device on the WLW Platform.

POST URL/b2b-gateway/v2/customers/devices

Request

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

Attribute Description
deviceExternalId Required String
The external system's unique identifier of the device that is coordinating the transaction through the B2B Gateway.
customerUri Contextual String
WLW’s unique identifier of the mobile wallet user associated with the device. The customer must be identified to the system using either this property or the customerExternalId property.
customerExternalId Contextual String
The external system’s unique identifier of the mobile wallet user associated with the device. You must identify the customer using either this property or the customerUri property.
partnerUri Required String
WLW’s unique identifier for a business entity that has been onboarded to the WLW platform in order to participate in mobile transactions.
issuingPartnerUri Required String
WLW’s unique identifier of a partner that is configured to issue a mobile wallet.
deviceTypeUniqueName Required String
Identifies the device platform. Valid responses are iphone or android.

Response

The platform extends B2bResponse to create a createDeviceResponse populated with:

Attribute Description
device Otional Device
The device profile created in the WLW platform.

Status codes

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

Status Code Description
100 SUCCESS
The device profile was created successfully.
304 INVALID_ARGUMENTS
Arguments specified in the request are not valid.
386 ERROR
An unrecoverable error occurred.
389 ISSUING_PARTNER_DOES_NOT_ALLOW_STUB_ACCOUNTS
Issuing Partner is not configured to support stub device records.

enrollCustomerAndProvisionCard

Note: This endpoint is only available for select partners. Contact your WLW representative before developing against it.

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.

POST URL/b2b-gateway/v2/customers/devices/wallet

Request

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

Attribute Description
customer Required Customer
Provides user profile information of the device owner.
device Required Device
Provides identifying information about the mobile device where the app is installed.
paymentAccount Required PaymentAccount
Information that describes the method of payment available to the wallet.

Response

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

Attribute Description
customer Required Customer
Provides user profile information of the device owner.
device Required Device
Provides identifying information about the mobile device where the app is installed.
paymentAccount Required PaymentAccount
Information that describes the method of payment available to the wallet.

Status codes

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

StatusCode Description
100 SUCCESS
Customer, device, and wallet enrollment was successful.
304 INVALID_ARGUMENTS
The arguments in the request were not valid.
370 TENDER_NOT_SUPPORTED
The Issuer has not configured support for the specified tender.
386 ERROR
An unrecoverable error has occurred.
389 ISSUING_PARTNER_DOES_NOT_ALLOW_STUB_ACCOUNTS
The Issuing Partner has not been set up to accept stub customers or devices.
523 PAYMENT_ACCOUNT_ENROLLMENT_CARD_PROVISIONING_DECLINED
The card used to enroll this account was not accepted.
524 PAYMENT_ACCOUNT_ENROLLMENT_CARD_PROVISIONING_NOT_SUPPORTED
The card used to enroll this account does not allow provisioning.
525 PAYMENT_ACCOUNT_ENROLLMENT_CRUD_NOT_POSSIBLE
Payment account enrollment does not allow CRUD (create, read, update, or delete) so the operation failed.

invokeAdditionalProcess

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

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

Request

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

Attribute Description
tenantIdentifier Required TenantIdentifier
Identifies the WLW partner authorized to submit calls to the B2B Gateway.
additionalProcessInfo Required AdditionalProcessInfo
The set of key/value properties relevant to the additional process.

Response

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

Attribute Description
tenantIdentifier Required TenantIdentifier
Identifies the WLW partner that originated the request.
additionalProcessInfo Required AdditionalProcessInfo
The set of key/value properties relevant to the additional process.

Note: The properties defined in the additionalProcessInfo.additionalInformation instance in the response will not necessarily match those in the request instance of the same object. The response instance may echo the properties of the request, as well as include additional properties added by the connector, or have only properties added by the connector, or even be empty, depending on the connector configuration.

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:

Code Details Code Message Type
SUCCESS The Transaction's additional processing was successful.
830 SUCCESS PLATFORM connector response
120 PARTIAL_SUCCESS EXTERNAL_PROCESSOR processor response
200 OK EXTERNAL_PROCESSOR processor gateway response

Required data is missing:

Code Details Code Message Type
FAILED The Transaction's additional processing failed.
831 FAILED PLATFORMconnector response
250 Invalid values specified. PLATFORM connector response
304 Invalid arguments EXTERNAL_PROCESSOR processor response

Internal platform error caused failure:

Code Details Code Message Type
FAILED The Transaction's additional processing failed.
831 FAILED PLATFORM connector response
241 Processing error occurred. PLATFORM internal component

Processor is unresponsive:

Code Details Code Message Type
FAILED The Transaction's additional processing failed.
831 Transaction additional processing failed. PLATFORM connector response
242 Processing error occurred at gateway. PLATFORM connector response

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.

POST URL/b2b-gateway/v2/transactions/mobile/token

Request

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

Attribute Description
tenant Required TenantIdentifier
Defines the WLW tenant used to issue the mobile wallet app.
customerUri Required String
WLW’s unique identifier for the user of the mobile wallet associated with the device.
deviceUri Required String
WLW’s unique identifier for the mobile device that is associated with a mobile wallet user in the WLW platform. See note below.
deviceUniqueId Required String
The device manufacturer’s unique identifier for the device, which is collected when the device is linked with wallet registration. See note below.
checkoutTokenType Optional checkoutTokenType Enum
Identifies the transaction type of the requested token. Valid values are:
PURCHASE - A standard payment or non-referenced refund.
REFUND - A standard or non-paired refund.
OFFER - A scannable offer.
CASH_ACCESS - A banking transaction with an ATM.
FUEL - A gas station transaction with a fuel pump.
paydiantReferenceId Optional String
WLW’s unique identifier of the transaction.

Note: For deviceUri and deviceUniqueId: The value needs to be unique to the device but the value does not have to match the value generated by the WLW platform. It can be a unique value from the device or an external ID unique for each device. If you do not use a WLW value, use this format:

deviceUniqueId = UUID of the device or some external ID unique for the device
deviceUri = <client_name>:<device_type>#<deviceUniqueId>

For example: deviceUri = bp.uk.bpme:android#342d233211

Response

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

Attribute Description
checkoutToken Optional checkoutToken
The checkout token generated to initiate the transaction from the mobile device for the transaction type specified.

Status codes

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

StatusCode Description
100 SUCCESS
The checkout token generation was successful.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
386 ERROR
An unrecoverable error occurred.

refreshCustomerCardBalances

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

POST URL/b2b-gateway/v2/customers/wallet/balances

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:

Attribute Description
customerUri Required String
The unique identifier of a registered mobile wallet user.
issuingPartnerUri Required String
The unique identifier of the WLW partner that issued the mobile payments app where the wallet is registered.
partnerUri Required String
The unique identifier of the WLW partner under which the issuer is registered.
cardUris Optional String
The unique identifiers for the cards to be refreshed.

Response

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

Attribute Description
accountBalances Optional AccountBalance
The set of objects that define each account’s current balance.
StatusCode Description
100 SUCCESS
The checkout token generation was successful.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
Issuing Partner URI cannot be NULL
Partner URI cannot be NULL
Failed to retrieve card info for: (card number)
386 ERROR
(500)Request time out
Logged in user doesn't have access to the tenant provided.
Null Result returned from paymentAccountManagerService.refreshCustomerCardBalances.

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.

POST URL/b2b-gateway/v2/transactions/mobile/token/release

Request

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

Attribute Description
tenant Required TenantIdentifier
Defines the WLW tenant used to issue the mobile wallet app.
customerUri Required String
WLW’s unique identifier for the user of the mobile wallet associated with the device.
deviceUri Required String
WLW’s unique identifier for the mobile device that is associated with a mobile wallet user in the WLW platform. See note below.
deviceUniqueId Required String
The device manufacturer’s unique identifier for the device, which is collected when the device is linked with wallet registration. See note below.
checkoutTokenValue Required String
The value of the checkout token being released.

Note: For deviceUri and deviceUniqueId: The value needs to be unique to the device but the value does not have to match the value generated by the WLW platform. It can be a unique value from the device or an external ID unique for each device. If you do not use a WLW value, use this format:

deviceUniqueId = UUID of the device or some external ID unique for the device
deviceUri = <client_name>:<device_type>#<deviceUniqueId>

For example: deviceUri = bp.uk.bpme:android#342d233211

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.

StatusCode Description
100 SUCCESS
The checkout token was released successfully.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
386 ERROR
An unrecoverable error occurred.

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.

POST URL/b2b-gateway/v2/customers/retrieve

Request

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

Attribute Description
customerUri Contextual String
WLW’s unique identifier for the customer wallet profile that was just created.
externalId Contextual String
Unique identifier for the wallet user within another repository that has been included as part of the WLW profile.
tenantUri Required String
WLW’s unique identifier for an entity of a registered partner. As a tenant, the entity can either develop a mobile wallet (issuing tenant) or accept payments from a mobile wallet (acceptance or merchant tenant).
partnerUri Required String
WLW’s unique identifier for a business entity that has been onboarded to the WLW platform in order to participate in mobile transactions.

Note: customerUri and externalId are each optional, but one of them must be included as the identifying search parameter for the user.

Response

The platform extends B2bResponse to return a retrieveCustomerResponseinstance populated with:

Attribute Description
active Required Boolean
Indicates whether the wallet is functional (true), or disabled or locked (false).
createDate Require DateTime
A timestamp that indicates when the wallet profile was created in the WLW system.
modifiedTime Required DateTime
A timestamp that indicates the most recent time at which changes were saved to the wallet profile.
tenantName Required String
The name of the WLW partner that issued the wallet.
customerId Optional String
A secondary identifier for the wallet user in another system.
stub Optional Boolean
Indicates whether the user profile is a "guest" account that is not validated by WLW’s Security Manager.
true - this is a minimal user profile that is not validated by WLW's Security Manager.
false - This is a full user profile validated by WLW's Security Manager.
customer Optional Customer
Defines the wallet user profile properties.

Status codes

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

StatusCode Description
100 SUCCESS
The customer record was obtained successfully.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
386 ERROR
An unrecoverable error occurred.

retrieveCustomerBlockedDevices

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

GET URL/b2b-gateway/v2/customers/devices/block/search

Request

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

Attribute Description
customerUri Optional String
The unique identifier of a registered mobile wallet user.
customerExternalId Optional String
A unique identifier for the mobile wallet user known in the issuer's system.
partnerUri Required String
The unique identifier of the WLW partner under which the issuer is registered.
issuingPartnerUri Required String
The unique identifier of the WLW partner that issued the mobile payments app where the wallet is registered.

Note: Although both customerUri and customerExternalId are both optional, one or the other must be included as the customer search parameter.

Response

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

Attribute Description
customerDevices Optional Array: CustomerDevice
The set of device instances associated with the specified customer that have ever been blocked due to suspected fraud.

Status codes

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

StatusCode Description
100 SUCCESS
The set of blocked devices was retrieved successfully.
301 ENTITY_NOT_EXISTING
The specified customer does not exist in the system. Recheck the identifiers in the request.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
316 INVALID_CUSTOMER_URI
The customerUri specified in the request is not valid.
322 INVALID_ISSUING_PARTNER_URI
A valid issuing partner identifier is required.
386 ERROR
An unrecoverable error occurred.
388 CUSTOMER_NOT_FOUND
The specified customer could not be located.
389 ISSUING_PARTNER_DOES_NOT_ALLOW_STUB_ACCOUNTS
The issuing partner is not configured to permit stub customer records.

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.

Note: This is a v1 method that returns the v1 Status object in the response.

POST URL/b2b-gateway/customers/cards/search

Request

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

Attribute Description
customerUri Required String
The unique identifier of a registered mobile wallet user.
issuingPartnerUri Required String
The unique identifier of the WLW partner that issued the mobile payments app where the wallet is registered.
partnerUri Required String
The unique identifier of the WLW partner under which the issuer is registered.
paymentAccountUri Required String
The unique identifier of a specific payment account. Pass a null value for this attribute to get the set of all payment accounts.
applicationId Optional String
ID of an application used by the wallet. You can get the appId for the wallet from your Professional Services representative. If your application uses an appId, this field is required.
includeMetaData Required Boolean
Indicates if the metadata associated with this card will be included in the return. Must be in lowercase: true or false.
deviceUri Optional String
The unique identifier of the device where this card is stored.

Response

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

Attribute Description
paymentResponse Required PaymentResponse
Extends the
cards Optional Array:Card
The set of payment account records in the platform that match the identifier data in the request.
includeMetaData Required Boolean
Indicates if the metadata associated with this card is included in the return.
true - Metadata is included
false - Metadata is omitted. Must be in lowercase.
customerUri Required String
The unique identifier of the account owner of the card data in the response.
paymentAccountUri Required String
The unique identifier of the card data in the response.

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.

Note: This is a V1 method that returns the V1 Status object in the response.

POST URL/b2b-gateway/customers/devices/search

Request

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

Attribute Description
customerUri Contextual String
WLW’s unique identifier of the mobile wallet user associated with the device. The customer must be identified to the system using either this property or the customerExternalId property.
externalId Contextual String
The external system’s unique identifier of the mobile wallet user associated with the device. You must identify the customer using either this property or the customerUri property.
issuingPartnerUri Required String
WLW’s unique identifier of a partner that is configured to issue a mobile wallet.

Response

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

Attribute Description
customerDevices Optional Array: CustomerDevice
The set of device instances associated with the specified customer’s mobile wallet.

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.

POST URL/b2b-gateway/v2/customers/cards/multistep/search

Request

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

Attribute Description
customerIdentifier Required EntityIdentifier
Identifies the customer initiating the enrollment.
deviceIdentifier Optional EntityIdentifier
Identifies the device where the enrollment originated.

Response

The Platform extends B2bResponse to return a retrieveIncompletePaymentAccountEnrollmentsResponse populated with:

Attribute Description
enrollmentInformation Required PaymentAccountEnrollmentInformation
A summary of the in-progress enrollment details. The enrollmentState for each instance indicates whether the enrollment is waiting for additional data in order to continue (MORE_INFO) or if the allowed time to continue has elapsed (EXPIRED).
customerIdentifier Required EntityIdentifier
Identifies the customer initiating the enrollment.
deviceIdentifier Required EntityIdentifier
Identifies the device where the enrollment originated.

Status codes

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

StatusCode Description
100 SUCCESS
The operation was successful.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
386 ERROR
An unrecoverable error occurred.

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.

Note: See retrieveMobileTransactionMetadata Webhook to learn how to allow WLW to push event data instead of polling for it. The polling method is a fallback if the push cannot be completed, so if you implement the non-polling method, you must also implement the polling method as a fallback.

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.

POST URL/b2b-gateway/v2/transactions/mobile/metadata

Request

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

Attribute Description
tenant Required TenantIdentifier Defines the WLW tenant used to issue the mobile wallet app.
customerUri Required String
WLW’s unique identifier for the user of the mobile wallet associated with the device.
deviceUri Required String
WLW’s unique identifier for the mobile device that is associated with a mobile wallet user in the WLW platform. See note below.
deviceUniqueId Required String
The device manufacturer’s unique identifier for the device, which is collected when the device is linked with wallet registration. See note below.
checkoutTokenValue Optional String
The value of the token issued to initiate the transaction.
paydiantReferenceId Optional String
WLW’s unique identifier of the transaction.
receiptParameters Optional ReceiptParameters
Defines the filter to use when retrieving receipts.
offerParameters Optional OfferParameters
Defines the filter to use when retrieving eligible offers.
executingFlowRule Required MobileTransactionFlowRule Enum
Identifies the stage of the transaction for this request.
discoveryType Optional DiscoveryType
Identifies the type of transaction so that during DISCOVERY the property values returned are appropriate for that type of transaction.
siteCheckInDetail Optional SiteCheckInDetail
Returns the parameters that identify a fuel site within range of the mobile device. Used, for example, in a fuel transaction to retrieve fuel-site-specific data, such as pump availability.
invoiceId Optional String
The Acceptance Location’s identifier of the bill or other request for payment presented to the user.

Note: For deviceUri and deviceUniqueId: The value needs to be unique to the device but the value does not have to match the value generated by the WLW platform. It can be a unique value from the device or an external ID unique for each device. If you do not use a WLW value, use this format:

deviceUniqueId = UUID of the device or some external ID unique for the device
deviceUri = <client_name>:<device_type>#<deviceUniqueId>

For example: deviceUri = bp.uk.bpme:android#342d233211

Response

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

Attribute Description
refundableReceipts Optional RefundableReceipts
The set of receipts for prior transactions that can be refunded based on the refund criteria at the current Acceptance Location.
eligibleOffers Optional EligibleOffers
The set of active offers in the wallet that qualify for redemption in the current transaction.
transactionMetaData Optional TransactionMetaData
The data passed by the Acceptance Location required to start a transaction at that location, such as supported payment tenders, loyalty programs, offers, and other location-specific metadata.
transactionStatus Optional TransactionStatus
The state of the transaction in WLW’s transaction manager at the time of this response.
transactionDetail Optional MobileTransactionDetail
Defines the elements that have been processed at this point in the transaction’s life cycle.
nextExecutingFlowRule Optional MobileTransactionFlowRule Enum
The flow rule that will execute upon completion of the current flow rule. The flow rule process is based on the life cycle configuration for the transaction type.
currentExecutingFlowRule Required MobileTransactionFlowRule Enum
Indicates the current step of the transaction’s life cycle that is processing.
transactionFlowRuleSpcifications Optional TransactionFlowRuleSpecification
Details that define how the current flow rule must complete in order to be successful. The flow rule specification responds to the dynamic transaction conditions.
checkoutToken Optional checkoutToken
The token instance generated to initiate the transaction. Once this value is returned by the platform, it is then required in all subsequent calls related to the transaction.
paydiantReferenceId Optional String
WLW’s unique identifier for the transaction.
nextTransactionFlowRuleSpecification Optional TransactionFlowRuleSpecification
The handling instruction that triggers the next flow rule in the transaction process once the current flow rule completes.
discoveryType Optional DiscoveryType
Identifies the type of transaction so that during DISCOVERY the property values returned are appropriate for that type of transaction.
externalEvents Optional ExternalEvents.
Identifies the set of actions that occurred outside the immediate transaction or mobile wallet that affect the processing of the transaction, such as a social media share that earns loyalty points.

Status Codes

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

StatusCode Description
100 SUCCESS
The operation was successful.
304 INVALID_ARGUMENTS
The arguments in the request were not valid.
309 INVALID_CHECKOUT_TOKEN
The checkout token is not valid. It can have expired or was not generated properly.
337 NO_TRANSACTION_DETAILS_FOUND
The transaction details related to the request are not available.
341 TRANSACTION_CANCELED
The transaction was stopped from completing.
347 TRANSACTION_IN_USE
The referenced transaction is processing and data is not available.
360 OPERATION_TIMEOUT
The request expired due to unresponsiveness.
361 CHECKOUT_TOKEN_BLOCKED
The checkout token cannot be used for this transaction.
385 TRANSACTION_NOT_READY
Data for the transaction is not yet available.
386 ERROR
An unrecoverable error occurred during processing.
391 EXTERNAL_ENTITY_NOT_FOUND
An external entity relevant to the operation was not located.
427 INVALID_EXTERNAL_ENTITY_STATE
The external entity is in an invalid state for the operation.

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, whitelist the endpoint so that it will accept only the WLW IP address. If the Merchant App Server uses VPN, whitelisting 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.

Attribute Description
metadata Required Metadata Object
Stores the transaction details.
transactionMetaData Optional TransactionMetaData Object
Defines any metadata needed for the transaction.
transactionStatus Optional TransactionStatus Enum
Indicates the current status of the transaction.
checkoutToken Optional CheckoutToken Object
Defines the value and type for the checkout token for this transaction.
paydiantReferenceId Optional String
WLW's unique identifier for the transaction.
externalEvents Optional ExternalEvent Object
Defines any additional data and the external event type.

retrieveMobileTransactionMetadata webhook response

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

Attribute Description
statusCode Required StatusCode Enum
Indicates if the data was properly received at the Merchant App endpoint. Valid values are:
SUCCESS
PARTIAL_SUCCESS
FAILED

retrievePaginatedUserReceipts

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

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

Request

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

Attribute Description
partnerUri Required String
The unique identifier of the WLW partner under which the issuer is registered.
issuingPartnerUri Required String
The unique identifier of the WLW partner that issued the mobile payments app where the wallet is registered.
customerUri Required String
The unique identifier of a registered mobile wallet user.
startDate Required dateTime
Timestamp that begins the range in which returned receipts fall, based on the time of the transaction completion. dateTime uses yyyy-MM-dd hh:mm:ss format in UTC time (no offset from GMT). For example, 2018-07-23 12:00:00.
endDate Required dateTime
Timestamp that ends the range in which returned offers fall, based on the time of the transaction completion. dateTime uses yyyy-MM-dd hh:mm:ss format in UTC time (no offset from GMT). For example. 2018-07-23 12:00:00.
startIndex Required Integer
Filters the set of returned receipts to omit any receipts before this record number.
maxRowsToReturn Required Integer
Restricts the number of returned receipts to this number.

Response

The platform extends B2bResponse to return a retrievePaginatedUserReceiptsResponse populated with:

Attribute Description
receiptList Required Array: UserReceipt
The set of transaction receipts that met the filtering criteria specified in the request.

Status codes

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

StatusCode Description
100 SUCCESS
The operation was successful.
404 RESOURCE_NOT_FOUND
There was a problem retrieving a resource.

retrieveUserReceiptByPaydiantRefId

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

GET URL/b2b-gateway/records/userreceipts/pydtRefId

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:

Attribute Description
receipt Required userReceipt
Provides details of the requested receipt.

Status Codes

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

StatusCode Description
100 SUCCESS
The operation was successful.
404 RESOURCE_NOT_FOUND
There was a problem retrieving a resource.

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.

Note: This is a V1 method that returns the V1 Status object in the response.

POST URL/b2b-gateway/partners/tendertypes/search

Request

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

Attribute Description
tenantUri Required String
Unique identifier used to indicate this partner for single gateway tenancy.
partnerUri Required String
The unique identifier of the WLW partner under which the issuer is registered.

Note: The following attributes are Optional search criteria that can be used to filter the results.

Attribute Description
paymentNetworkTypeUri Optional String
Unique identifier that identifies the type of payment network for this account.
paymentAccountTypeUri Optional String
Unique identifier for the kind of account, for example, "Credit Card."
provisioningSupportedOnly Optional Boolean
Indicates if only the tender types that support provisioning are returned. These are account types that allow new payment account generation through the wallet. Valid values are:
true - include only tender types that support provisioning
false - tender types that do not support provisioning can also be returned
applicationId Contextual String
ID of an application used by the wallet. You can get the appId for the wallet from your Professional Services representative. If your application uses an appId, this field is Required.

Response

The platform extendsB2bResponse to return a retrieveSupportedTenderTypesResponse populated with:

Attribute Description
tenderTypes Optional Array:TenderType
The set of tender types supported for the wallet.

startPaymentAccountEnrollment

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

POST URL/b2b-gateway/v2/customers/cards/multistep

Request

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

Attribute Description
enrollmentType Required Enum found in PaymentAccountEnrollmentType
Indicates where WLW or an external system retains the PAN (Payment Card Number) data for the payment account. Valid values are:
LINK - Value sent in the CARD_NUMBER field is stored in the WLW platform.
PROVISION - Value sent in the CARD_NUMBER field is stored by the authorizing party and a tokenized replacement is stored in WLW’s system.
customerIdentifier Required EntityIdentifier
Identifies the customer initiating the enrollment.
deviceIdentifier Required EntityIdentifier
An instance that identifies the device from which the enrollment originated. Note that when the EntityIdentifier uri identifies a device, the uri is required.
paymentAccount Required PaymentAccount Details about the Payment Account being enrolled.

Response

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

Attribute Description
enrollmentInformation Required PaymentAccountEnrollmentInformation
A summary of the in-progress enrollment details. The enrollmentState attribute of this object indicates whether the enrollment has completed in this step (END) or requires secondary details in order to continue (MORE_INFO).
customerIdentifier Required EntityIdentifier
Identifies the customer initiating the enrollment.
deviceIdentifier Required EntityIdentifier
Identifies the device from which the enrollment originated.
paymentAccount Optional PaymentAccount Details about the Payment Account being enrolled.

Status codes

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

StatusCode Description
100 SUCCESS
The enrollment was initiated successfully.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
386 ERROR
An unrecoverable error occurred.

updateCustomer

Change the editable properties of a mobile wallet user profile.

PUT URL/b2b-gateway/v2/customers

Request

Extend B2bRequest to create a updateCustomerRequest instance that includes:

Attribute Description
customer Required Customer
The user profile with edited values that is to replace the existing record.

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.

StatusCode Description
100 SUCCESS
The enrollment was initiated successfully.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
386 ERROR
An unrecoverable error occurred.
389 ISSUING_PARTNER_DOES_NOT_ALLOW_STUB_ACCOUNTS
Unable to write to the record because the issuing partner does not allow stub customer records.

updateCustomerCard

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

PUT URL/b2b-gateway/v2/customers/cards

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:

Attribute Description
cardUri Required String
The unique identifier of a card in the customer’s mobile wallet.
deviceUri Optional String
The unique identifier of the device where the mobile wallet app using this card is installed.
customerUri Required String
The unique identifier of a registered mobile wallet user.
applicationId Required String
Identifies the specific wallet app build used by this wallet. You can get the appId for this wallet from your Professional Services representative. If your application does not use an appId, this field is optional.
issuingPartnerUri Required String
The unique identifier of the WLW partner that issued the mobile payments app where the wallet is registered.
partnerUri Required String
The unique identifier of the WLW partner under which the issuer is registered.
cardDetails One or more required CardDetails
Communicates additional information relevant to the outcome of the call as a set of key/value pairs.

Response

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

Attribute Description
cardUri Required String
The unique identifier of a card in the customer’s mobile wallet.
verificationType Required String
Indicates the type of response. Valid values are:
SIMPLE_AUTH
SIMPLE_BALANCE_REQUEST
BIN_NUMBER
DOUBLE_DEPOSIT
NO_VALIDATION
StatusCode Description
100 SUCCESS
Successfully refreshed customer balances.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
386 ERROR
An unrecoverable error occurred.
Card URI cannot be NULL.
Issuing Partner URI cannot be null.
Partner URI cannot be null.
Failed to retrieve card info for (card number)
No response when retrieving the unencrypted card.
386 FAILED
Request timed out.
Logged in user doesn't have access to the tenant provided.
Null result returned from paymentAccountManagerService updateCard.
389 ISSUING_PARTNER_DOES_NOT_ALLOW_STUB_ACCOUNTS
Unable to write to the record because the issuing partner does not allow stub customer records.

updateDeviceBlockStatus

Set a device's status to blocked or unblocked.

Note: This method can be used only when the device has been created on the WLW platform.

PUT URL/b2b-gateway/v2/customers/devices/block

Request

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

Attribute Description
issuingPartnerUri Required String
The unique identifier of the WLW partner that issued the mobile payments app where the wallet is registered.
partnerUri Required String
The unique identifier of the WLW partner under which the issuer is registered.
deviceUri Required String
The unique identifier of a device. A valid deviceUri is needed to unblock a device. Must be generated on the WLW Platform.
blocked Required Boolean
Sets the status of the specified device to blocked (TRUE) or unblocked (FALSE).
auditInfo Optional AuditInfo
Identifies the event that triggered the status update, such as a fraud alert.

Response

The platform extends B2bResponse to return an updateDeviceBlockStatusResponse populated with:

Attribute Description
block Required Boolean
Indicates current status of the device.

Status codes

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

StatusCode Description
100 SUCCESS
The enrollment was initiated successfully.
304 INVALID_ARGUMENTS
Arguments in the request are not valid.
386 ERROR
An unrecoverable error occurred.
344 DEVICE_NOT_FOUND
The device identified in the request could not be located in the system.

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.

POST URL/b2b-gateway/v2/transactions/mobile/update

Request

Extend B2bRequest to create an updateMobileTransactionRequest instance that includes:

Attribute Description
tenant Required TenantIdentifier Defines the WLW tenant used to issue the mobile wallet app.
customerUri Required String
WLW’s unique identifier for the user of the mobile wallet associated with the device.
deviceUri Required String
WLW’s unique identifier for the mobile device that is associated with a mobile wallet user in the WLW platform. See note below.
deviceUniqueId Required String
The device manufacturer’s unique identifier for the device, which is collected when the device is linked with wallet registration. See note below.
checkoutTokenValue Optional String
The decoded value of the token issued to initiate the transaction.
paydiantReferenceId Optional String
WLW’s unique identifier of the transaction.
selectedPaymentInstruments OptionalPaymentInstrument
A set of supported payment accounts designated by the wallet user as tender available for use in the transaction. This attribute is Required when the current flow rule is any submit tender value.
customerConfirmationForPOSRequestedPayments Optional Boolean
Specifies if the user has confirmed that the POS can submit the payment authorization request for the specified payment tender.
executingFlowRule Required MobileTransactionFlowRule Enum
Identifies the stage of the transaction that applies to this request.
cashAccessDetail Optional CashAccessDetail
Used to pass transaction specifications only for ATM transactions. This attribute is Required when the TransactionType is ATM_CASH_ACCESS.
tipAmount Optional Double
The dollar amount of any tip added to the amount due by the wallet user.
offers Optional String
A list of offerUri values that identify offers that the user has elected to redeem for this transaction. This attribute is Required when the current flow rule is any submit offers value.
refundDetail Optional RefundDetail
Passes the transaction specifications that are needed only for refund transactions. This attribute is Required when the TransactionType is REFUND.
secondaryIdentifier Optional SecondaryIdentifier
A code used for multi-factor consent in transactions requiring charge pre-authorization.
fuelAccessDetail Optional fuelAccessDetail
Passes transaction specifications that apply only to fuel transactions. This attribute is Required when the TransactionType is FUEL.
mobileRequestedPayments Optional MobilePaymentCharge
The set of individual payment instances submitted by the mobile wallet toward completion of transaction payment in full.
transactionMetaData Optional Key/Value pair
Custom properties that capture data needed to proceed to the next step of the transaction, but which are not explicitly defined as part of the standard transaction structure.

Note: For deviceUri and deviceUniqueId: The value needs to be unique to the device but the value does not have to match the value generated by the WLW platform. It can be a unique value from the device or an external ID unique for each device. If you do not use a WLW value, use this format:

deviceUniqueId = UUID of the device or some external ID unique for the device
deviceUri = <client_name>:<device_type>#<deviceUniqueId>

For example: deviceUri = bp.uk.bpme:android#342d233211

Response

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

Attribute Description
transactionStatus Optional TransactionStatus Enum
The state of the transaction in WLW’s transaction manager at the time of this response.
transactionMetaData Optional TransactionMetaData
The data passed by the Acceptance Location required to start a transaction at that location, such as supported payment tenders, loyalty programs, offers, and other location-specific metadata.
transactionDetail Optional MobileTransactionDetail
Defines the elements that have been processed at this point in the transaction’s life cycle.
nextExecutingFlowRule Optional MobileTransactionFlowRule Enum
The flow rule that will execute upon completion of the current flow rule. The flow rule process is based on the life cycle configuration for the transaction type.
currentExecutingFlowRule Required MobileTransactionFlowRule Enum
Indicates the current step of the transaction’s life cycle that is processing.
transactionFlowRuleSpcifications Optional TransactionFlowRuleSpecification
Details that define how the current flow rule must complete in order to be successful. The flow rule specification responds to the dynamic transaction conditions.
checkoutToken Optional String
The token instance generated to initiate the transaction. Once this value is returned by the platform, it is then required in all subsequent calls related to the transaction.
paydiantReferenceId Optional String
WLW’s unique identifier for the transaction.
nextTransactionFlowRuleSpecification Optional TransactionFlowRuleSpecification
The handling instruction that triggers the next flow rule in the transaction process once the current flow rule completes.
discoveryType Optional DiscoveryType
Identifies the type of transaction so that during DISCOVERY the property values returned are appropriate for that type of transaction.
externalEvents Optional ExternalEvents.
Identifies the set of actions that occurred outside the immediate transaction or mobile wallet that affect the processing of the transaction, such as a social media share that earns loyalty points.

Status codes

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

StatusCode Description
100 SUCCESS
The enrollment was initiated successfully.
101 PARTIAL_SUCCESS
Partial Payment/Dispense success
304 INVALID_ARGUMENTS
Arguments in the request were not valid.
337 NO_TRANSACTION_DETAILS_FOUND
No TransactionDetail instances could be found relevant to this transaction, so updates could not be made.
341 TRANSACTION_CANCELED
The transaction was canceled and cannot be updated.
347 TRANSACTION_IN_USE
The transaction is processing and cannot be updated at this time.
360 OPERATION_TIMEOUT<br The transaction did not receive a response within its configured period.
370 TENDER_NOT_SUPPORTED
The selected payment account type is not supported for the transaction.
386 ERROR
An unrecoverable error occurred.
390 DATA_ACCCESS_ERROR
Data access error.
391 EXTERNAL_ENTITY_NOT_FOUND
An entity referenced in the update request could not be located in the system.
430 DECLINED
The payment was not authorized.
431 INSUFFICIENT_FUNDS
The account did not have enough money pay the amount of funds that the transaction needed.
443 PROCESSING_ERROR
WLW could not process the request. Wait 5 minutes.
444 GATEWAY_PROCESSING_ERROR
The Gateway could not process the request. Wait 5 minutes.
445 TRANSACTION_NOT_ALLOWED
The requested update is not allowed for this transaction.
447 TRANSACTION_NOT_SUPPORTED
The request update is not a supported operation for this transaction.
449 INVALID_AMOUNT
An amount specified in the request is not valid, such as if an ATM only dispenses $20 denominations and the request is for $25.
450 INVALID_CARD_NUMBER
The card number on the payment account being used is not a valid payment account for that tender.
452 EXPIRED_CARD
The payment account's expiration date has passed.
490 INVALID_TRANSACTION
The details of this transaction indicate it can be a fraudulent login account. Notify the Issuer of the wallet.
491 SUSPECTED_FRAUD
The details of this transaction indicate it can be using a fraudulent payment account. Notify the Issuer of the wallet.

Next

Feedback