Deprecated feature

WebSphere Commerce Payments payment objects

WebSphere Commerce Payments defines the following framework objects for all electronic payments, regardless of payment protocol:

WebSphere Commerce Payments uses the terms order, payment, and credit to represent payment data for all electronic payment. An Order is an object that is created as a result of a data flow between a buyer and a merchant, while the buyer is placing an order for merchandise or services. Transactions flow between the merchant and the financial institution during the Order life cycle. These transactions can be broken into two broad categories: payments (monies transferred to the merchant from the consumer) and credits (monies returned to the buyer, such as when merchandise is defective). As processing on an Order continues, Payment and Credit objects are created, modified, and destroyed.

Another type of object used by the WebSphere Commerce Payments is a batch object. A batch represents multiple transactions processed as a group, such as the deposit of all payments at the end of a business day. Batch objects in the WebSphere Commerce Payments keep track of the collections of transactions. For instance, if a financial institution tells the merchant to close out the week's transactions, the merchant will close the current batch and open a new one. Batch objects for these two batches will reflect the new status of the batches.

Order, Payment, Credit, and Batch objects each have an associated state. The state of an object determines what actions are permitted for the object. The state of an object is determined by the action, or command, that was last performed on it.

Each WebSphere Commerce Payments framework object is defined by its attributes, or fields. In the sections that follow, object tables display field names, field syntax, and field descriptions for each framework object. In addition, object state tables display the states an object can assume and field descriptions for those states.

Order

An Order represents all the instructions and information needed from the buyer (payer) in order for the merchant (payee) to collect money. The merchant may collect that money all at once, or over a period of time, but never needs to go back to the buyer for additional information. The required information is all there in the Order. The WebSphere Commerce Payments Order object describes the data included in the order. Each Order can have zero or more payments associated with it. The attributes for the Order object are:

Field name Syntax Description
merchantNumber Numeric token, 1 to 9 digits long A number that identifies the merchant that created the Order.
orderNumber Numeric token, 1 to 9 digits long A number assigned by the merchant that uniquely identifies the Order.
merchantOriginated 0 or 1 (Boolean) Value is 1, (true) if the Order was created using AcceptPayment. Value is 0, (false) if the Order was created using ReceivePayment.
amount Integer Identifies the Order amount in the smallest denomination of the particular currency used to place the Order. When combined with AmountExp10, this field specifies the amount of the full Order in the specified currency.
amountExp10 Integer Indicates the number of decimal places to shift the decimal point to reflect the currency. For example, if the amount is 2325, the currency code is for U.S. dollars, and AmountExp10 is -2, the transaction amount in U.S. dollars is $23.25.
currency Integer ISO code for currency. For example, 840 is the numeric code for a U.S. dollar, and 392 is the numeric code for a Japanese yen.
paymentType Character string Identifies the payment cassette or protocol used to place the Order (for example, OfflineCard).
timeStampCreated Date The time that this Order entry was created. The number of milliseconds since midnight January 1, 1970 GMT.
timeStampModified Date The time that this Order entry was last modified. The number of milliseconds since midnight, January 1, 1970 GMT.
state Character string The state of the Order.
  • order_requested
  • order_ordered
  • order_refundable
  • order_rejected
  • order_pending
  • order_canceled
  • order_closed
approvesAllowed 0 or 1 (Boolean) Flag indicating if approve commands are legal on this Order.
unapprovedAmount Integer Amount of the Order minus the approved amount of all Payments for that Order.
numberOfPayments Integer The number of payments associated with this Order.
numberOfCredits Integer The number of credits associated with this order.
brand Character string For credit cards: the payment card brand used to place this Order (for example, VISA or MasterCard).
orderURL URL A merchant-defined URL often used to point to information about the Order in the merchant's business system.
merchantAccount Numeric token, 1 to 9 digits long The number of the Account used to process this Order.

