commerce/orders/payments

Use the Payments subresource to manage payment transactions for orders. Each transaction performed for an order represents an individual payment. For example, if an order totals $75.00 but the shopper has a $50.00 gift certificate, both the gift certificate transaction and the credit card transaction for the remaining $25.00 are recorded as payments for the order.

JSON Example

Payment Properties

Property Description
amountCollected

type: decimal

The total monetary amount collected in this payment transaction for the order.

amountCredited

type: decimal

If the payment transaction is a shopper store credit, the total monetary amount credited in this payment transaction for the order.

amountRequested

type: decimal

The total amount originally requested for this payment.

auditInfo

type: auditInfo

Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.

auditInfo.createBy

type: string

Identifier of the user that created the object. System created and read only.

auditInfo.createDate

type: DateTime

The date and time in UTC format set when the object was created.

auditInfo.updateBy

type: string

Identifier of the user that updated the entity most recently.

auditInfo.updateDate

type: DateTime

The date and time in UTC format the object was updated most recently.

availableActions

type: list of string

Available actions you can complete for an order. These actions may differ depending on the status of the order, such as actions required to enter a payment, return of a package, and fulfillment of a shipment.

billingInfo

type: billingInfo

Properties for the customer's billing information associated with an order or specific payment.

billingInfo.auditInfo

type: auditInfo

Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.

billingInfo.auditInfo.createBy

type: string

Identifier of the user that created the object. System created and read only.

billingInfo.auditInfo.createDate

type: DateTime

The date and time in UTC format set when the object was created.

billingInfo.auditInfo.updateBy

type: string

Identifier of the user that updated the entity most recently.

billingInfo.auditInfo.updateDate

type: DateTime

The date and time in UTC format the object was updated most recently.

billingInfo.billingContact

type: contact

The cardholder's billing contact information, including addresses.

billingInfo.contact.address

type: address

Address information to supply for a contact.

billingInfo.contact.address.address1

type: string

Physical or mailing address line one. Usually includes the street number and street name or it could be a P.O. Box. Max length: 200.

billingInfo.contact.address.address2

type: string

Physical or mailing address line two. Usually supplements the main street address with apartment, floor, suite, building, or unit information. Max length: 200.

billingInfo.contact.address.address3

type: string

Physical or mailing address line three. Max length: 200.

billingInfo.contact.address.address4

type: string

Physical or mailing address line four. Max length: 200.

billingInfo.contact.address.addressType

type: string

The type of address, which is commercial or residential.

billingInfo.contact.address.cityOrTown

type: string

The entered city or town for the address.

billingInfo.contact.address.countryCode

type: string

The 2-letter geographic code representing the country for the physical or mailing address. Currently limited to the US.

billingInfo.contact.address.isValidated

type: bool

Indicates if the address has been validated. If true, the address has been verified by an address validation service.

billingInfo.contact.address.postalOrZipCode

type: string

The entered zip or postal code for an address.

billingInfo.contact.address.stateOrProvince

type: string

The entered state or province for an address.

billingInfo.contact.companyOrOrganization

type: string

The entered company or organization name entered for a customer account.

billingInfo.contact.email

type: string

The email address for the customer account and contact. This email may be used for login to the storefront, receiving in-stock product notifications, and subscription mailing lists.

billingInfo.contact.firstName

type: string

The full first name of a customer or contact name.

billingInfo.contact.id

type: int

Unique identifier of the source property, such as a catalog, discount, order, or email template.

For a product field it will be the name of the field.

For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID.

For a product attribute it will be the Attribute FQN.

For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366
or
bba0a1a8-85e2-413b-b097-ceacf7bac366.

For email templates, the ID must be one of the following values:
BackInStock
OrderChanged
OrderShipped
OrderFulfillmentDetailsChanged
ShopperLoginCreated
ShopperPasswordReset
ReturnCreated
ReturnAuthorized
ReturnUpdated
ReturnRejected
ReturnCancelled
ReturnClosed
RefundCreated
StoreCreditCreated
StoreCreditUpdated
GiftCardCreated

billingInfo.contact.lastNameOrSurname

type: string

The full last name or surname of a customer or contact name.

billingInfo.contact.middleNameOrInitial

type: string

Character string of the middle name or initial for the customer.

billingInfo.contact.phoneNumbers

type: phone

List of phone numbers associated with the customer account contact. The phone numbers include area codes.

billingInfo.contact.phone.home

type: string

Home phone number.

billingInfo.contact.phone.mobile

type: string

Mobile phone number.

