B2B Mobile Transaction APIs - Methods

B2B request and response structure

All calls to the Paydiant B2B Gateway are structured in the following way:

B2B requests

All calls to the B2B gateway include a B2BRequest attribute which identifies the call to the gateway using the following attributes. The messageHeader attributes of versionID and environmentID are optional and can be left blank.

Request Attribute Description
B2BRequest messageHeader versionID
environmentID
partnerID

B2B responses

Responses back from the B2B Gateway also provide optional attributes that can be left blank. The status object of all of these methods except enrollCustomerandProvisionCard use the following format for the B2BResponse:

Response Attribute Description
B2BResponse messageHeader versionID
environmentID
partnerID
configurationDetails Key/Value pairs
status statusCode
statusDescription
statusDetails statusDetail statusCode
statusDescription
statusType:
PLATFORM or EXTERNAL_PROCESSOR

See each method's attribute tables for full details.

Payment status and transmission response status codes

The Status attribute indicates if the call was processed by the platform, not whether the intended action of the request was successfully accomplished.

For example, a request to retrieve a customer can be successfully transmitted, but if the requested customer does not exist, the intended action of retrieving the customer fails.

Each method here lists the transmission response status codes that can be sent for that method. See Payment status codes for the status codes that reflect the status of the payment. See Response status codes for a list of possible response status codes.

Alphabetical methods list

By purpose methods list

Purpose Name Description
Enrollment and Payment Accounts cancelPaymentAccountEnrollment Stops a multi-step payment account enrollment.
continuePaymentAccountEnrollment Submit the additional information requested by the authorizor to continue a multi-step or single step in-progress payment account enrollment.
enrollCustomerAndProvisionCard Used by a branded app to register a wallet profile in the Paydiant platform based on the user’s existing PayPal profile.
retrieveCustomerCardInfo Returns the card details for the customer uri supplied.
retrieveIncompletePaymentAccountEnrollments Returns multi-step payment account enrollments that did not finish.
startPaymentAccountEnrollment Initiates a multi-step payment account enrollment.
Customers createCustomer Used by the issuing partner's backend service to register a wallet profile in the Paydiant platform.
retrieveCustomer Used by the issuing partner’s backend service to lookup an existing wallet profile in the Paydiant platform using a Paydiant or external repository user identifier.
updateCustomer Used by the issuing partner’s backend service to make changes to an existing wallet profile in the Paydiant platform.
Devices createDevice Used by the issuing partner’s backend service to define a new stub device.
retrieveCustomerDevices Used by the issuing partner’s backend service to obtain the list of mobile devices associated with an existing wallet profile.
Tokens obtainMobileDeviceCheckoutToken Initiate a transaction by requesting a checkout token to generate a QR Code to display on the mobile device for scanning and decoding by an acceptor, for example, an ATM or POS.
releaseMobileDeviceCheckoutToken Resets the checkout token that has not yet been scanned by disassociating it from the transaction.
Transactions retrieveCustomerBlockedDevices Returns transactions that have been blocked due to suspected fraudulent activity.
retrieveMobileTransactionMetadata
retrieveMobileTransactionMetadata webhook
Request updated data from Paydiant based on the current step of the transaction.
updateDeviceBlockStatus Toggles a transaction's status between blocked and unblocked when the transaction has been blocked due to suspected fraudulent activity.
updateMobileTransaction Submit updated data to Paydiant based on the current step of the transaction.
Receipts retrievePaginatedUserReceipts Returns a set of receipts for a particular mobile wallet user for transactions that occurred within a specified range of time.
retrieveUserReceiptByPaydiantRefId Returns a specific receipt based on its unique identifier.

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

cancelPaymentAccountEnrollment

Deletes a pending payment account enrollment instance. This method cancels the registration of that account.

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

Request

Create an instance of B2bRequest extended to include:

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

Response

The platform returns an instance of B2bResponse extended to include:

Attribute Description
paydiantCorrelationId Required String
Paydiant’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.

cancelTransaction

Aborts a transaction that is in progress. Paydiant returns a confirmation of the cancellation result.

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