Assigned before the Order entered Ordered state.
transactionId Character string, 1 to 128 ASCII characters long Customer's transaction identifier. This value will only be present if a non-null TRANSACTIONID value was specified on the AcceptPayment or ReceivePayment command.
orderData1 Character string, 1 to 254 ASCII characters long This value will only be present if a non-null ORDERDATA1 value was specified on the AcceptPayment or ReceivePayment command.
orderData2 UTF-8 string, 1 to 254 bytes long This value will only be present if a non-null ORDERDATA2 value was specified on the AcceptPayment or ReceivePayment command.
orderData3 UTF-8 string, 1 to 254 bytes long This value will only be present if a non-null ORDERDATA3 value was specified on the AcceptPayment or ReceivePayment command.
orderData4 Binary string, 1 to 254 bytes long This value will only be present if a non-null ORDERDATA4 value was specified on the AcceptPayment or ReceivePayment command.
orderData5 Binary string of an arbitrary length This value will only be present if a non-null ORDERDATA5 value was specified on the AcceptPayment or ReceivePayment command.
Note: A numeric token is defined as a numeric string that is one to nine digits in length.

Order states

The state of an object determines what actions are legal for the object. The state of an object is determined by the action, or command, that was last performed on it (for example, a Payment that was approved, moves into Approved state).

Orders are in one of the following states:

State Description
Requested A preliminary state where the buyer has not yet provided all of the information necessary to complete the Order. Legal commands for this state:
  • CancelOrder
Ordered Indicates consumer/merchant server/WebSphere Commerce Payments order message flow completed successfully. WebSphere Commerce Payments can now perform commands on Payments. Legal commands for this state:
  • CloseOrder, if the order has any payments or credits associated with it, they all must be in closed state before CloseOrder is allowed; if an Order has no payments or credits associated with it, then CloseOrder is not valid.
  • CancelOrder, if one or the other is true:
    • The order has no Payments or Credits associated with it, OR
    • All Payments and Credits are in either Reset, Void, ApprovalExpired or Declined state.
  • Approve
  • ApproveReversal
  • Deposit
  • DepositReversal
Refundable WebSphere Commerce Payments can now perform commands on Payments and Credits. The point at which an Order moves from Ordered to Refundable state depends on the payment method. Legal commands for this state:
  • CloseOrder, if the order has any payments or credits associated with it, they all must be in closed state before CloseOrder is allowed; if an Order has no payments or credits associated with it, then CloseOrder is not valid.
  • Approve
  • ApproveReversal
  • Deposit
  • DepositReversal
  • Refund
  • RefundReversal
Rejected Indicates that a problem occurred during the consumer-merchant purchase flows. Legal commands for this state:
  • CancelOrder
Pending An Order is in Pending state when WebSphere Commerce Payments is performing a command on the Order. No commands are legal for Orders in this state.
Canceled This Order has been canceled. Legal commands for this state:
  • CancelOrder with the DELETEORDER flag enabled (this removes the Order from the database).
Closed This Order has been closed. Legal commands for this state:
  • CloseOrder
  • CancelOrder with the DELETEORDER flag enabled (thisl removes the Order from the database).

Payments

The Payment object represents a request by the merchant to the financial institution to approve all or part of an Order.

In many cases, all the money authorized for collection by the Order will be collected in a single payment. Some payment systems may allow the money authorized in one Order (that is, one set of payment instructions) to be collected in multiple payments, depending on the business model. There can be zero or more Payments per Order. The attributes for the Payment object are:

Field name Syntax Description
merchantNumber Numeric token, 1 to 9 digits long A number that identifies the merchant that created the Order.
orderNumber Numeric token, 1 to 9 digits long A number assigned by the merchant that uniquely identifies the Order. This field matches the orderNumber in the Orders table.
paymentNumber Numeric token, 1 to 9 digits long A unique identifier for a particular Payment within an Order.
paymentType Character string Identifies the payment cassette or protocol used to place the order (for example, VisaNet or OfflineCard).
approvedAmount Integer Amount of the Order that has been approved for Payment.
amount Integer Identifies the Payment amount in the smallest denomination of the particular currency used to place the order. When combined with AmountExp10, this field specifies the amount of the Payment in the specified currency.
amountExp10 Integer Indicates the number of decimal places to shift the decimal point to reflect the currency. For example, if the amount is 2325, the currency code is for U.S. dollars, and AmountExp10 is -2, the transaction amount in U.S. dollars is $23.25.
currency Integer The currency used to make this Payment. ISO code for currency. For example, 840 is the numeric code for a U.S. dollar, and 392 is the numeric code for a Japanese yen.
timeStampCreated Date The time that this Payment entry was created. The number of milliseconds since midnight, January 1, 1970 GMT.
timeStampModified Date The time that this Payment entry was last modified. The number of milliseconds since midnight, January 1, 1970 GMT.
state Character string The state of the Payment:
  • payment_reset
  • payment_approved
  • payment_deposited
  • payment_pending
  • payment_declined
  • payment_void
  • payment_closed
  • payment_approvalexpired
