Payment types

The types the payment domain defines, with the fields other domains add to them.

Objects

`ApplePayPaymentValidateResponse`

Field	Type	Description
`merchantSession`	`String`	Opaque merchant session returned by Apple, to hand to the Apple Pay SDK
`paymentErrors`	`[ApplePayPaymentValidateError!]`	Error details if validation failed

`Cart`

Fields added by Delivery options, Multiple carts and Order approval

Shopping cart containing line items and checkout information

Field	Type	Description
`id`	`ID!`	Unique identifier of the cart. Stable for the cart's whole life, so a client may key a cache on it.
`version`	`String`	Opaque optimistic-concurrency token, present only for engines that version their resources. Pass it back verbatim; never parse or compare it.
`createdAt`	`DateTime!`	Creation date of the cart
`lastModifiedAt`	`DateTime!`	Last modified date of the cart
`currency`	`Currency!`	The currency used in the cart
`customerEmail`	`String`	Customer email
`isGuest`	`Boolean!`	Indicates if the cart is a guest cart
`lineItems`	`[CartLineItem!]!`	Line items in the cart
`totalQuantity`	`Int!`	Total quantity of all line items
`changes`	`[CartLineChange!]!`	What changed since the session last acknowledged the cart, oldest first: sold-out lines, price changes against the price at the time of adding, and lowered quantities. Listed until cartChangesAcknowledge, so a notice shows them once.
`unavailableLineItems`	`[CartLineItem!]!`	Lines that cannot be ordered now, such as sold out. They are kept out of the totals and out of the order. Empty where the engine cannot keep them: those are removed instead, and listed in changes as REMOVED.
`subTotal`	`TaxedTotalPrice!`	Sum of all line items (i.e. price excluding all shipping and payment costs)
`total`	`TaxedTotalPrice!`	Sum of all line items (i.e. price including all shipping and payment costs)
`discountTotal`	`TaxedPrice`	Discount applied to the cart total, on top of any discount already reflected in the line items. A positive magnitude: subtract it, never add it. Showing it as a negative amount is a presentation choice, not a property of the data. Taxed like the amounts it has to be arithmetic with, so a summary reconciles in one basis: subTotal minus this plus shippingCosts equals total. The rate is the effective rate over the discounted goods -- exact for a single-rate basket, a blend where the basket mixes rates.
`discountCodes`	`[CartDiscountCode!]!`	Discount codes that are applied to the cart
`appliedDiscounts`	`[AppliedDiscount!]`	Every discount the cart applies, on its total, its lines or its shipping, with what it takes off in all: the names a summary explains the price with. A reduced price the product itself carries is not one of them. A discount reached through a code is also in discountCodes; the rest are automaticDiscounts. Null where the engine does not report its discounts.
`automaticDiscounts`	`[AppliedDiscount!]`	The discounts the cart gets without a code, such as an automatic promotion, each with what it takes off: the entries of appliedDiscounts that no code brought, so adding the two lists counts these twice. Together with discountCodes they explain discountTotal row by row. Null where the engine does not report its discounts.
`billingAddress`	`Address`	Customer billing address
`shippingAddress`	`Address`	Customer shipping address
`shippingCosts`	`TaxedPrice`	Shipping costs, if any
`estimatedShippingCosts`	`TaxedPrice`	What shipping will likely cost while no shipping method is set, so a summary can show a total before checkout. An estimate: null once shippingCosts is known, and where the engine has nothing to base one on.
`freeDelivery`	`CartFreeDelivery`	How far the cart is from free delivery: the goods total at which shipping becomes free, and how much is still to add. Read from the chosen shipping method's rate, or the default method's for the store's country while none is chosen. Null where that rate has no free threshold, and where the cart ships outside the store's country without a method chosen.
`complementaryProducts`	`[ProductVariant!]!`	Products to suggest alongside what is in the cart, such as below its lines: the complementary products of its lines, the most recently added line's first, without those already in the cart, and only what can be sold in the store and is in stock. At most limit of them, and never more than 10.Arguments: `limit`
`selectedShippingMethod`	`ShippingMethod`	Selected shipping method for the cart
`preselectedShippingMethod`	`ShippingMethod`	The shipping method the delivery step starts on: the selected one once there is one, otherwise the default method for the shipping address's country or, before there is an address, the store's. Its price is what the cart is charged for it, after the rate's tiers and free threshold, and with the delivery options composed its carrier and deliveryEstimate say who brings it and when. Null when no method ships there.
`selectedPaymentMethod`	`PaymentMethod`	Selected payment method for the cart
`amountToPay`	`Money!`	What the buyer still has to pay: the gross total less everything the cart's payments have reserved or collected. Equal to the gross total while no payment holds anything. A partial payment such as a gift card lowers this and never total, subTotal, discountTotal or any tax: the price of the goods is the same whoever pays for it.
`payments`	`[CartPayment!]!`	The payments on the cart, oldest first. A cart can carry several: partial payments such as gift cards, and the payment that pays the rest.
`availableShippingMethods`	`[ShippingMethod!]!`	Shipping methods that are available for the cart
`deliveryRemarks`	`String`	Note for whoever delivers the goods, as the buyer typed it -- "please leave it under the shelter". Carried to the order. Null until someone records one.
`vatNumber`	`String`	The VAT number of the company the buyer orders for, as recorded at checkout. Carried to the order. Null until someone records one. A verified number can make the cart reverse-charged; see vatOutcome.
`vatShifting`	`Money`	The amount of a reverse-charge line, negative and already reflected in total, where one is carried. A reverse-charged cart is taxed at 0% and gets no such line, so this is null on it.Deprecated: A reverse-charged cart is taxed at 0%; read vatOutcome and the taxed totals.
`vatExemption`	`Money`	The amount of an export line, negative and already reflected in total, where one is carried. An exported cart is taxed at 0% and gets no such line, so this is null on it.Deprecated: An exported cart is taxed at 0%; read vatOutcome and the taxed totals.
`vatOutcome`	`VatOutcome`	Which VAT rule the cart's amounts follow, and why, so a checkout can explain them. Decided by the delivery country and the buyer's VAT number, or for a cart bought for a business unit, the company's VAT registrations; the billing country never counts. Null until the cart has a delivery address or a pickup at the seller, and where the engine does not decide VAT itself. The rules are the standard EU rules for goods and have not been reviewed by a tax advisor.
`purchaseOrderNumber`	`String`	The buyer's own reference for this purchase, usually a purchase order number. Carried to the resulting order so a finance team can match it against their own paperwork. Null until someone records one, which only an associate of the cart's business unit can, through cartSetPurchaseOrderNumber.
`minimumOrder`B2B	`CartMinimumOrder`	The business unit's minimum order value. Null when the unit has none, when it is set in another currency than the cart's, and for a cart that is not a business unit's. Below it orderPlace is refused; requesting a quote is not.
`availablePaymentMethods`	`[PaymentMethod!]!`	Payment methods that are available for the cartArguments: `device`
`deliveryDates`	`[DeliveryDate!]!`	The dates the cart can be delivered on, each with its time slots, starting at from (today when absent) and covering the given number of days. Every date in the range is listed, including those with nothing to offer, so a date picker can show them disabled with their reason. Empty while the cart has no shipping address to deliver to.Arguments: `from`, `days`
`deliverySlot`	`DeliverySlot`	The delivery slot chosen for the cart. Null until one is chosen.
`pickupPoints`	`[PickupPoint!]!`	Pickup points the cart can be collected from, nearest first, including those that cannot be chosen. Searched around near, or the shipping address when near is absent; empty when there is neither. carrierKeys narrows the list to those carriers.Arguments: `near`, `carrierKeys`, `limit`
`pickupPoint`	`PickupPoint`	The pickup point chosen for the cart. Null until one is chosen.
`deliverySplit`	`DeliverySplitType!`	Whether the cart ships once, when every line is in stock, or ships what is in stock now and the backordered rest later. COMPLETE until chosen.
`requestedDeliveryDate`	`Date`	The date the buyer asked to receive the delivery on. Null until asked.
`earliestCompleteDeliveryDate`	`Date`	The first date every line is in stock, which is when a complete delivery can leave at the earliest. Null when nothing is backordered, or when a backordered line has no expected date; the lines say which.
`name`	`String`	Buyer-given name, to tell one cart from another. Null until a cart is named.
`defaultName`	`String`	What to call the cart while it has no name: its first product, then a plus and the number of further products, such as "Accuboormachine + 2". Language-neutral, so a storefront needs no wording for it. Given whether or not the cart is named; null for an empty cart, where a storefront shows its own label.
`previewImages`	`[ProductImage!]!`	Images of the cart's first products, one per line in the order they were added and none repeated, so a cart list shows what each cart holds. Add-ons are left out, as is a line without an image. At most 10, whatever the limit asks for; empty for an empty cart.Arguments: `limit`
`owner`	`Customer`	The person whose cart this is. Null for a guest cart, which belongs to a session rather than to anyone.
`status`	`CartStatusType!`	Whether the cart is in use or archived. A cart nobody has touched for 60 days, or the period the service configures, is archived: it leaves the unit's cart list unless that is asked for. The caller's current cart is never archived, so choosing one with cartSetCurrent makes it read ACTIVE.
`approvalRequirement`	`CartApprovalRequirement`	What placing the cart now waits for. Null when it needs no approval, and for a cart that is not a business unit's.