Request

Create an instance of B2bRequest extended to include:

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

Response

The Platform returns an instance of B2bResponse with no additional attributes.

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Transaction was cancelled.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the system attempted to cancel the transaction. The detailed description can be context-specific.

continuePaymentAccountEnrollment

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

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

Request

Create an instance of B2bRequest extended to include:

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.

Response

The platform returns an instance of B2bResponse extended to include:

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 originates.

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the system attempted to update the customer profile. The detailed description can be context-specific.

createCustomer

Registers a mobile wallet profile in the Paydiant platform that can engage in mobile transactions. Device and authentication handling is managed by the Issuer’s application service layer and is not subject to Paydiant’s Security Manager for handling.

POST URL/b2b-gateway/v2/customers

Request

Create an instance of B2bRequest extended to include:

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

Response

The platform returns an instance of B2bResponse extended to include:

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

Status codes

See Payment status codes for the transaction payment status.

StatusCode Description
SUCCESS SUCCESS
Creation of the wallet user profile was successful.
304 Invalid argument FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the customer profile was created. The detailed description can be context-specific.
389 Issuing Partner is not configured
to support stub customer records
FAILED
The Issuing Partner for the wallet has not been set up to accept a stub customer record.

createDevice

Links a mobile wallet profile in the Paydiant platform with a mobile device that does not have an idenity in the Paydiant platform. Transactions that are processed through the B2B Gateway do not identify the device making a transaction.

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

Request

Create an instance of B2bRequest extended to include:

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
Paydiant’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
Paydiant’s unique identifier for a business entity that has been onboarded to the Paydiant platform in order to participate in mobile transactions.
issuingPartnerUri Required String
Paydiant’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 returns an instance of B2bResponse extended to include:

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

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the customer profile was updated. The detailed description can be context-specific.
389 Issuing Partner is not configured
to support stub device records
FAILED
This issuing partner was not properly configured to accept stub device records.

enrollCustomerAndProvisionCard

Note: This method is not available to all users. Contact your Paydiant representative before developing against it.

Registers a device on the Paydiant platform and enables mobile transactions for that device with a valid payment tender. Paydiant creates a security profile and returns the unique identifiers assigned for the device, the customer, and the payment account. This is a previously released B2B wallet management method that uses a status object that is slightly different from the status object used for the other B2B Mobile Transaction APIs described here.

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

Request

Create an instance of B2bRequest extended to include:

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 returns an instance of B2bResponse extended to include:

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

See Payment status codes for the transaction payment status.

StatusCode Description
SUCCESS SUCCESS
Customer, device, and wallet enrollment was successful.
304 Invalid arguments FAILED
The arguments in the request were not valid.Some part of the attribute arguments are incorrect. The detailed description can be context-specific, such as PartnerURI cannot be null or empty.
370 Tender not supported FAILED
The requested tender is not available in the wallet.
386 Error FAILED
An error occurred when the customer profile, device profile, or wallet enrollment was created. The detailed description can be context-specific.
389 Issuing Partner is not configured
to support stub customer records
FAILED
The Issuing Partner for the wallet has not been set up to accept a stub customer record.
523 Payment account enrollment
card provisioning declined
FAILED
The card used to enroll this account was not accepted.
524 Payment account enrollment
card provisioning operation not supported
FAILED
The card used to enroll this account is not set up to allow provisioning.
525 CRUD not possible FAILED
Payment account enrollment does not allow CRUD (create, read, update, or delete) so the account cannot persist in the system.

obtainMobileDeviceCheckoutToken

Requests 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

Create an instance of B2bRequest extended to include:

Attribute Description
tenant Required TenantIdentifier
Defines the Paydiant tenant used to issue the mobile wallet app.
customerUri Required String
Paydiant’s unique identifier for the user of the mobile wallet associated with the device.
deviceUri Required String
Paydiant’s unique identifier for the mobile device that is associated with a mobile wallet user in the Paydiant platform.
deviceUniqueId Required String
The device manufacturer’s unique identifier for the device, which is collected when the device is linked with wallet registration.
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
Paydiant’s unique identifier of the transaction.

