B2B Mobile Transaction API - UserReceipt Data Objects

The UserReceipt data object is designed to carry similar information to the Receipt data object but with a reduced payload and some other slight differences. In some cases data objects have the same name as the Receipt data objects but with different requirements or fewer attributes when called by the UserReceipt object. Most data objects with the same name are identical regardless of what calls them.

For convenience, this section provides the set of data objects called by the UserReceipt object. See Data Objects for the data objects called by Receipt and other B2B Mobile Transaction API endpoints.

UserReceipt Enums

UserReceipt Data Objects

AcceptanceLocation

Uniquely identifies one physical retail location at which a merchant partner operates. A merchant partner might have one or many acceptance locations defined.

Attribute Description
storeCode Required String
The Acceptance Partner’s unique identifier for the Acceptance Location. For example, this code could be a franchise number, store chain id, or ATM identifier. Maximum 50 char.
uri Required String
Paydiant’s unique system identifier for the Acceptance Location.
name Required String
Paydiant’s text name identifier for the Acceptance Location.
address1 Required String
The number and street of the physical address of the Acceptance Location.
address2 Optional String
Available for any secondary information about the position of the business within the street address, such as a suite number.
city Required String
The name of the city in which the Acceptance Location exists. Maximum 100 char.
state Required String
The US state in the postal address of an entity. Maximum 100 char.
zipCode Required String
The postal zip code associated with the Acceptance Location. Maximum 100 char.
country Required String
The country of the Acceptance Location’s physical address. Maximum 100 char.

AcceptancePartner

Uniquely identifies the merchant that is registered to process mobile wallet transactions with Paydiant. AcceptancePartner is also referred to as the merchant.

Attribute Description
acceptanceLocation Optional AcceptanceLocation
The set of Acceptance Location instances that identify where this transaction took place.
uri Required String
Paydiant's unique identifier for the acceptance partner.
name Required NCName
Paydiant's plain text name of the Acceptance Partner.
partnerUri Required String
Paydiant’s unique identifier for a business entity that has been configured to participate in mobile transactions on the Paydiant platform.
modifiedTime Optional dateTime
A timestamp that represents the last time any attribute of this record was updated.
logoUrl Optional String
The server path location for the logo image of the Acceptance Partner. Can be used on receipts.
cardSurfaceDiscountLabel Optional String
Indicates the acceptance partner’s preferred payment tender, which can be referenced as an incentive for using that tender in transactions.

AdditionalData

Key/Value pairs used to supply metadata.

Attribute Description
key Required String
The name of a custom property.
value Required String
A specific setting for a custom property.

AdvertisingNetwork

Defines the details of the sponsor of an offer sponsor, as registered and defined by Paydiant. An AdNetwork aggregates advertisement space supplied from publishers and matches it with advertiser demand. In the Paydiant platform, the advertisingNetwork groups similar offer objectives.

Attribute Description
advertisingNetworkDisplayName Optional String
The name to use to identify the AdNetwork associated with the offer.
advertisingNetworkLogoUri Optional String
A unique identifier for the logo image associated with this AdNetwork.
advertisingNetworkType Optional advertisingNetworkType Enum
Identifies the AdNetwork’s tenant relationship with Paydiant. Valid values are:
ACCEPTANCE_PARTER
ISSUING_PARTNER
THIRD_PARTY
partnerUri Optional String
Unique identifier for the parent partner under which the advertising network is registered. The parent partner is a tenant relationship and can be an issuing partner, acceptance partner, or third-party entity that has been configured to process mobile payments on the Paydiant platform.
partnerNetworkUri Optional String
Unique identifier for the tenant under which this network is registered.

CashAccessDepositProperties

The properties associated with an ATM deposit transaction of cash and/or checks.

Attribute Description
availableBalance Required Double
The balance of the account into which the deposit was made. Includes the deposit amount.
availableNow Required Double
The balance of the account into which the deposit was made that is available for withdrawal at this time.
cashDeposits Optional CashDeposit
Identifies the denomination of each set of bills included in the deposit.
checkDeposits Optional CheckDeposit
Identifies the value and URL for an image of each check included in the deposit.
noOfChecksDeposited Optional Integer
The number of checks included in the deposit. This number matches the set of instances in the checkDeposit property.
postDate Required dateTime
The time at which the deposit posted to the account in the format yyyy-MM-dd’T’HH:mm:ss’Z’.
transactionSubType Required TransactionSubType Enum
String that further distinguishes the transaction type.

CashDeposit