`PaymentCancelResponse`

Response for withdrawing a payment the shopper abandoned

Field	Type	Description
`success`	`Boolean!`	Whether the payment was withdrawn and its cart released
`paymentErrors`	`[PaymentCancelError!]`	Error details if the payment could not be withdrawn

`PaymentComplete`

A payment that needs nothing further from the shopper. Buying on account is the case: credit is granted at checkout, an invoice follows, and there is no provider page to visit.

The order is the one the payment settled, which a caller paying a cart has no other way to learn -- it may not have existed when the call was made.

Field	Type	Description
`payment`	`Payment!`	The payment that was created
`order`	`Order`	The order the payment settled, where the payment settled one. Null while the payment covers only part of a cart: the order comes when the payments add up to the total, so check Cart.amountToPay.

`PaymentCreateResponse`

Response for creating a payment

Field	Type	Description
`next`	`PaymentNext`	What the shopper does next, when payment creation succeeded
`paymentErrors`	`[PaymentCreateError!]`	Error details if payment creation failed

`PaymentDetailsSubmitResponse`

Response for continuing a payment with what the provider's component reported

Field	Type	Description
`next`	`PaymentNext`	What the shopper does next, when the details were accepted
`paymentErrors`	`[PaymentDetailsSubmitError!]`	Error details if the payment could not be continued