Response

The platform returns an instance of B2bResponse extended to include:

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

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Obtained checkout token.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the system attempted to obtain the mobile device checkout token. The detailed description can be context-specific.

releaseMobileDeviceCheckoutToken

Cancels a generated checkout token that has not yet been scanned. This action is typically invoked when the app screen changes. For example, this action is invoked when the user switches to the location finder from the pay screen or when the user puts the app into the background by answering a phone call or text. Paydiant 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

Create an instance of B2bRequest extended to include:

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

Response

The platform returns an instance B2bResponse with no additional attributes.

Status codes

See Payment status codes for the transaction payment status.

Attribute Description
SUCCESS SUCCESS
Transaction was cancelled.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the system attempted to obtain the mobile device checkout token. The detailed description can be context-specific.

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

Create an instance of B2bRequest extended to include:

Attribute Description
customerUri Contextual String
Paydiant’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 Paydiant profile.
tenantUri Required String
Paydiant’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
Paydiant’s unique identifier for a business entity that has been onboarded to the Paydiant 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 returns an instance of B2bResponse extended to include:

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 Paydiant 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 Paydiant 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 Paydiant’s Security Manager.
TRUE - this is a minimal user profile that is not validated by Paydiant's Security Manager.
FALSE - This is a full user profile validated by Paydiant's Security Manager.
customer Optional Customer
Defines the wallet user profile properties.

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the customer profile was updated. The detailed description can be context-specific.

retrieveCustomerBlockedDevices

Returns transactions that have been blocked due to suspected fraudulent activity.

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

Request

Attribute Description
b2bRequest Required B2bRequest
Identifies the request to the B2B Gateway.
customerUri Required String
The unique identifier of a registered mobile wallet user.
customerExternalUri Optional String
The unique identifier of a registered mobile wallet user onboarded externally to the Paydiant platform.
partnerUri Required String
The unique identifier of the Paydiant partner under which the issuer is registered.
issuingPartnerUri Required String
The unique identifier of the Paydiant partner that issued the mobile payments app where the wallet is registered.

Response

The Platform returns an instance of B2bResponse extended to include:

Attribute Description
customerDevices Optional CustomerDevice
List of device profiles that are associated with the specified customer wallets with transactions identified as blocked.

Status codes

Status Code Description
SUCCESS SUCCESS
The list of blocked devices was retrieved.
386 Error FAILED
An error occurred when the system attempted to retrieve the list of devices that are blocked. The detailed description can be context-specific.
543 Customer not found FAILED
The specified customer URI or customer external ID was not found.

retrieveCustomerCardInfo

Returns the information on a specific card (payment account).

Note: This is a V1 method that uses the V1 Status object.

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

Uses the customerUri or the paymentAccountUri to identify the card.

Request

Attribute Description
b2bRequest Required B2bRequest
Identifies the request to the B2B Gateway.
customerUri Required String
The unique identifier of a registered mobile wallet user.
issuingPartnerUri Required String
The unique identifier of the Paydiant partner that issued the mobile payments app where the wallet is registered.
partnerUri Required String
The unique identifier of the Paydiant partner under which the issuer is registered.
paymentAccountUri Required String
The unique identifier of a card in the customer’s mobile wallet (but can be null).
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 Boolen
Indicates if the metadata associated with this card will be included in the return.
deviceUri Optional String
The unique identifier of the device where this card is stored.

Response

Attribute Description
paymentResponse Required PaymentResponse
Extends the B2bResponse) to add a payment status.
cards Optional Card
Instances of the Card object that define an individual card/payment account.
includeMetaData Required Boolean
Indicates if the metadata associated with this card will be included in the return.
TRUE - Metadata is included
FALSE - Do not include the metadata
customerUri Required String
The unique identifier of a registered mobile wallet user.
paymentAccountUri Required String
The unique identifier of a card in the customer’s mobile wallet.

retrieveCustomerDevices

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

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

Request