Identifies each set of bills included in the ATM deposit based on the denonmination. A single cash deposit transaction can include multiple instances of this object to represent each different bill denomination in the deposit.

Attribute Description
billDenomination Required Integer
The number of dollars or other currency unit for each distinct denonmination in this deposit.
noOfBills Required Integer
The number of bills of the specified denomination included in this deposit element.

CheckDeposit

Defines the relevant elements of a single check included in an ATM deposit. A single deposit transaction includea an instance of this object for each check in the deposit.

Attribute Description
checkValue Required Double
The dollar or other currency unit of the check. Maximum 100 char.
url Optional String
The ATM’s unique identification or image reference of the check.

Customer

Identifies a mobile wallet user.

Attribute Description
partnerUri Required String
Unique identifier for the parent partner under which the advertising network is registered. The parent partner is a tenant relationship and can be an issuing partner, acceptance partner, or third-party entity that has been configured to process mobile payments on the Paydiant platform.
issuingPartnerUri Required String
Paydiant’s unique identifier of a partner that is configured to issue a mobile wallet.
customerUri Required String
Paydiant’s unique identifier for the user of the mobile wallet associated with the device.

FuelReceiptProperties

Extends a receipt with data applicable only to fuel transactions.

Attribute Description
additionalData Optional AdditionalData
A set of any number of key-value properties used to extend the receipt data.
fuelUnitsPumped Required Double
The amount of fuel that was dispensed for the transaction.
fuelUnitType Required FuelUnitType
Specifies the unit of volume used to measure the fuel. Valid values are:
GALLON
LITRE

LoyaltyReceipt

Defines properties related to the conclusion of a transaction in which loyalty points were earned or spent.

Attribute Description
accrualActivityUri Required String
Paydiant’s unique identifier of the qualified activity.
loyaltyAccrualActivityType Required LoyaltyAccrualActivityType Enum
Identifies the loyalty activity category. Valid values are:
EXTERNAL_ACTIVITY
ENROLLMENT
PURCHASE
REFUND
VOID_PURCHASE
VOID_REFUND
loyaltyProgramUri Required String
Paydiant’s unique identifier of the loyalty program for which the activity is eligible.
points Optional Integer
The number of points awarded or redeemed for this transaction. Maximum 100 char.

Offer

Defines the properties that make up an individual instance of an offer campaign that has been delivered to a mobile wallet, where it can then be activated and redeemed in qualifying transactions.

Attribute Description
offerCampaign Optional OfferCampaign
The parent campaign for this offer instance.
discountAmount Optional Double
The dollar or percentage amount by which the total purchase is to be reduced when this offer is redeemed. Maximum 100 char.
expiryDate Optional dateTime
The UNIX timestamp that indicates when the offer is no longer valid for redemption.
offerUri Required String
Paydiant’s unique identifier of the offer instance.
offerStatus Optional OfferStatus Enum
Indicates the current state of the offer in the wallet.

OfferArtifact

Defines each visual part of an offer. The OfferArtifactViewType indicates which part this object defines. The artifact parts are:

  • Details
  • Confirmation
  • Thumbnail
  • Image
  • Terms and Conditions
  • Offer Title
  • Offer Description
  • Additional Information
  • Summary
Attribute Description
content Required String
Depending on the offerArtifactContentType, the content can be actual text used or a URL for the content to use when this offer is displayed, or other kind of content.
offerArtifactChannelType Required OfferArtifactChannelType Enum
Indicates the channel destination where this artifact is intended for display. Valid values are:
MOBILE
WEB
FACEBOOK
EMAIL
offerArtifactContentType Required OfferArtifactContentType Enum
Indicates the type of file for the artifact's content. Valid values are:
TEXT
VIDEO
URL
XML
TAGS
offerArtifactViewType Required OfferArtifactViewType Enum
Identifies the part of the offer represented by this artifact. Valid values are:
SUMMARY
DETAILS
CONFIRMATION
THUMBNAIL
IMAGE
TERMS_AND_CONDITIONS
OFFER_TITLE
OFFER_DESCRIPTION
ADDITIONAL_INFORMATION
REDEMPTION_SCHEDULE

OfferCampaign

The details of a mobile offer promotional campaign that is delivered to subscribed mobile wallets. Users can then be activated and redeemed as part of a qualifying transaction.