`PaymentError`

Implements Error

Error that occurred during payment creation

Field	Type	Description
`code`	`PaymentErrorCodeType!`	Error code indicating the specific payment creation failure
`message`	`String!`	Human readable error message describing the payment creation failure. Not intended for end users.

`PaymentExpressCheckoutUpdateResponse`

Response for updating a wallet payment in progress

Field	Type	Description
`paymentData`	`String`	The data the wallet continues with, which replaces what it had. Null when the update failed.
`paymentErrors`	`[PaymentExpressCheckoutUpdateError!]`	Error details if the payment could not be updated

`PaymentPending`

A payment that covers what was owed, which the provider is still confirming. Nothing further is needed from the shopper: the order follows once the provider reports the outcome.

Field	Type	Description
`payment`	`Payment!`	The payment the provider is confirming

`PaymentSdkAction`

A payment the provider's own component carries on in the page, such as the PayPal button: the payment exists before the shopper has approved anything, and before there is an order.

Hand action to that component as it is. When the component reports what the shopper did, send that with paymentDetailsSubmit.

Field	Type	Description
`payment`	`Payment!`	The payment that was created
`provider`	`String!`	The provider whose component continues the payment
`action`	`JSON!`	The provider's action, verbatim, for its component to continue with

Input objects

`ApplePayPaymentContextInput`