Create an instance of B2bRequest extended to include:

Attribute Description
customerUri Contextual String
Paydiant’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
Paydiant’s unique identifier of a partner that is configured to issue a mobile wallet.

Response

The Platform returns an instance of B2bResponse extended to include:

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

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the system attempted to retrieve the devices list. The detailed description can be context-specific.

retrieveIncompletePaymentAccountEnrollments

Returns a list of enrollments that were started but not completed. Use this method to either resume or cancel the enrollment.

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

Request

Create an instance of B2bRequest extended to include:

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

Response

The Platform returns an instance of B2bResponse extended to include:

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

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the system attempted to retrieve the incomplete payment account enrollment data. The detailed description can be context-specific.

retrieveMobileTransactionMetadata

Retrieves information about the transaction that is necessary for the wallet to progress through the current step of the transaction.

Note: See retrieveMobileTransactionMetadata Webhook to learn how to allow Paydiant 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 Paydiant 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

Create an instance of B2bRequest extended to include:

Attribute Description
tenant Required TenantIdentifier Defines the Paydiant tenant used to issue the mobile wallet app.
customerUri Required String
Paydiant’s unique identifier for the user of the mobile wallet associated with the device.
deviceUri Required String
Paydiant’s unique identifier for the mobile device that is associated with a mobile wallet user in the Paydiant platform.
deviceUniqueId Required String
The device manufacturer’s unique identifier for the device, which is collected when the device is linked with wallet registration.
checkoutTokenValue Optional String
The value of the token issued to initiate the transaction.
paydiantReferenceId Optional String
Paydiant’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.

Response

The platform returns an instance of B2bResponse extended to include:

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 Paydiant’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
Paydiant’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.

Staus Codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
309 Invalid checkout token FAILED
The checkout token is not valid. It can have expired or was not generated properly.
337 No transaction details found FAILED
The transaction details needed to complete the transaction were not available.
341 Transaction has been canceled FAILED
The transaction was stopped from completing.
347 Transaction in use FAILED
The transaction is already processing.
360 Operation timeout FAILED
The transaction did not receive a resaponse within its configured attempts or number of tries.
361 Checkout token blocked FAILED
the checkout token was prevented from geing generated or passed.
385 Transaction not ready FAILED
The transaction did not complete in the specified amount of time available.
386 Error FAILED
An error occurred when the system attempted to retrieve the mobile transaction metadata. The detailed description can be context-specific.
391 Check not found FAILED
The external entity is not found.
427 Check Locked / Not Found /
Closed
FAILED
Invalid external entity state.

retrieveMobileTransactionMetadata webhook

In the retrieveTransactionMetadata method described above, the Merchant App Server polls the Paydiant platform for specific transaction lifecycle events as they occur. The retrieveMobileTransactionMetadata method can instead be implemented as a webhook that will consume transaction lifecycle events pushed from Paydiant's notification connector API. For this implementation, the Merchant creates the endpoint and provides Paydiant 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 Paydiant so it can be identified in the property file to recognize it.
  • 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 Paydiant IP address. If the Merchant App Server uses VPN, whitelisting is not required.

When a LifeCycleEventType occurs, the Paydiant 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 Paydiant to acknowledge that the Merchant App Server successfully received the transaction metadata. If Paydiant does not receive the success response, Paydiant retries the push the number of times configured in the connector. If the transaction data is still not received, the transaction timeout calls the standard retrieveMobileTransactionMetadata with polling until the data is transferred.

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.

The following information describes how to configure the endpoint so that it will accept the pushed data.

retrieveMobileTransactionMetadata webhook request

Transaction fields with null content are not sent.

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
Paydiant's unique identifier for the transaction.
externalEvents Optional ExternalEvent Object
Defines any additional data and the external event type.

retrieveMobileTransactionMetadata webhook response

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

retrieveCustomerCardInfo

Returns the information on a specific card (payment account).

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

Uses the customerUri or the paymentAccountUri to identify the card.

Request