billingInfo.contact.phone.work

type: string

Work phone number.

billingInfo.card

type: paymentCard

Properties of a credit card used to submit payment for an order.

billingInfo.paymentCard.bin

type: string

The bin number of a branded credit card.

billingInfo.paymentCard.cardNumberPartOrMask

type: string

The masked credit card number part returned from the payment gateway.

billingInfo.paymentCard.expireMonth

type: short

The two-digit month a credit card expires for a payment method.

billingInfo.paymentCard.expireYear

type: short

The four-digit year the credit card expires for a payment method.

billingInfo.paymentCard.isCardInfoSaved

type: bool

If true, the credit card information is saved to the customer account for future use.

billingInfo.paymentCard.isUsedRecurring

type: bool

If true, the credit card is used for a recurring order payment.

billingInfo.paymentCard.nameOnCard

type: string

The full name printed on a credit card. The name should match what is printed on the card exactly, used in validation during a payment.

billingInfo.paymentCard.paymentOrCardType

type: string

The type of credit card, such as Visa or Amex.

billingInfo.paymentCard.paymentServiceCardId

type: string

Unique identifier of the credit card from the payment service.

billingInfo.check

type: checkPayment

Information about the check used in the billing information, if it exists.

billingInfo.checkPayment.checkNumber

type: string

If applicable, the check number associated with the payment action or interaction.

billingInfo.customCreditType

type: string

Indicates a custom reward type.

billingInfo.data

type: Mozu.Core.Api.Contracts.Json

Custom data originated by the billing service.

billingInfo.externalTransactionId

type: string

Holds the transaction ID for an external payment type service.

billingInfo.isSameBillingShippingAddress

type: bool

If true, the system overrides the customer's billing address information with the supplied fulfillment information.

billingInfo.paymentType

type: string

The type of payment, such as credit card, check, or PayPal Express. Additional payment types will be supported in future releases.

billingInfo.paymentWorkflow

type: string

Identifies a specific workflow the payment goes through. This is used to define a workflow for external payment services.

billingInfo.purchaseOrder

type: purchaseOrderPayment

The purchase order payment details.

billingInfo.purchaseOrderPayment.customFields

type: list of purchaseOrderCustomField

Details of the custom text fields associated with the purchase order.

Refer to Custom Text Fields in the Purchase Order guides topic for more information.

billingInfo.purchaseOrderPayment.purchaseOrderCustomField.code

type: string

The unique identifier of the object.

billingInfo.purchaseOrderPayment.purchaseOrderCustomField.label

type: string

Descriptive text used as a label for objects, such as field names, facets, date ranges, contact information, and package information.

billingInfo.purchaseOrderPayment.purchaseOrderCustomField.value

type: string

The value of a property, used by numerous objects within Kibo eCommerce including facets, attributes, products, localized content, metadata, capabilities (Kibo eCommerce and third-party), location inventory adjustment, and more. The value may be a string, integer, or double. Validation may be run against the entered and saved values depending on the object type.

billingInfo.purchaseOrderPayment.paymentTerm

type: purchaseOrderPaymentTerm

The details of the payment terms. The payment terms are made up of a code and a description.

Refer to Payment Terms in the Purchase Order guides topic for more information.

billingInfo.purchaseOrderPayment.purchaseOrderPaymentTerm.code

type: string

The unique identifier of the object.

billingInfo.purchaseOrderPayment.purchaseOrderPaymentTerm.description

type: string

The localized description in text for the object, displayed per the locale code. For example, descriptions are used for product descriptions, attributes, and pre-authorization transaction types.

billingInfo.purchaseOrderPayment.purchaseOrderNumber

type: string

The purchase order number.

Note:  Kibo eCommerce does not validate the purchase order number by default; however, you can add validation functionality using Arc.js. Refer to Validate Purchase Orders During the Checkout Process in the Arc.js Guides for more information and examples.

billingInfo.storeCreditCode

type: string

The code that identifies the store credit to apply to the order.

billingInfo.storeCreditType

type: string

A payment referring to a store credit or gift card.

  • StoreCredit
  • GiftCard
  • Custom

StoreCredit and GiftCard are internally managed by Kibo eComm. Use Custom for externally managed gift cards or reward systems. If Custom is used, provide the name for the custom type in the CustomCreditType field.

billingInfo.token

type: paymentToken

The token to access billing information.

billingInfo.paymentToken.paymentServiceTokenId

type: string

The identifier of the payment service token.

billingInfo.paymentToken.type

type: string

