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.
|
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. |
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:
|
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:
|
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:
|
Rejected | Indicates that a problem occurred during the consumer-merchant
purchase flows. Legal commands for this state:
|
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:
|
Closed | This Order has been closed. Legal commands for this state:
|
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:
|
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. |
|
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:
|
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:
|
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:
|
Void | A Credit enters Void state when a RefundReversal command
for an amount of zero is successful. Legal commands for this state:
|
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:
|
batchStatus | Character string | The balance status of this Batch:
|
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:
|
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:
|