Attribute Description
b2bRequest Required B2bRequest
Identifies the request to the B2B Gateway.
customerUri Required String
The unique identifier of a registered mobile wallet user.
issuingPartnerUri Required String
The unique identifier of the Paydiant partner that issued the mobile payments app where the wallet is registered.
partnerUri Required String
The unique identifier of the Paydiant partner under which the issuer is registered.
paymentAccountUri Required String
The unique identifier of a card in the customer’s mobile wallet (but can be null).
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 Boolen
Indicates if the metadata associated with this card will be included in the return.
deviceUri Optional String
The unique identifier of the device where this card is stored.

Response

Attribute Description
paymentResponse Required PaymentResponse
Extends the B2bResponse to add a payment status.
cards Optional Card
Instances of the Card object that define an individual card/payment account.
includeMetaData Required Boolean
Indicates if the metadata associated with this card will be included in the return.
TRUE - Metadata is included
FALSE - Do not include the metadata
customerUri Required String
The unique identifier of a registered mobile wallet user.
paymentAccountUri Required String
The unique identifier of a card in the customer’s mobile wallet.

retrievePaginatedUserReceipts

Returns 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

Attribute Description
b2bRequest Required B2bRequest
Identifies the request to the B2B Gateway.
partnerUri Required String
The unique identifier of the Paydiant partner under which the issuer is registered.
issuingPartnerUri Required String
The unique identifier of the Paydiant 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 returns an instance of B2bResponse extended to include:

Attribute Description
receiptList Required Array
The set of UserReceipt objects for each receipt record that met the filtering criteria specified in the request.

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
404 Resource Not Found FAILED
There was a problem retrieving a resource. Actual message can provide detailed context such as Specified receipt not found.
401 Calling service does not
have permission to access
the endpoint.
FAILED
Unauthorized.
400 One or more parameters is not valid. FAILED

retrieveUserReceiptByPaydiantRefId

Returns 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 returns an instance of B2bResponse extended to include:

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

Status Codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
404 Resource Not Found FAILED
There was a problem retrieving a resource. Actual message can provide detailed context such as Specified receipt not found.
401 Calling service does not
have permission to access
the endpoint.
FAILED
Unauthorized.
400 One or more parameters is not valid. FAILED

retrieveSupportedTenderTypes

Returns a list of the types of tender available for this Issuing Partner and the metadata required for each one.

Note: This is a V1 method that uses the V1 Status object.

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

Request

Attribute Description
b2bRequest Required B2bRequest
Identifies the request to the B2B Gateway.
tenantUri Required String
Unique identifier used to indicate this partner for single gateway tenancy.
partnerUri Required String
The unique identifier of the Paydiant partner under which the issuer is registered.

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

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 returns an instance of B2bResponse extended to include:

Attribute Description
tenderTypes Optional TenderType
Provides the details about a particular tender type.

startPaymentAccountEnrollment

Use this method to initiate the process to add a payment instrument to a mobile wallet as a valid tender for payments when the enrollment process requires multiple steps. If the authorizor requires that the enrollment behave differently depending on the responses received at each step, this method is used as the first step of that back and forth process. This method can also be used to initiate a single-step authorization.

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

Request

Create an instance of B2bRequest extended to include:

Attribute Description
enrollmentType Required Enum found in PaymentAccountEnrollmentType
Indicates where Paydiant 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 Paydiant platform.
PROVISION - Value sent in the CARD_NUMBER field is stored by the authorizing party and a tokenized replacement is stored in Paydiant’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.
paymentAccount Required PaymentAccount Details about the Payment Account being enrolled.

Response

The platform returns an instance of B2bResponse extended to include:

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

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the system attempted to update the customer profile. The detailed description can be context-specific.

updateCustomer

Changes the editable properties of a mobile wallet user profile.

PUT URL/b2b-gateway/v2/customers

Request

Create an instance of B2bRequest extended to include:

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

Response

The platform returns an instance of B2bResponse with no additional payload.

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
386 Error FAILED
An error occurred when the system attempted to update the customer profile. The detailed description can be context-specific.
389 Issuing Partner is not configured
to support stub customer records
FAILED
The Issuing Partner for the wallet has not been set up to accept a stub customer record.