Input for Apple Pay payment validation

Field	Type	Description
`merchantIdentifier`	`String!`	Merchant identifier
`domainName`	`String!`	Domain name for validation
`displayName`	`String!`	Display name for the merchant

`PaymentContextInput`

Input for payment context when completing checkout or creating a payment

Field	Type	Description
`method`	`PaymentMethodInput!`	Payment method details
`successUrl`	`URL!`	URL to redirect to on successful payment
`cancelUrl`	`URL!`	URL to redirect to on cancelled payment
`failureUrl`	`URL!`	URL to redirect to on failed payment

`PaymentMethodArgumentInput`

Input for payment method argument key-value pairs

Field	Type	Description
`key`	`String!`	Argument key
`value`	`String!`	Argument value

`PaymentMethodInput`

Input for selecting a payment method

Field	Type	Description
`internalId`	`String!`	Internal ID of the payment method
`provider`	`String!`	Payment provider name
`arguments`	`[PaymentMethodArgumentInput!]`	Additional arguments for the payment method

`PaymentTargetInput`

What a payment is being made against

Field	Type	Description
`id`	`ID!`	Identifier of the cart or order being paid
`type`	`PaymentTargetType!`	Whether the id names a cart or an order

Enums

`PaymentErrorCodeType`

Error codes for payment creation failures

`TARGET_NOT_FOUND`	The cart or order does not exist, or the caller may not reach it
`TARGET_NOT_PAYABLE`	The cart or order is in a state that cannot be paid, such as a cart that has already been ordered or merged away.
`ORDER_ALREADY_PAID`	The order is already paid for, so paying it again would take the money twice
`ORDER_AWAITING_APPROVAL`	The order is held by an approval flow that nobody has decided yet. It becomes payable once the flow is approved.
`PAYMENT_IN_PROGRESS`	The order already carries a payment whose outcome is still open, so a second one would be a double submission. Wait for the provider to report the outcome; a payment that failed does not block a retry.
`PARTIAL_NOT_ALLOWED`	The method cannot be combined with the payments the cart already holds. Paying on account settles the whole order as owed, so it cannot pay what is left after a part payment.
`PAYMENT_CREATION_FAILED`	Failed to create payment with provider
`TRANSACTION_START_FAILED`	The payment was created but the provider would not start the transaction. Nothing was charged and the attempt left no live payment behind, so the same order can be paid again.
`INVALID_PAYMENT_METHOD`	Invalid payment method or arguments provided
`UPDATE_NOT_SUPPORTED`	The payment's provider cannot update a wallet payment in progress.
`PAYMENT_REFUSED`	The provider declined the payment. Nothing was charged and a cart is open again, so the shopper may pay another way.

`PaymentTargetType`

Target type for payment operations

`CART`	Payment targets a cart
`ORDER`	Payment targets an order
`INVOICE`	Payment settles an invoice, on its own rather than through the orders it bills. What is charged is the outstanding balance, never the total. Declared here rather than added by the invoice module: an enum value is not a type reference, and a client sending it to a deployment without invoices gets a plain refusal instead of a schema that changes shape underneath it.

Unions

`PaymentExpressCheckoutUpdateError`

Error union for updating a wallet payment in progress

One of PaymentError or ValidationError.

`PaymentNext`

What has to happen next for a payment that was created successfully. The shopper goes somewhere, the provider's component in the page carries on, the provider is still confirming, or nothing further is needed.

This is a union rather than a nullable redirect because a payment that finished and a payment whose destination went missing are different facts, and a caller cannot tell them apart from an absent field.

One of PaymentRedirect, PaymentComplete, PaymentSdkAction or PaymentPending.

Get started

Guides

Conventions

Reference

Architecture

Changelog