The type of scope, which is a developer account or production tenant.

changeMessages

type: list of changeMessage

Collection (list or paged) of change messages logged for each modification made by a shopper to their carts, wishlists, orders, package, payment, pickup, and returns. Change log messages are system-supplied based on shopper actions and read only.

changeMessage.amount

type: decimal

The amount of the order-level adjustment, which can be a positive or negative amount.

changeMessage.appId

type: string

Unique identifier of an app available in your Kibo eCommerce tenant or within Kibo eCommerce Dev Center. This ID is unique across all apps installed, initialized, and enabled in the Admin and those in development through the Dev Center Console.

changeMessage.appKey

type: string

The application's key.

changeMessage.appName

type: string

The application's name.

changeMessage.correlationId

type: string

The unique identifier of the API request associated with the event action, which might contain multiple actions.

changeMessage.createDate

type: DateTime

The date and time in UTC format set when the object was created.

changeMessage.id

type: string

Unique identifier of the source property, such as a catalog, discount, order, or email template.

For a product field it will be the name of the field.

For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID.

For a product attribute it will be the Attribute FQN.

For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366
or
bba0a1a8-85e2-413b-b097-ceacf7bac366.

For email templates, the ID must be one of the following values:
BackInStock
OrderChanged
OrderShipped
OrderFulfillmentDetailsChanged
ShopperLoginCreated
ShopperPasswordReset
ReturnCreated
ReturnAuthorized
ReturnUpdated
ReturnRejected
ReturnCancelled
ReturnClosed
RefundCreated
StoreCreditCreated
StoreCreditUpdated
GiftCardCreated

changeMessage.identifier

type: string

Identifier for the object associated with the change message, which can represent a cart, cart item, or an order.

changeMessage.message

type: string

The text of the change message, such as "This product is no longer available." System-supplied and read-only.

changeMessage.metadata

type: object

Metadata content for entities, used by document lists, document type lists, document type, views, entity lists, and list views.

changeMessage.newValue

type: string

The new value of the object affected by the change, such as the new price of the product. System-supplied and read-only.

changeMessage.oldValue

type: string

The prior value of the object affected by the change, such as the price of the product when it was added to the cart. System-supplied and read-only.

changeMessage.subject

type: string

The text that appears on the subject line of the message, such as "The product price has changed."

changeMessage.subjectType

type: string

Represents the type of object affected by the change, such as Cart Item or Product. System-supplied and read-only.

changeMessage.success

type: bool

If true, the change associated with the message executed successfully.

changeMessage.userFirstName

type: string

The user's first name.

changeMessage.userId

type: string

Unique identifier of the customer account (shopper or system user). System-supplied and read-only. If the shopper user is anonymous, the user ID represents a system-generated user ID string.

changeMessage.userLastName

type: string

The user's last name.

changeMessage.userScopeType

type: string

The user type (e.g. Shopper, Admin, etc.).

changeMessage.verb

type: string

The action associated with this message. For example, if the price of a product changes, the verb could be "Increased" or "Decreased". If the product is no longer available, the verb could be "Invalidated". System-supplied and read-only.

data

type: Mozu.Core.Api.Contracts.Json

Custom data originated by the payment service.

externalTransactionId

type: string

The external/third party transaction Id for this payment. This is used to store the transaction Id from digital wallet like Visa Checkout

groupId

type: paymentActionTarget

The parent group Id that this payment belongs to. This will refer to the parent checkout in the case of a multi-ship order, or the parent order in the case of a non-multi-ship order. This will (eventually) allow us to find all payments associated with a checkout, even if the payment is added directly to one of the child orders.

paymentActionTarget.targetId

type: string

The Id of the checkout/order to target.

paymentActionTarget.targetNumber

type: int

The number of the checkout/order to target.

paymentActionTarget.targetType

type: string

Specifies if the TargetId is a checkout Id or order Id.

id

type: string

Unique identifier of the source property, such as a catalog, discount, order, or email template.

For a product field it will be the name of the field.

For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID.

For a product attribute it will be the Attribute FQN.

For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366
or
bba0a1a8-85e2-413b-b097-ceacf7bac366.

For email templates, the ID must be one of the following values:
BackInStock
OrderChanged
OrderShipped
OrderFulfillmentDetailsChanged
ShopperLoginCreated
ShopperPasswordReset
ReturnCreated
ReturnAuthorized
ReturnUpdated
ReturnRejected
ReturnCancelled
ReturnClosed
RefundCreated
StoreCreditCreated
StoreCreditUpdated
GiftCardCreated