updateDeviceBlockStatus

Toggles a transaction's status between blocked and unblocked when the transaction has been blocked due to suspected fraudulent activity.

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

Request

Attribute Description
b2bRequest Required B2bRequest
Identifies the request to the B2B Gateway.
issuingPartnerUri Required String
The unique identifier of the Paydiant partner that issued the mobile payments app where the wallet is registered.
partnerUri Required String
The unique identifier of the Paydiant partner under which the issuer is registered.
deviceUri Required String
The unique identifier of a device.
blocked Required Boolean
Indicates if the status of the listed device is blocked.
auditInfo Optional AuditInfo
Stores information that Merchants can use to audit the activation.

Response

The platform returns an instance of B2bResponse extended to include:

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

Status codes

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
386 Error FAILED
An error occurred when the system attempted to update the list of blocked devices. The detailed description can be context-specific.
453 Device not found FAILED
The Device was not found for the specified device URI or device external ID.

updateMobileTransaction

Submits updates to the transaction based on 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. Paydiant 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

Create an instance of B2bRequest extended to include:

Attribute Description
tenant Required TenantIdentifier Defines the Paydiant tenant used to issue the mobile wallet app.
customerUri Required String
Paydiant’s unique identifier for the user of the mobile wallet associated with the device.
deviceUri Required String
Paydiant’s unique identifier for the mobile device that is associated with a mobile wallet user in the Paydiant platform.
deviceUniqueId Required String
The device manufacturer’s unique identifier for the device, which is collected when the device is linked with wallet registration.
checkoutTokenValue Optional String
The decoded value of the token issued to initiate the transaction.
paydiantReferenceId Optional String
Paydiant’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 String
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.

Response

The platform returns an instance of B2bResponse extended to include:

Attribute Description
transactionStatus Optional TransactionStatus
The state of the transaction in Paydiant’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 CashAccessTicket
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
Paydiant’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

See Payment status codes for the transaction payment status.

Status Code Description
SUCCESS SUCCESS
Requested property updates were applied successfully.
PARTIAL_SUCCESS Partial Payment/Dispense success
304 Invalid arguments FAILED
The arguments in the request were not valid. The detailed description can be context-specific, such as PartnerUri cannot be null or empty.
337 No transaction details found FAILED
The transaction details needed to complete the transaction were not available.
341 Transaction has been canceled FAILED
The transaction was stopped from completing.
347Transaction in use FAILED
The transaction is already processing.
360 Operation timeout FAILED
The transaction did not receive a resaponse within its configured attempts or number of tries.
370 Tender not supported FAILED
Tender type not supported for cash access
386 Error FAILED
An error occurred when the system attempted to update the mobile transaction. The detailed description can be context-specific.
390 Data access error FAILED
Data access error.
391 Check not found FAILED
The external entity is not found.
430 Declined FAILED
The transaction declined to accept the payment.
431 Insufficient funds FAILED
The account did not have enough money pay the amount of funds that the transaction needed.
443 Processing error occurred FAILED
The transaction did not process properly.
444 Processing error occurred at gateway FAILED
The transaction did not properly process at the gateway to the Paydiant platform.
445 Transaction cannot be processed FAILED
An issue with the transaction is preventing it from being properly processed.
447 Transaction not supported in the integration FAILED
The transaction is trying to process in a way it was not configured to operate for the wallet.
449 Invalid amount specified FAILED
The amount of the transaction is not formatted properly.
450 Invalid card number FAILER
The card number on the payment account being used is not a valid payment account for the wallet.
452 Expired credit card FAILED
The payment account's expiration is not valid for the current date.
490 Invalid Transaction, Contact Issuer FAILED
The details of this transaction indicate it can be a fraudulent login account. The Issuer of the wallet should be notified.
491 Suspected Fraud, Contact Issuer FAILED
The details of this transaction indicate it can be using a fraudlent payment account. The Issuer of the wallet should be notified.

Next

Feedback