batchNumber Numeric token, 1 to 9 digits long The number that identifies the Batch.

Assigned when the Payment is deposited.
referenceNumber Character string Plain text identifier used by the financial institution to identify a Payment.
depositAmount Integer The amount deposited for this Payment (can differ from approved amount).

Assigned when deposited.
merchantAccount Numeric token, 1 to 9 digits long A number that identifies the Account used to process this Order.
order IDREF XML element representing the order associated with this payment.
approveTime Date The last time that this Payment entry was approved.
approvalExpiry Date The time that a Payment approval expires. A null value implies no expiration.

Payment states

Payments are in one of the following states:

State Description Valid commands
Reset A Payment enters Reset state when a Payment has been created, but has not yet been processed. No valid commands exist for Payments in this state, since the Approve command has not yet completed.
Approved A Payment enters Approved state when an approve command is successful. For credit cards, Approved state means that the Payment has been authorized.
  • ApproveReversal
  • Deposit
Deposited A Payment enters Deposited state when a deposit, or auto-deposit, command is successful. For credit card payment types, Deposited state means that the Payment has been captured. DepositReversal
Closed A Payment in Deposited state moves into Closed state when the Batch associated with the Payment closes. When a Payment is in Closed state, the financial transaction is complete; monies are deposited, and the Payment cannot be modified. No valid commands exist for Payments in this state.
Declined A Payment enters Declined state when an approve command is rejected for financial reasons. Approve
Void A Payment enters Void state when an ApproveReversal command for an amount of zero is successful. Approve
Pending A command is currently being performed on this Payment. No valid commands exist for Payments in this state.
ApprovalExpired The Payment moves from an Approved state to the ApprovalExpired state after the specified approval time has elapsed or the cassette has detected that the Payment authorization has expired. This is an optional state which may not be supported by a cassette. ApproveReversal

Split payments

Suppose a customer contacts an online catalog store and orders $80 of merchandise. The merchant checks the inventory and finds that only $60 worth of merchandise is in stock and can be shipped. The merchant would like to collect $60 now and the remaining $20 when the rest of the order is filled. WebSphere Commerce Payments is designed to support payment systems in which customers provide payment information aboutce (for the entire $80) and the merchant collects the funds over time ($60 now and $20 later). This is referred to as split payments.

AVS common codes

If the cassette you are using supports WebSphere Commerce Payments common AVS codes, then you can also query the commonAVSCode parameters to determine the AVS result in a cassette-independent way.

Mapping of common AVS result codes to cassette result codes follows.

Common AVS code PM constant name Description
0 AVS_COMPLETE_MATCH This constant maps both the AVS 5-digit and 9-digit postal code and street addresses. Both are exact matches.
1 AVS_STREETADDRESS_MATCH The street address matches, but the postal code does not.
2 AVS_POSTALCODE_MATCH The 5-digit or 9-digit postal code matches, but the street address does not.
3 AVS_NO_MATCH Neither the street address nor the postal code matches.
4 AVS_OTHER_RESPONSE This constant maps the address information unavailable, system unavailable (possibly due to timeout), card type not supported, and transaction ineligible AVS return codes. Some other system-related response was received from the credit card processor.

Credits

The WebSphere Commerce Payments command that creates the Credit object is called Refund. The Credit object identifies one credit made against the amount of money identified in one Order (that is, the payment agreement) object. There can be zero or more Credits per Order. The attributes for the Credit object are:

Field name Syntax Description
merchantNumber Numeric token, 1 to 9 digits long A number that identifies the merchant that created the Order.
orderNumber Numeric token, 1 to 9 digits long A number assigned by the merchant that uniquely identifies the Order. This field matches the orderNumber in the Orders table.
creditNumber Numeric token, 1 to 9 digits long A unique identifier for a particular Credit within an Order.
paymentType Character string Identifies the payment cassette or protocol used to place the order (for example, VisaNet or OfflineCard).
amount Integer Identifies the Credit amount in the smallest denomination of the particular currency used to place the order. When combined with AmountExp10, this field specifies the amount of the Credit in the specified currency.
amountExp10 Integer Indicates the number of decimal places to shift the decimal point to reflect the currency. For example, if the amount is 2325, the currency code is for U.S. dollars, and AmountExp10 is -2, the transaction amount in U.S. dollars is $23.25.
currency Integer The currency used to issue this Credit. ISO code for currency. For example, 840 is the numeric code for a U.S. dollar, and 392 is the numeric code for a Japanese yen.
timeStampCreated Date The time that this Credit entry was created. The number of milliseconds since midnight, January 1, 1970 GMT.
timeStampModified Date The time that this Credit entry was last modified. The number of milliseconds since midnight, January 1, 1970 GMT.
state Character string The state of the Credit:
  • credit_reset
  • credit_refunded
  • credit_pending
  • credit_declined
  • credit_void
  • credit_closed