interactions

type: list of paymentInteraction

Container for the interactions associated with the payment, which includes details for each action performed for the payment.

paymentInteraction.amount

type: decimal

The amount of the order-level adjustment, which can be a positive or negative amount.

paymentInteraction.auditInfo

type: auditInfo

Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.

paymentInteraction.auditInfo.createBy

type: string

Identifier of the user that created the object. System created and read only.

paymentInteraction.auditInfo.createDate

type: DateTime

The date and time in UTC format set when the object was created.

paymentInteraction.auditInfo.updateBy

type: string

Identifier of the user that updated the entity most recently.

paymentInteraction.auditInfo.updateDate

type: DateTime

The date and time in UTC format the object was updated most recently.

paymentInteraction.checkNumber

type: string

If applicable, the check number associated with the payment action or interaction.

paymentInteraction.currencyCode

type: string

The localized currency code for the monetary amount.

paymentInteraction.gatewayAuthCode

type: string

If required by the payment gateway, the authorization code of the transaction.

paymentInteraction.gatewayAVSCodes

type: string

AVS (Address Verification Service) codes supplied by the payment gateway. The codes indicate partial to complete or failed matches against the billing address for the shopper against the financial institute data through the gateway.

paymentInteraction.gatewayCVV2Codes

type: string

CVV2 (Card Verification Value) codes supplied by the payment gateway. The codes indicate a verified or failed match of the encrypted code entered against the financial institution data through the gateway.

paymentInteraction.gatewayInteractionId

type: int

Unique identifier of the payment interaction from the payment gateway.

paymentInteraction.gatewayResponseCode

type: string

Response code from the gateway associated with the payment interaction. The response code is unique to the gateway.

The response code is associated with the gatewayResponseText, which contains the textual response message.

Refer to Gateway Response Code and Text in the API Guides for more information.

paymentInteraction.gatewayResponseData

type: list of paymentGatewayResponseData

Additional response data from the gateway that's unique to each gateway.

This is a list of key value pairs.

Refer to Gateway Response Data in the API Guides for more information.

paymentInteraction.paymentGatewayResponseData.key

type: string

Key used for metadata defined for objects, including extensible attributes, custom attributes associated with a shipping provider, and search synonyms definitions. This content may be user-defined depending on the object and usage.

For search synonym definitions, refer to Synonym Expansion Types for more information about the key usage.

paymentInteraction.paymentGatewayResponseData.value

type: string

The value of a property, used by numerous objects within Kibo eCommerce including facets, attributes, products, localized content, metadata, capabilities (Kibo eCommerce and third-party), location inventory adjustment, and more. The value may be a string, integer, or double. Validation may be run against the entered and saved values depending on the object type.

paymentInteraction.gatewayResponseText

type: string

Textual message returned by the payment gateway for the associated gatewayResponseCode.

Refer to Gateway Response Code and Text in the API Guides for more information.

paymentInteraction.gatewayTransactionId

type: string

Unique identifier of the gateway transaction associated with the payment interaction.

paymentInteraction.id

type: string

Unique identifier of the source property, such as a catalog, discount, order, or email template.

For a product field it will be the name of the field.

For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID.

For a product attribute it will be the Attribute FQN.

For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366
or
bba0a1a8-85e2-413b-b097-ceacf7bac366.

For email templates, the ID must be one of the following values:
BackInStock
OrderChanged
OrderShipped
OrderFulfillmentDetailsChanged
ShopperLoginCreated
ShopperPasswordReset
ReturnCreated
ReturnAuthorized
ReturnUpdated
ReturnRejected
ReturnCancelled
ReturnClosed
RefundCreated
StoreCreditCreated
StoreCreditUpdated
GiftCardCreated

paymentInteraction.interactionDate

type: DateTime

Date and time of a payment interaction, including handling and processing a payment and validating and completing a payment with a payment gateway.

paymentInteraction.interactionType

type: string

The type of payment interaction. The payment can be Capture or CheckReceived. The value also includes customer payment interactions such as Website, Call, Store, or Unknown.

paymentInteraction.isManual

type: bool

If true, the payment interaction was manually defined s part of offline order processing.

paymentInteraction.isRecurring

type: bool

Indicates if the product in a cart, order, or wish list is purchased on a recurring schedule. If true, the item can be purchased or fulfilled at regular intervals, such as a monthly billing cycle. For example, digital or physical product subscriptions are recurring cart items. This property is not used at this time and is reserved for future functionality.