Attribute Description
offerArtifacts Optional OfferArtifact
The set of objects that define each visual component of this offer.
advertisingNetwork Optional AdvertisingNetwork
The advertising collection that is sponsoring the promotion of the campaign.
offerReward Optional OfferReward
Defines the parameters of the specific compensation associated with an offer. For each [
checkoutTokenValue Optional String
A unique identifier code that generates a QR code that can be scanned by a user's phone to redeem this offer.
endDate Optional DateTime
UNIX timestamp for the date and time when the offer becomes invalid.
offerCampaignExternalId Optional String
An identifier that associates the offer to a relevant merchant value, such as the offer code on the POS system. If this value is not defined, a random value is automatically generated.
offerCampaignUri Optional String
Paydiant’s unique identifier for the campaign.
offerType Optional OfferType Enum
Identifies the type of offer. Currently only one valid value: VALUE_BASED_OFFER.
To define a SKU-based reward or to set the percentage discount for the value-based reward, see OfferCampaign/OfferReward/RewardType.
offerProcessingPoint Required OfferProcessingPoint Enum
Indicates if the offer is calculated by the merchant's POS and only the total sent to Paydiant or if the entire discount is calculated by the Paydiant Cloud. Valid values are: POS'
Paydiant

OfferReward

Defines the details of the specific compensation associated with an offer. The compensation can be in the form of a percentage of the total to discount or as a total value to remove from the transaction total. The OfferReward can also be defined as a series of SKUs for products offered as the reward.

Attribute Discription
discountPercentage Required Double
The percentage used calculate how much the offer will discount the total transaction amount. Maximum 100 char.
discountValue Required Double
The dollar amount that the offer will remove from the transaction. Maximum 100 char.
rewardType Required RewardType Enum
Defines the percentage to discount, the total value to discount, or whether this reward is SKU-based.

PaymentAccountType

Identifies the card type supported by the wallet for a particular PaymentTender.

Attribute Description
paymentAccountTypeUri Required String
Unique identifier of the type of payment for this tender.
paymentAccountTypeName Optional String
Text description of the payment account type.

PaymentAccountNetworkType

Identifies the network processor supported by the wallet for a particular PaymentTender.

Attribute Description
paymentAccountNetworkTypeUri Required String
Unique identifier of the type of network that this tender runs on.
paymentAccountNetworkTypeName Optional String
Text description of the type of network that this tender runs on.

PaymentInstrument

Uniquely identifies a payment account that is registered as a valid tender in the mobile wallet and can require extended data when used in a transaction, such as PayPal.

Attribute Description
paymentInstrumentUri Required String
Uniquely identifies the payment account in the Paydiant system.
maskedCardNumber Optional String
The encrypted rendition of the card PAN, as configured to display on the receipt.
cardNickName Optional String
The wallet user’s way to identify this payment account in the wallet, for example, Paul’s Work Visa.
paymentTender Required PaymentTender
Identifies the tender available to a wallet by identifying the type (credit, debit, etc.) plus the network processor (Visa, NYCE, etc.).
additionalData Optional
Key-value pairs that define custom properties for the payment instrument that are not otherwise captured, such as nickname. An instance of this object can include any number number of these data pairs.
extendedPaymentTenderData Optional AdditionalData
Defines additional data required by a payment processor to obtain payment authorization, such as an auth token or other credentials.

PaymentResult

Defines the response data from all involved parties for the outcome of a payment request.

Attribute Description
paymentInstrument Required PaymentInstrument
Defines the PAN data associated with the payment tender.
currencyCode Optional String
The ISO 4217 recognized code for the type of currency associated with the amount, for example, USD = United States Dollar. Maximum 10 char.
paidOrRefundAmount Optional Double
The dollar amount of the payment instance. This amount may or may not be the full transaction amount.
paymentStatus Optional String
Paydiant’s text description for the current state of the payment authorization.
paymentStatusCode Optional Integer
Paydiant’s numeric identifier for the current state of the payment authorization. Maximum 100 char.
externalPaymentStatusCode Optional String
The third-party processor’s system identifier for the outcome of the payment authorization.
externalPaymentStatusDesc Optional String
The third-party processor’s descriptor for the outcome of the payment authorization.
paymentTransactionUri Optional String
The third-party processor’s unique identifier for the specific payment authorization instance.
mobileReceivedPaymentProcessedMetadata Optional AdditionalData
Defines custome properties that are included in the payment authorization and should be available in the receipt, for example, externally applied loyalty activity.

PaymentTender

Identifies a specific payment instrument configured for use by an issuing or acceptance partner.

Attribute Description
paymentAccountType Required PaymentAccountType
Identifies the tender available to a wallet by identifying the type (credit, debit, etc.).
paymentAccountNetworkType Optional PaymentAccountNetworkType

UserReceipt

Defines the details of a completed transaction needed to generate a user receipt.

Attribute Description
acceptancePartner Required AcceptancePartner
The Paydiant tenant that is registered to engage in mobile transaction processing for this Acceptance Location.
loyaltyReceipts Optional LoyaltyReceipt
The set of loyalty activity instances applied to the transaction.
offers Optional OfferThe set of offers that were redeemed or refunded for the transaction.
paymentResults Optional PaymentResult
The set of outcomes for each payment authorization attempt for the transaction.
receiptType Required ReceiptType Enum
Identifies the type of transaction for this receipt.
cashierId Required String
The identifier of the employee logged into the POS who rang in the transaction.
merchantTranasctionReferenceId Required String
The merchant (AcceptancePartner)’s unique identifier of the transaction.
paydiantReferenceId Required String
Paydiant’s unique identifier of the transaction.
savings Optional Double
The dollar amount by which the total is reduced by coupons or other promotions. Maximum 100 char.
subTotal Optional Double
The dollar amount due before applied tax, tip, and discounts. Maximum 100 char.
tax Optional Double
The dollar amount added to the ticket for tax. Maximum 100 char.
terminalId Required String
Paydiant’s identifier of the registered POS terminal that processed the transaction.
tipAmount Optional Double
The dollar amount appended to the total as tip.
totalAmount Required Double
The total dollar amount paid for the transaction. Maximum 100 char.
otherTransactionTypeDescription Optional String
When the TransactionSubType value is other, this text value describes the nature of the transaction, such as donation.
transactionSubType Optional TransactionSubType Enum
Further categorizes a transaction beyond that of purchase or refund.
externalReceiptUrl Optional String
Used to store a merchant-provided URL through which the user can view the receipt in a secure portal.
receiptText Optional String
A text message that can be added to the receipt by the merchant.
fuelReceiptProperties Optional FuelReceiptProperties
A set of properties that describe the fuel activity instances for this transaction.
surcharge Optional Double
The dollar amount added to a cash withdrawal as a transaction fee. Maximum 100 char.
includedGratuity Optional Double
The dollar amount added as an automatically applied tip, for example for large dining parties. Maxcimum 100 char.
totalAmountPoints Optional Double
The total points added or subtracted for the transaction based on all loyalty activity processed. Maximum 100 char.
cashAccessDepositProperties Optional CashAccessDepositProperties
Specifies the details for an ATM deposit transaction. Required when the TransactionSubType is ATM_CASH_ACCESS.
offerDiscountAmount Optional Double
The total amount due after an offer discount has been applied. Maximum 100 char.
receiptId Optional String
Paydiant’s identifier of the generated receipt instance.
secondaryReceiptId Optional String
A code generated to confirm a user’s consent to a pre-authorization charge against a payment account.
originalReceiptId Required String
A unique identifier of the receipt for the transaction that precipitated this transaction, such as a purchase for which this is a refund.
originalPaydiantReferenceId <Otional String
A unique identifier of the transaction that precipitated this transaction, such as a purchase for which this is a refund.
Customer Required Customer
Unique identifies the mobile wallet user.
TransactionTime Required dateTime
Timestamp for when the transaction took place.

UserReceipt Enums

AdvertisingNetworkType

Identifies the AdNetwork’s tenant relationship with Paydiant.

Enum Description
ACCEPTANCE_PARTER The merchant who sponsors the offer to be redeemed.
ISSUING_PARTNER The partner who sponsors the mobile wallet where an offer is proffered.
THIRD_PARTY An entity that is external to the Paydiant platform that can sponsor an offer or wallet, such as a bank or coupon club.

FuelUnitType

The unit of fuel volume specified for the fuel site.

Enum Description
GALLON Fuel is dispensed and priced per gallon.
LITRE Fuel is dispensed and priced per litre.

LoyaltyAccrualActivityType

A qualifying action that affects the loyalty reward balance.

Enum Description
EXTERNAL_ACTIVITY An action outside the mobile wallet, such as social media activity.
ENROLLMENT Membership registration in the loyalty program.
PURCHASE A standard sales transaction.
REFUND A standard refund/credit transaction.
VOID_PURCHASE The reversal of a sale for which points were awarded.
VOID_REFUND The reversal of a refund for which points were subtracted.

OfferArtifactChannelType

The medium through which the offer artifact is meant to be published.

Enum Description
MOBILE Viewable on a mobile device.
WEB Viewable in an Internet browser page.
FACEBOOK Viewable on a Facebook site account.
EMAIL Viewable as the body of an email message.

OfferArtifactContentType

The format of the artifact file.

Enum The content is
TEXT A text file.
VIDEO A video file.
URL A link to a webpage.
XML An XML file.
TAGS A set of categorization or search optimization tags.

OfferArtifactViewType

The offer component represented by the artifact.

Enum Description
DETAILS The body of the offer that describes the details of its use.
CONFIRMATION The page displayed when the user opts to redeem the offer.
THUMBNAIL The image shown for the offer in the list of all offers.
IMAGE The image that is shown on the offer details page.
TERMS_AND_CONDITIONS The fine print of the offer. Specifics of the agreement and use of the offer.
OFFER_TITLE The title text shown for the offer in the list of all offers.
OFFER_DESCRIPTION The text shown at the top of the details page describing the offer.
ADDITIONAL_INFORMATION The other relevant information text shown on the details page for the offer.
SUMMARY The offer description shown in the list of all offers.
REDEMPTION_SCHEDULE Specifies the dates and times when the offer is valid for use.

OfferCampaignType

Type of campaign that generated the receipt.

Enum Description
DYNAMIC_EXPIRY The expiration of the offers can vary. For example a free birthday coffee might be valid only for the week of the recipient’s birthday.
INTEGRATED_OFFERS Offer campaigns of this type (the default if not specified) have a definitive expiration for all recipients and recipients must be a valid wallet user.
COUPONS Offers that can be sent to and used by anyone, including non-wallet owners. For example, they can be printed on flyers.

OfferProcessingPoint

The entity that calculated the offer to apply the transaction for redemption.

Enum Description
POS The POS terminal calculated the offer that was applied it to the transaction.
PAYDIANT The Paydiant platform calculated the offer that was applied to the transaction.

OfferStatus

The state of an offer that indicates its usability.

Enum Description
ACTIVE The offer is live and can be redeemed.
REDEEMED The offer has been redeemed.
REDEEM_PENDING The offer is in the process of being redeemed.
EXPIRED The offer has expired and is no longer valid.
CANCELLED The offer was rescinded.
REVERSAL_PENDING The offer was redeemed in a transaction that is being reversed.
REVERSAL_FAILED Reversal of the transaction in which the offer was redeemed failed.
VOID_PENDING The offer was redeemed in a transaction that is being voided.
REFUND_PENDING The offer was redeemed in a transaction that is being refunded.

OfferType

The type of compensation promoted by an offer.

Enum Description
VALUE_BASED_OFFER The offer is a dollar or percentage amount discount, such as $5 off or 10% off.

ReceiptType

The type of transaction for which a receipt is generated.

Enum Transaction Type
PURCHASE A standard payment or non-referenced refund.
REFUND A standard or non-paired refund.
CASH_WITHDRAWAL An ATM withdrawal.
CASH_DEPOSIT An ATM deposit.
FUEL A gas station transaction with a fuel pump.

RewardType

The type of compensation promoted by an offer.

Enum Description
VALUE_BASED The offer is a dollar or percentage amount discount, such as $5 off or 10% off.
SKU_BASED The offer gives a product reward, such as a free cookie or car wash.

TransactionSubType

Further describes the ReceiptType.

Enum Description
PAYMENT A standard payment for a purchase.
REFUND A standard refund of a previous purchase.
CASH_BACK A payment over the amount due in which cash was returned.
RETURN A refund in which a previously purchased item was returned.
SALE A purchase of an item at a discounted price.
EXCHANGE A refund in which a previously purchased item was exchanged for a different item, possibly of different value, which might result in additional payment, credit, or cash back.
PAYMENT_ON_ACCOUNT A payment toward an existing credit balance.
REWARD The payment is a loyalty reward redemption.
OTHER The transaction is of another type not represented in this enum.
NON_REFERENCE_REFUND A refund that is processed as a sale for a negative amount (credit) because the original transaction receipt is not available.
CREDIT A sale entered as a negative amount due.
FUEL A purchase of fuel from a gas station pump.
NON_PAIRED_REFUND A refund where the POS looks up the original transaction based on a paper receipt because the mobile wallet is not present.
PAIRED_REFUND A refund where the mobile user selects the original receipt within the mobile wallet.
CASH_DEPOSIT The deposited funds were made up of cash only.
CHECK_DEPOSIT The deposited funds were made up of checks only.
CASH_AND_CHECK_DEPOSIT The deposited funds were a combination of cash and checks.

Next

Feedback