batchNumber Numeric token, 1 to 9 digits long The number that identifies the Batch.

Assigned when the Payment is deposited.
referenceNumber Character string Plain text identifier used by the financial institution to identify a Payment.
merchantAccount Numeric token, 1 to 9 digits long The number of the Account used to process this Order.

Credit states

Credits are in one of the following states:

State Description
Reset A Credit enters Reset state when a Credit has been created, but has not yet been processed. No commands are legal for Credits in this state.
Refunded A Credit enters Refunded state when a refund command is successful. Legal commands for this state:
  • RefundReversal
Closed A Credit in Refunded state moves into Closed state when the Batch associated with the Credit closes. When a Credit is in Closed state, the financial transaction is complete; monies are refunded, and the Credit cannot be modified. No commands are legal for Credits in Closed state.
Declined A Credit enters Declined state when a refund command is rejected for financial reasons. Legal commands for this state:
  • Refund
Void A Credit enters Void state when a RefundReversal command for an amount of zero is successful. Legal commands for this state:
  • Refund
Pending A command is currently being performed on this Credit. No commands are legal for Credits in this state.

Batches

A Batch is a collection of financial transactions (Payments and Credits) that are processed as a unit by a financial institution. A Batch is associated with an Account and a merchant. An Account can have zero or more Batches. The attributes for the Batch object are:

Field name Syntax Description
merchantNumber Numeric token, 1 to 9 digits long The number of the merchant that owns the Batch.
merchantAccount Numeric token, 1 to 9 digits long The account number associated with the Batch.
batchNumber Numeric token, 1 to 9 digits long The number that identifies the Batch.

Assigned when the Payment is deposited.
purgeAllowed 0 or 1 (Boolean) Flag indicating if it is legal for the merchant to purge this batch. If the value is 1, (yes), the merchant can purge this batch using the BatchPurge command. If the value is 0, (no), the merchant cannot purge this batch.
forceAllowed 0 or 1 (Boolean) Flag indicating if it is legal for the merchant to issue a BatchClose command with the Force option set. If the value is 1, (yes), the merchant can issue the command.
paymentType Character string Identifies the payment cassette or protocol used to place the Order (for example, VisaNet or OfflineCard).
merchantControl 0 or 1 (Boolean) Flag indicating if it is legal for the merchant to control this batch. If the value is 1, (true), the merchant is responsible for settling this Batch. (The merchant settles the Batch by explicitly closing the Batch using the BatchClose command.) If the value is 0, (false), the merchant does nothing to settle this Batch.
timeStampOpened Date The time that this Batch was opened (either by the merchant or the financial institution). The number of milliseconds since midnight, January 1, 1970 GMT.
timeStampClosed Date The time that this Batch was closed (either by the merchant or the financial institution). The number of milliseconds since midnight, January 1, 1970 GMT.
timeStampModified Date The time that this Batch was last modified. The number of milliseconds since midnight, January 1, 1970 GMT.
state Character string The state of the Batch:
  • batch_opening
  • batch_open
  • batch_closing
  • batch_closed
batchStatus Character string The balance status of this Batch:
batch_not_ yet_ balanced
Balancing has not yet been performed on this Batch.
batch_balanced
The Batch has been balanced, and everything is in agreement.
batch_out_ of_ balance
The Batch has been balanced, and everything does not agree.

Batch states

Batches are in one of the following states:

State Description
Opening The Batch is currently being opened. No commands are legal on a Batch in Opening state.
Open Payments and Credits can be added to a Batch in Open state. Legal commands for this state:
  • CloseBatch, only if merchantControl is true.
Closing Batch is currently being settled. No commands are legal for Batches in this state.
Closed A batch in Closed state has been settled. Legal commands for this state:
  • DeleteBatch