paymentInteraction.note

type: string

User-entered notation content for an object, used to save information such as payment, return, account, and order notes.

paymentInteraction.orderId

type: string

Unique identifier of the order associated with the payment.

paymentInteraction.paymentEntryStatus

type: string

The status of the payment prior to the interaction being performed, which enables manual rollback of previous transactions.

paymentInteraction.paymentId

type: string

Unique identifier of the payment associated with this transaction.

paymentInteraction.paymentTransactionInteractionIdReference

type: int

Unique identifier of previous interaction that this payment interaction is modifying. For example, when refunding a payment, the crediting interaction would reference the capture interaction.

paymentInteraction.refundId

type: string

The unique identifier of the refund for a given interaction.

paymentInteraction.returnId

type: string

The unique identifier of the return associated with a given interaction.

paymentInteraction.status

type: string

The current status of the object.

This value is read only. Valid values for this field are: "Active", "Expired", and "Inactive".

paymentInteraction.target

type: paymentActionTarget

Targets represent the object, such as an item to apply discounts to(products or orders) or a view field for content. Targets are the dot notations that link to the source document property. For example, firstitem for the direct level or firstitem.seconditem.thirditem for a deeper property.

paymentInteraction.paymentActionTarget.targetId

type: string

The Id of the checkout/order to target.

paymentInteraction.paymentActionTarget.targetNumber

type: int

The number of the checkout/order to target.

paymentInteraction.paymentActionTarget.targetType

type: string

Specifies if the TargetId is a checkout Id or order Id.

isRecurring

type: bool

Indicates if the product in a cart, order, or wish list is purchased on a recurring schedule. If true, the item can be purchased or fulfilled at regular intervals, such as a monthly billing cycle. For example, digital or physical product subscriptions are recurring cart items. This property is not used at this time and is reserved for future functionality.

orderId

type: string

Unique identifier of the order associated with the payment.

paymentServiceTransactionId

type: string

The transaction ID supplied by the payment service to associate with this order payment.

paymentType

type: string

The type of payment, such as credit card, check, or PayPal Express. Additional payment types will be supported in future releases.

paymentWorkflow

type: string

The source of data for this payment. By default, this will be set to 'mozu'

status

type: string

The current status of the object.

This value is read only. Valid values for this field are: "Active", "Expired", and "Inactive".

subPayments

type: list of subPayment

List of sub-payments that correspond to child orders in case of multiship orders. Used for tracking each order's portion of a shared payment.

subPayment.amountCollected

type: decimal

The amount collected for that portion of the payment.

subPayment.amountCredited

type: decimal

The amount credited back for that portion of the payment.

subPayment.amountRefunded

type: decimal

The amount refunded for that portion of the payment.

subPayment.amountRequested

type: decimal

The amount requested for that portion of the payment.

subPayment.status

type: string

The current status of the object.

This value is read only. Valid values for this field are: "Active", "Expired", and "Inactive".

subPayment.target

type: paymentActionTarget

Targets represent the object, such as an item to apply discounts to(products or orders) or a view field for content. Targets are the dot notations that link to the source document property. For example, firstitem for the direct level or firstitem.seconditem.thirditem for a deeper property.

subPayment.paymentActionTarget.targetId

type: string

The Id of the checkout/order to target.

subPayment.paymentActionTarget.targetNumber

type: int

The number of the checkout/order to target.

subPayment.paymentActionTarget.targetType

type: string

Specifies if the TargetId is a checkout Id or order Id.

Operations

Operation Name Request URI Description
CreatePaymentAction POST %7borderId%7d%2fpayments%2factions%3fresponseFields%3d%7bresponseFields%7d

Creates a new payment transaction for the specified order and performs the specified action.

GetAvailablePaymentActions GET %7borderId%7d%2fpayments%2f%7bpaymentId%7d%2factions

Retrieves the list of all available payment actions dependent on the order payment status by specifying the order ID.

GetPayment GET %7borderId%7d%2fpayments%2f%7bpaymentId%7d%3fresponseFields%3d%7bresponseFields%7d

Retrieves information about a specific payment transaction submitted for the specified order.

GetPayments GET %7borderId%7d%2fpayments%2f%3fresponseFields%3d%7bresponseFields%7d

Retrieves information about all payment transactions submitted for the specified order.

PerformPaymentAction POST %7borderId%7d%2fpayments%2f%7bpaymentId%7d%2factions%3fresponseFields%3d%7bresponseFields%7d

Performs the specified action for an individual order payment transaction.