> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # GetPaymentSettings # Package: paymentSettings # Namespace: PaymentSettingsSPI # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/payment-settings/payment-settings-integration-service-plugin/get-payment-settings.md ## Introduction This method retrieves payment settings from your app. Wix calls this method during the payment process. For example, when a customer inserts credit card details and places an order. This method retrieves the payment settings to apply, and Wix passes on the settings to the payment provider. --- ## REST API ### Schema ``` Method: getPaymentSettings Description: This method retrieves payment settings from your app. Wix calls this method during the payment process. For example, when a customer inserts credit card details and places an order. This method retrieves the payment settings to apply, and Wix passes on the settings to the payment provider. URL: null Method: POST Method parameters: param name: order | type: Order | description: An order represents a completed purchase from a buyer. Orders are created through the checkout flow or manually via the Create Order endpoint. The order contains details about purchased items, buyer and recipient information, pricing, tax, shipping, fulfillment status, and payment status. To get the total sum of all discounts applied to an order, use `priceSummary.discount.amount`. - name: buyerInfo | type: BuyerInfo | description: Buyer information. - ONE-OF: - name: visitorId | type: string | description: Visitor GUID. Returned when the buyer isn't a logged-in site member. - name: memberId | type: string | description: Member GUID. Returned when the buyer is a logged-in site member. - name: contactId | type: string | description: Contact GUID. Automatically created if one doesn't exist. For more information, see [Contacts API](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/introduction.md). - name: email | type: string | description: Buyer's email address. - name: paymentStatus | type: PaymentStatus | description: Order payment status. - enum: - UNSPECIFIED: - NOT_PAID: `NOT_PAID` can apply to an order made online, but not yet paid. In such cases `order.status` will be `INITIALIZED`. This status also applies when an offline order needs to be manually marked as paid. In such cases `order.status` will be `APPROVED`. - PAID: All required payments associated with this order are paid. - PARTIALLY_REFUNDED: Order partially refunded, but the refunded amount is less than the order's total price. See `order.balanceSummary` for more details. - FULLY_REFUNDED: Order fully refunded. Refund amount equals total price. See `order.balanceSummary` for more details. - PENDING: All payments pending. This can happen with two-step payments, when a payment requires manual review, or when a payment is in progress and will be concluded shortly. Learn more about [pending orders](https://support.wix.com/en/article/pending-orders). - PARTIALLY_PAID: At least one payment received and approved, but it covers less than the order's total price. See `order.balanceSummary` for more details. - PENDING_MERCHANT: Payment received, but not yet confirmed by the payment provider. In most cases, when a payment provider is holding payment it's because setup hasn't been successfully completed by the merchant/site owner. To solve this, the merchant/site owner should log in to the payment provider's dashboard and make sure their account is set up correctly, or contact their support for further assistance. - CANCELED: One or more payments canceled. - DECLINED: One or more payments declined. - name: buyerLanguage | type: string | description: Language for communication with the buyer. Defaults to the site language. For a site that supports multiple languages, this is the language the buyer selected. - name: weightUnit | type: WeightUnit | description: Weight measurement unit - defaults to site's weight unit. - enum: - UNSPECIFIED_WEIGHT_UNIT: Weight unit can't be classified due to an error. - KG: Kilograms. - LB: Pounds. - name: currency | type: string | description: Currency used for the pricing of this order in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) format. - name: currencyConversionDetails | type: CurrencyConversionDetails | description: Currency conversion details. For use with multi-currency sites. - name: taxIncludedInPrices | type: boolean | description: Whether tax is included in line item prices. - name: billingInfo | type: AddressWithContact | description: Billing address and contact details. - name: address | type: Address | description: Address. - name: country | type: string | description: Two-letter country code in [ISO-3166 alpha-2](https://www.iso.org/obp/ui/#search/code/) format. - name: subdivision | type: string | description: Code for a subdivision (such as state, prefecture, or province) in [ISO 3166-2](https://www.iso.org/standard/72483.html) format. - name: city | type: string | description: City name. - name: postalCode | type: string | description: Postal or zip code. - name: streetAddress | type: StreetAddress | description: Street address. - name: number | type: string | description: Street number. - name: name | type: string | description: Street name. - name: addressLine | type: string | description: Main address line (usually street name and number). - name: addressLine2 | type: string | description: Free text providing more detailed address info. Usually contains apt, suite, floor. - name: geocode | type: AddressLocation | description: Geocode object containing latitude and longitude coordinates. - name: latitude | type: number | description: Address latitude. - name: longitude | type: number | description: Address longitude. - name: contactDetails | type: FullAddressContactDetails | description: Contact details. - name: firstName | type: string | description: First name. - name: lastName | type: string | description: Last name. - name: phone | type: string | description: Phone number. - name: company | type: string | description: Company name. - name: vatId | type: VatId | description: Tax information (for Brazil only). If GUID is provided, `vatId.type` must also be set, `UNSPECIFIED` is not allowed. - name: id | type: string | description: Customer's tax GUID. - name: type | type: VatType | description: Tax type. Supported values: + `CPF`: for individual tax payers + `CNPJ`: for corporations - enum: - UNSPECIFIED: - CPF: CPF - for individual tax payers. - CNPJ: CNPJ - for corporations - name: shippingInfo | type: ShippingInformation | description: Shipping info and selected shipping option details. - name: carrierId | type: string | description: App Def Id of external provider which was a source of shipping info - name: code | type: string | description: Unique code (or GUID) of selected shipping option. For example, `"usps_std_overnight"`. - name: title | type: string | description: Shipping option title. For example, `"USPS Standard Overnight Delivery"`, `"Standard"` or `"First-Class Package International"`. - name: logistics | type: DeliveryLogistics | description: Shipping logistics. - ONE-OF: - name: shippingDestination | type: AddressWithContact | description: Shipping destination address and contact details. For pickup orders, this contains the pickup location address, not the recipient's address. - name: pickupDetails | type: PickupDetails | description: Pickup details for store pickup or pickup point orders. - name: address | type: PickupAddress | description: Pickup address. - name: country | type: string | description: Two-letter country code in [ISO-3166 alpha-2](https://www.iso.org/obp/ui/#search/code/) format. - name: subdivision | type: string | description: Code for a subdivision (such as state, prefecture, or province) in [ISO 3166-2](https://www.iso.org/standard/72483.html) format. - name: city | type: string | description: City name. - name: postalCode | type: string | description: Postal or zip code. - name: streetAddress | type: StreetAddress | description: Street address object, with number, name, and apartment number in separate fields. - name: addressLine | type: string | description: Main address line (usually street name and number). - name: addressLine2 | type: string | description: Free text providing more detailed address info. Usually contains apt, suite, floor. - name: pickupMethod | type: PickupMethod | description: Pickup method - enum: STORE_PICKUP, PICKUP_POINT - name: deliveryTime | type: string | description: Expected delivery time in free text. For example, `"3-5 business days"`. - name: instructions | type: string | description: Instructions for the carrier. For example, `"Please knock on the door. If unanswered, please call contact number."`. - name: deliveryTimeSlot | type: DeliveryTimeSlot | description: Expected delivery time slot with start and end times. - name: from | type: string | description: Delivery slot starting time. - name: to | type: string | description: Delivery slot ending time. - name: cost | type: ShippingPrice | description: Shipping costs. - name: price | type: Price | description: Shipping price for display purposes. - name: amount | type: string | description: Amount. - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for a shipping. - name: taxAmount | type: Price | description: Calculated tax, based on `taxable_amount` and `tax_rate`. - name: taxableAmount | type: Price | description: Amount for which tax is calculated. - name: taxRate | type: string | description: Tax rate %, as a decimal point. - name: taxGroupId | type: string | description: Tax group GUID. - name: taxIncludedInPrice | type: boolean | description: Indicates whether the price already includes tax. - name: taxBreakdown | type: array | description: Tax information for a line item. - name: jurisdiction | type: string | description: Jurisdiction that taxes were calculated for. For example, "New York", or "Quebec". - name: rate | type: string | description: Tax rate used for this jurisdiction, as a decimal. For example, 10% tax is 0.1000. - name: taxAmount | type: Price | description: Amount of tax calculated for this line item. - name: taxType | type: string | description: The type of tax that was calculated. Depends on the jurisdiction's tax laws. For example, "Sales Tax", "Income Tax", "Value Added Tax", etc. - name: taxName | type: string | description: The name of the tax against which this tax amount was calculated. For example, "NY State Sales Tax", "Quebec GST", etc. This name should be explicit enough to allow the merchant to understand what tax was calculated. - name: jurisdictionType | type: JurisdictionType | description: Type of jurisdiction that taxes were calculated for. - enum: UNDEFINED, COUNTRY, STATE, COUNTY, CITY, SPECIAL - name: nonTaxableAmount | type: Price | description: Non-taxable amount of the line item price. - name: taxableAmount | type: Price | description: Taxable amount of the line item price. - name: region | type: ShippingRegion | description: Shipping region. - name: name | type: string | description: Name of shipping region. For example, `"Metropolitan London"`, or `"Outer Melbourne suburbs"`. - name: buyerNote | type: string | description: [Buyer note](https://support.wix.com/en/article/wix-stores-viewing-buyer-notes) left by the customer. - name: status | type: OrderStatus | description: Order status. - enum: - INITIALIZED: Order created, but not yet approved or canceled. - APPROVED: Order approved. This happens when either an online payment is received **or** when `priceSummary.total` is `0` (a zero-total order). Offline orders (cash payment) are automatically approved. - CANCELED: Order canceled by the merchant or buyer. - PENDING: Order is waiting for the buyer to complete checkout. - REJECTED: Order rejected. This happens when pending payments fail. - name: archived | type: boolean | description: Whether order is archived. - name: taxInfo | type: OrderTaxInfo | description: Tax information. - name: totalTax | type: Price | description: Calculated tax, added from line items. - name: taxBreakdown | type: array | description: The summary of the tax breakdown for all the line items. It will hold for each tax name, the aggregated tax amount paid for it and the tax rate. - name: taxName | type: string | description: The name of the tax against which this tax amount was calculated. - name: taxType | type: string | description: The type of tax that was calculated. Depends on the company's nexus settings as well as the jurisdiction's tax laws. - name: jurisdiction | type: string | description: The name of the jurisdiction in which this tax detail applies. - name: jurisdictionType | type: JurisdictionType | description: The type of the jurisdiction in which this tax detail applies (e.g. Country,State,County,City,Special). - name: rate | type: string | description: The rate at which this tax detail was calculated. - name: aggregatedTaxAmount | type: Price | description: The sum of all the tax from line items that calculated by the tax identifiers. - name: appliedDiscounts | type: array | description: Applied discounts. - ONE-OF: - name: coupon | type: Coupon | description: Coupon applied by the customer. - name: id | type: string | description: Coupon GUID. - name: code | type: string | description: Coupon code. - name: name | type: string | description: Coupon name. - name: amount | type: Price | description: Coupon value. - name: merchantDiscount | type: MerchantDiscount | description: Discount applied manually by the merchant. - ONE-OF: - name: discountReason | type: DiscountReason | description: Predefined discount reason. - enum: - UNSPECIFIED: Unknown discount reason. - EXCHANGED_ITEMS: Balance adjustment resulting from an item exchange. - BILLING_ADJUSTMENT: Proportional discount for a shortened subscription billing cycle. Applied when a subscription's billing date is moved earlier, reducing the cycle length. - name: description | type: string | description: Custom discount description as free text. - name: amount | type: Price | description: Discount amount. - name: discountRule | type: DiscountRule | description: Automatic discount applied by the system based on configured discount rules. - name: id | type: string | description: Discount rule GUID - name: name | type: DiscountRuleName | description: Discount rule name - name: original | type: string | description: Original discount rule name (in site's default language). - name: translated | type: string | description: Translated discount rule name according to buyer language. Defaults to `original` when not provided. - name: amount | type: Price | description: Discount value. - name: discountType | type: DiscountType | description: - enum: - GLOBAL: Discount applies to the entire order. - SPECIFIC_ITEMS: Discount applies to specific items. - SHIPPING: Discount applies to shipping. For example, free shipping. - name: id | type: string | description: Discount GUID. - name: lineItemDiscounts | type: array | description: Line items the discount applies to, including the discount amount for each. - name: id | type: string | description: Line item GUID. - name: totalDiscount | type: Price | description: Total discount amount for this line item. - name: attributionSource | type: AttributionSource | description: Order attribution source. - enum: UNSPECIFIED, FACEBOOK_ADS - name: channelInfo | type: ChannelInfo | description: Information about the sales channel that submitted this order. - name: type | type: ChannelType | description: Sales channel that submitted the order. When creating an order via the API to record an external order, use the channel type that matches the original source. If no matching type exists, use `OTHER_PLATFORM`. - enum: - UNSPECIFIED: Unspecified sales channel. This value is not supported. - WEB: A web client. - POS: [Point of sale solutions](https://support.wix.com/en/wix-mobile-pos-2196395). - EBAY: [eBay shop](https://support.wix.com/en/article/wix-stores-connecting-and-setting-up-an-ebay-shop). - AMAZON: [Amazon shop](https://support.wix.com/en/article/wix-stores-connecting-and-setting-up-an-amazon-shop). - OTHER_PLATFORM: Other sales platform. - WIX_APP_STORE: [Wix Owner app](https://support.wix.com/article/wix-owner-app-an-overview). - WIX_INVOICES: Wix Invoices app in [your dashboard](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Finvoices/settings/general-settings) - BACKOFFICE_MERCHANT: Wix merchant backoffice. - WISH: Wish sales channel. - CLASS_PASS: [ClassPass sales channel](https://support.wix.com/en/article/wix-bookings-letting-clients-book-your-services-with-classpass). - GLOBAL_E: Global-E sales channel. - FACEBOOK: [Facebook shop](https://support.wix.com/en/article/wix-stores-changes-to-facebook-shops). - ETSY: [Etsy sales channel](https://support.wix.com/en/article/wix-stores-request-adding-etsy-as-a-sales-channel). - TIKTOK: [TikTok sales channel](https://support.wix.com/en/article/wix-stores-request-adding-tiktok-as-a-sales-channel). - FAIRE_COM: [Faire marketplace integration](https://support.wix.com/en/article/wix-stores-creating-a-faire-store-using-the-faire-integration-app). - PAYPAL_AGENTIC_CHECKOUT: PayPal Agentic Checkout sales channel. - STRIPE_AGENTIC_CHECKOUT: Stripe Agentic Checkout sales channel. - name: externalOrderId | type: string | description: Reference to an order GUID from an external system. Relevant when recording orders from external platforms. - name: externalOrderUrl | type: string | description: URL to the order in the external system. Relevant when recording orders from external platforms. - name: seenByAHuman | type: boolean | description: Whether a human has seen the order. Set when an order is clicked on in the dashboard. - name: checkoutId | type: string | description: Checkout GUID. - name: customFields | type: array | description: Custom fields. - name: value | type: Value | description: Custom field value. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: title | type: string | description: Custom field title. - name: translatedTitle | type: string | description: Translated custom field title. - name: additionalFees | type: array | description: Additional fees applied to the order. - name: code | type: string | description: Additional fee's unique code for future processing. - name: name | type: string | description: Name of additional fee. - name: price | type: Price | description: Additional fee's price. - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for additional fee. - name: providerAppId | type: string | description: SPI implementer's `appId`. - name: priceBeforeTax | type: Price | description: Additional fee's price before tax. - name: priceAfterTax | type: Price | description: Additional fee's price after tax. - name: id | type: string | description: Additional fee's id. - name: lineItemIds | type: array | description: Optional - Line items associated with this additional fee. If no `lineItemIds` are provided, the fee will be associated with the whole cart/checkout/order. - name: source | type: AdditionalFeeSource | description: Specifies the entity that added the additional fee. - enum: - SERVICE_PLUGIN: The additional fee was added by an additional fee service plugin. - ITEM: The additional fee was added to the item by a catalog or custom line item. - MANUAL: The additional fee was added manually on request. - SHIPPING: The additional fee was added by the shipping provider. - PLATFORM: The additional fee was added by the Wix eCommerce platform. - name: extendedFields | type: ExtendedFields | description: Custom field data for the order object. [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: purchaseFlowId | type: string | description: Persistent GUID that correlates between the various eCommerce elements: cart, checkout, and order. - name: recipientInfo | type: AddressWithContact | description: Final recipient's address and contact details. This field represents who will ultimately receive the order. It may differ from `shippingInfo.logistics.shippingDestination` when: + The chosen shipping option is a pickup point or store pickup, where `shippingDestination` contains the pickup location. + No shipping option is selected. - name: tags | type: Tags | description: Order tags. [Tags](https://dev.wix.com/docs/rest/business-management/tags/introduction.md) are labels attached to entities, allowing for flexible categorization and data management. - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, normally not given to site members or visitors. - name: tagIds | type: array | description: List of tag GUIDs - name: tags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: purchasedDate | type: string | description: Date and time the order was originally purchased in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Used for migration from external systems. - name: businessLocation | type: Location | description: Order location. - name: id | type: string | description: Location GUID. Learn more about the [Wix Locations API](https://dev.wix.com/docs/rest/business-management/locations/introduction.md). - name: platformFeeSummary | type: PlatformFeeSummary | description: Summary of platform fees for this order, including totals by charge type and a breakdown of individual fees. - name: total | type: Price | description: Total sum of all platform fees. - name: totalPassOn | type: Price | description: Total amount of platform fees with `PASS_ON` charge type. - name: totalAbsorbed | type: Price | description: Total amount of platform fees with `ABSORBED` charge type. - name: fees | type: array | description: Specific information about each platform fee. - name: name | type: TranslatableString | description: Platform fee name. - name: original | type: string | description: __Required.__ String in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. - name: translated | type: string | description: String translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: amount | type: Price | description: Platform fee amount. - name: lineItemId | type: string | description: GUID of the line item the platform fee applies to. - name: chargeType | type: ChargeType | description: Platform fee charge type. - enum: - PASS_ON: Platform fee passed on to buyer. This type increases the order total, and is visible to the buyer and merchant as an additional fee. - ABSORBED: Platform fee absorbed by merchant. This type does not increase the order total, and is only visible to the merchant. - name: percentageRate | type: string | description: Percentage rate charged as platform fee. The fee rate percentage expressed as a decimal fraction between 0 and 1. For example, `0.05` for 5%. Return type: GetPaymentSettingsResponse - name: paymentSettings | type: PaymentSettings | description: Retrieved payment settings. - name: requires3dSecure | type: boolean | description: Whether to apply [3D Secure](https://support.wix.com/en/article/about-3d-secure-3ds-payments-with-third-party-payment-providers) during the payment process. > __Note:__ > + Not all payment providers offer this feature in their Wix integration. > + If the service plugin call fails, the value set in the [extension configuration](https://dev.wix.com/docs/rest/api-reference/wix-e-commerce/payment-settings-integration-spi/introduction.md#configuration) for `fallbackValueForRequires3dSecure` will be used. ``` ### Examples ### Get payment settings - decoded JWT The data payload will include the following object as an encoded JWT. For the purposes of this example, we show the request and response objects decoded. ```curl curl -X POST https://provider.example.com/v1/payment-settings \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "order": { "activities": [ { "createdDate": "2023-09-10T09:03:06.546Z", "type": "ORDER_PLACED" } ], "additionalFees": [ ], "archived": false, "balanceSummary": { "balance": { "amount": "20.00", "formattedAmount": "$20.00" }, "paid": { "amount": "0", "formattedAmount": "$0.00" }, "refunded": { "amount": "0", "formattedAmount": "$0.00" } }, "billingInfo": { "address": { "addressLine": "Aahar Indian Cuisine", "city": "Farmington Hills", "country": "US", "countryFullname": "United States", "postalCode": "48335-3123", "subdivision": "US-MI", "subdivisionFullname": "Michigan" }, "contactDetails": { "firstName": "aa", "lastName": "aa", "phone": "012345678" } }, "buyerInfo": { "email": "ba1a18ca30bf6289323070a751094c881d57c8948ca94b8a8d1dfa126d2cb9ab", "visitorId": "cbc62c47-5aed-4949-8195-f7e6d02211ec" }, "buyerLanguage": "en", "channelInfo": { "type": "WEB" }, "checkoutId": "d28158fd-ebcd-4911-b1d5-964aa99ebba9", "createdBy": { "visitorId": "cbc62c47-5aed-4949-8195-f7e6d02211ec" }, "createdDate": "2023-09-10T09:03:06.546Z", "currency": "USD", "id": "3005ef53-df05-4ab8-84c8-b942884a7ee1", "lineItems": [ { "catalogReference": { "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "catalogItemId": "1b2b47bf-c162-dafc-f68a-c37eddcc208f", "options": { "customTextFields": {}, "variantId": "00000000-0000-0000-0000-000000000000" } }, "id": "00000000-0000-0000-0000-000000000001", "image": { "height": 1980, "id": "c837a6_fdb039110b784858933d038f14f78b1c~mv2.jpg", "url": "https://static.wixstatic.com/media/c837a6_fdb039110b784858933d038f14f78b1c~mv2.jpg/v1/fit/w_1796,h_1980,q_90/file.jpg", "width": 1796 }, "itemType": { "preset": "PHYSICAL" }, "physicalProperties": { "shippable": true, "sku": "0007" }, "price": { "amount": "15.00", "formattedAmount": "$15.00" }, "priceBeforeDiscounts": { "amount": "15.00", "formattedAmount": "$15.00" }, "productName": { "original": "I'm a product", "translated": "I'm a product" }, "quantity": 1, "refundQuantity": 0, "taxDetails": { "taxRate": "0", "taxableAmount": { "amount": "15.00", "formattedAmount": "$15.00" }, "totalTax": { "amount": "0.0", "formattedAmount": "$0.00" } }, "totalDiscount": { "amount": "0", "formattedAmount": "$0.00" }, "totalPriceAfterTax": { "amount": "15.00", "formattedAmount": "$15.00" }, "totalPriceBeforeTax": { "amount": "15.00", "formattedAmount": "$15.00" } } ], "payNow": { "discount": { "amount": "0", "formattedAmount": "$0.00" }, "shipping": { "amount": "5.0", "formattedAmount": "$5.00" }, "subtotal": { "amount": "15.00", "formattedAmount": "$15.00" }, "tax": { "amount": "0.0", "formattedAmount": "$0.00" }, "total": { "amount": "20.00", "formattedAmount": "$20.00" }, "totalAdditionalFees": { "amount": "0", "formattedAmount": "$0.00" }, "totalPrice": { "amount": "20.00", "formattedAmount": "$20.00" }, "totalWithGiftCard": { "amount": "20.00", "formattedAmount": "$20.00" }, "totalWithoutGiftCard": { "amount": "20.00", "formattedAmount": "$20.00" } }, "paymentStatus": "NOT_PAID", "priceSummary": { "discount": { "amount": "0", "formattedAmount": "$0.00" }, "shipping": { "amount": "5.0", "formattedAmount": "$5.00" }, "subtotal": { "amount": "15.00", "formattedAmount": "$15.00" }, "tax": { "amount": "0.0", "formattedAmount": "$0.00" }, "total": { "amount": "20.00", "formattedAmount": "$20.00" }, "totalAdditionalFees": { "amount": "0", "formattedAmount": "$0.00" }, "totalPrice": { "amount": "20.00", "formattedAmount": "$20.00" }, "totalWithGiftCard": { "amount": "20.00", "formattedAmount": "$20.00" }, "totalWithoutGiftCard": { "amount": "20.00", "formattedAmount": "$20.00" } }, "seenByAHuman": false, "shippingInfo": { "carrierId": "c8a08776-c095-4dec-8553-8f9698d86adc", "code": "bae3f4de-d759-fccb-6dff-9b49d5d5f13f", "cost": { "discount": { "amount": "0", "formattedAmount": "$0.00" }, "price": { "amount": "5", "formattedAmount": "$5.00" }, "taxDetails": { "taxRate": "0", "totalTax": { "amount": "0.0", "formattedAmount": "$0.00" } }, "totalPriceAfterTax": { "amount": "5.0", "formattedAmount": "$5.00" }, "totalPriceBeforeTax": { "amount": "5", "formattedAmount": "$5.00" } }, "logistics": { "deliveryTime": "", "shippingDestination": { "address": { "addressLine": "Aahar Indian Cuisine", "city": "Farmington Hills", "country": "US", "countryFullname": "United States", "postalCode": "48335-3123", "subdivision": "US-MI", "subdivisionFullname": "Michigan" }, "contactDetails": { "firstName": "aa", "lastName": "aa", "phone": "012345678" } } }, "region": { "name": "Region 3" }, "title": "Standard Shipping" }, "taxSummary": { "totalTax": { "amount": "0.0", "formattedAmount": "$0.00" } }, "updatedDate": "2023-09-10T09:03:06.790Z", "weightUnit": "KG" } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.paymentSettings.PaymentSettingsSPI.getPaymentSettings(request, metadata) Description: This method retrieves payment settings from your app. Wix calls this method during the payment process. For example, when a customer inserts credit card details and places an order. This method retrieves the payment settings to apply, and Wix passes on the settings to the payment provider. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: GetPaymentSettingsRequest - name: order | type: Order | description: Order. - name: buyerInfo | type: BuyerInfo | description: Buyer information. - ONE-OF: - name: visitorId | type: string | description: Visitor GUID. Returned when the buyer isn't a logged-in site member. - name: memberId | type: string | description: Member GUID. Returned when the buyer is a logged-in site member. - name: contactId | type: string | description: Contact GUID. Automatically created if one doesn't exist. For more information, see [Contacts API](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/introduction.md). - name: email | type: string | description: Buyer's email address. - name: paymentStatus | type: PaymentStatus | description: Order payment status. - enum: - UNSPECIFIED: - NOT_PAID: `NOT_PAID` can apply to an order made online, but not yet paid. In such cases `order.status` will be `INITIALIZED`. This status also applies when an offline order needs to be manually marked as paid. In such cases `order.status` will be `APPROVED`. - PAID: All required payments associated with this order are paid. - PARTIALLY_REFUNDED: Order partially refunded, but the refunded amount is less than the order's total price. See `order.balanceSummary` for more details. - FULLY_REFUNDED: Order fully refunded. Refund amount equals total price. See `order.balanceSummary` for more details. - PENDING: All payments pending. This can happen with two-step payments, when a payment requires manual review, or when a payment is in progress and will be concluded shortly. Learn more about [pending orders](https://support.wix.com/en/article/pending-orders). - PARTIALLY_PAID: At least one payment received and approved, but it covers less than the order's total price. See `order.balanceSummary` for more details. - PENDING_MERCHANT: Payment received, but not yet confirmed by the payment provider. In most cases, when a payment provider is holding payment it's because setup hasn't been successfully completed by the merchant/site owner. To solve this, the merchant/site owner should log in to the payment provider's dashboard and make sure their account is set up correctly, or contact their support for further assistance. - CANCELED: One or more payments canceled. - DECLINED: One or more payments declined. - name: buyerLanguage | type: string | description: Language for communication with the buyer. Defaults to the site language. For a site that supports multiple languages, this is the language the buyer selected. - name: weightUnit | type: WeightUnit | description: Weight measurement unit - defaults to site's weight unit. - enum: - UNSPECIFIED_WEIGHT_UNIT: Weight unit can't be classified due to an error. - KG: Kilograms. - LB: Pounds. - name: currency | type: string | description: Currency used for the pricing of this order in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) format. - name: currencyConversionDetails | type: CurrencyConversionDetails | description: Currency conversion details. For use with multi-currency sites. - name: taxIncludedInPrices | type: boolean | description: Whether tax is included in line item prices. - name: billingInfo | type: AddressWithContact | description: Billing address and contact details. - name: address | type: Address | description: Address. - name: streetAddress | type: StreetAddress | description: none - name: name | type: string | description: none - name: number | type: string | description: none - name: city | type: string | description: none - name: subdivision | type: string | description: none - name: country | type: string | description: none - name: postalCode | type: string | description: none - name: addressLine2 | type: string | description: none - name: contactDetails | type: FullAddressContactDetails | description: Contact details. - name: firstName | type: string | description: First name. - name: lastName | type: string | description: Last name. - name: phone | type: string | description: Phone number. - name: company | type: string | description: Company name. - name: vatId | type: VatId | description: Tax information (for Brazil only). If GUID is provided, `vatId.type` must also be set, `UNSPECIFIED` is not allowed. - name: _id | type: string | description: Customer's tax GUID. - name: type | type: VatType | description: Tax type. Supported values: + `CPF`: for individual tax payers + `CNPJ`: for corporations - enum: - UNSPECIFIED: - CPF: CPF - for individual tax payers. - CNPJ: CNPJ - for corporations - name: shippingInfo | type: ShippingInformation | description: Shipping info and selected shipping option details. - name: carrierId | type: string | description: App Def Id of external provider which was a source of shipping info - name: code | type: string | description: Unique code (or GUID) of selected shipping option. For example, `"usps_std_overnight"`. - name: title | type: string | description: Shipping option title. For example, `"USPS Standard Overnight Delivery"`, `"Standard"` or `"First-Class Package International"`. - name: logistics | type: DeliveryLogistics | description: Shipping logistics. - ONE-OF: - name: shippingDestination | type: AddressWithContact | description: Shipping destination address and contact details. For pickup orders, this contains the pickup location address, not the recipient's address. - name: pickupDetails | type: PickupDetails | description: Pickup details for store pickup or pickup point orders. - name: address | type: PickupAddress | description: Pickup address. - name: streetAddress | type: StreetAddress | description: none - name: city | type: string | description: none - name: subdivision | type: string | description: none - name: country | type: string | description: none - name: postalCode | type: string | description: none - name: addressLine2 | type: string | description: none - name: pickupMethod | type: PickupMethod | description: Pickup method - enum: STORE_PICKUP, PICKUP_POINT - name: deliveryTime | type: string | description: Expected delivery time in free text. For example, `"3-5 business days"`. - name: instructions | type: string | description: Instructions for the carrier. For example, `"Please knock on the door. If unanswered, please call contact number."`. - name: deliveryTimeSlot | type: DeliveryTimeSlot | description: Expected delivery time slot with start and end times. - name: from | type: Date | description: Delivery slot starting time. - name: to | type: Date | description: Delivery slot ending time. - name: cost | type: ShippingPrice | description: Shipping costs. - name: price | type: Price | description: Shipping price for display purposes. - name: amount | type: string | description: Amount. - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for a shipping. - name: taxAmount | type: Price | description: Calculated tax, based on `taxable_amount` and `tax_rate`. - name: taxableAmount | type: Price | description: Amount for which tax is calculated. - name: taxRate | type: string | description: Tax rate %, as a decimal point. - name: taxGroupId | type: string | description: Tax group GUID. - name: taxIncludedInPrice | type: boolean | description: Indicates whether the price already includes tax. - name: taxBreakdown | type: array | description: Tax information for a line item. - name: jurisdiction | type: string | description: Jurisdiction that taxes were calculated for. For example, "New York", or "Quebec". - name: rate | type: string | description: Tax rate used for this jurisdiction, as a decimal. For example, 10% tax is 0.1000. - name: taxAmount | type: Price | description: Amount of tax calculated for this line item. - name: taxType | type: string | description: The type of tax that was calculated. Depends on the jurisdiction's tax laws. For example, "Sales Tax", "Income Tax", "Value Added Tax", etc. - name: taxName | type: string | description: The name of the tax against which this tax amount was calculated. For example, "NY State Sales Tax", "Quebec GST", etc. This name should be explicit enough to allow the merchant to understand what tax was calculated. - name: jurisdictionType | type: JurisdictionType | description: Type of jurisdiction that taxes were calculated for. - enum: UNDEFINED, COUNTRY, STATE, COUNTY, CITY, SPECIAL - name: nonTaxableAmount | type: Price | description: Non-taxable amount of the line item price. - name: taxableAmount | type: Price | description: Taxable amount of the line item price. - name: region | type: ShippingRegion | description: Shipping region. - name: name | type: string | description: Name of shipping region. For example, `"Metropolitan London"`, or `"Outer Melbourne suburbs"`. - name: buyerNote | type: string | description: [Buyer note](https://support.wix.com/en/article/wix-stores-viewing-buyer-notes) left by the customer. - name: status | type: OrderStatus | description: Order status. - enum: - INITIALIZED: Order created, but not yet approved or canceled. - APPROVED: Order approved. This happens when either an online payment is received **or** when `priceSummary.total` is `0` (a zero-total order). Offline orders (cash payment) are automatically approved. - CANCELED: Order canceled by the merchant or buyer. - PENDING: Order is waiting for the buyer to complete checkout. - REJECTED: Order rejected. This happens when pending payments fail. - name: archived | type: boolean | description: Whether order is archived. - name: taxInfo | type: OrderTaxInfo | description: Tax information. - name: totalTax | type: Price | description: Calculated tax, added from line items. - name: taxBreakdown | type: array | description: The summary of the tax breakdown for all the line items. It will hold for each tax name, the aggregated tax amount paid for it and the tax rate. - name: taxName | type: string | description: The name of the tax against which this tax amount was calculated. - name: taxType | type: string | description: The type of tax that was calculated. Depends on the company's nexus settings as well as the jurisdiction's tax laws. - name: jurisdiction | type: string | description: The name of the jurisdiction in which this tax detail applies. - name: jurisdictionType | type: JurisdictionType | description: The type of the jurisdiction in which this tax detail applies (e.g. Country,State,County,City,Special). - name: rate | type: string | description: The rate at which this tax detail was calculated. - name: aggregatedTaxAmount | type: Price | description: The sum of all the tax from line items that calculated by the tax identifiers. - name: appliedDiscounts | type: array | description: Applied discounts. - ONE-OF: - name: coupon | type: Coupon | description: Coupon applied by the customer. - name: _id | type: string | description: Coupon GUID. - name: code | type: string | description: Coupon code. - name: name | type: string | description: Coupon name. - name: amount | type: Price | description: Coupon value. - name: merchantDiscount | type: MerchantDiscount | description: Discount applied manually by the merchant. - ONE-OF: - name: discountReason | type: DiscountReason | description: Predefined discount reason. - enum: - UNSPECIFIED: Unknown discount reason. - EXCHANGED_ITEMS: Balance adjustment resulting from an item exchange. - BILLING_ADJUSTMENT: Proportional discount for a shortened subscription billing cycle. Applied when a subscription's billing date is moved earlier, reducing the cycle length. - name: description | type: string | description: Custom discount description as free text. - name: amount | type: Price | description: Discount amount. - name: discountRule | type: DiscountRule | description: Automatic discount applied by the system based on configured discount rules. - name: _id | type: string | description: Discount rule GUID - name: name | type: DiscountRuleName | description: Discount rule name - name: original | type: string | description: Original discount rule name (in site's default language). - name: translated | type: string | description: Translated discount rule name according to buyer language. Defaults to `original` when not provided. - name: amount | type: Price | description: Discount value. - name: discountType | type: DiscountType | description: - enum: - GLOBAL: Discount applies to the entire order. - SPECIFIC_ITEMS: Discount applies to specific items. - SHIPPING: Discount applies to shipping. For example, free shipping. - name: _id | type: string | description: Discount GUID. - name: lineItemDiscounts | type: array | description: Line items the discount applies to, including the discount amount for each. - name: _id | type: string | description: Line item GUID. - name: totalDiscount | type: Price | description: Total discount amount for this line item. - name: attributionSource | type: AttributionSource | description: Order attribution source. - enum: UNSPECIFIED, FACEBOOK_ADS - name: channelInfo | type: ChannelInfo | description: Information about the sales channel that submitted this order. - name: type | type: ChannelType | description: Sales channel that submitted the order. When creating an order via the API to record an external order, use the channel type that matches the original source. If no matching type exists, use `OTHER_PLATFORM`. - enum: - UNSPECIFIED: Unspecified sales channel. This value is not supported. - WEB: A web client. - POS: [Point of sale solutions](https://support.wix.com/en/wix-mobile-pos-2196395). - EBAY: [eBay shop](https://support.wix.com/en/article/wix-stores-connecting-and-setting-up-an-ebay-shop). - AMAZON: [Amazon shop](https://support.wix.com/en/article/wix-stores-connecting-and-setting-up-an-amazon-shop). - OTHER_PLATFORM: Other sales platform. - WIX_APP_STORE: [Wix Owner app](https://support.wix.com/article/wix-owner-app-an-overview). - WIX_INVOICES: Wix Invoices app in [your dashboard](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Finvoices/settings/general-settings) - BACKOFFICE_MERCHANT: Wix merchant backoffice. - WISH: Wish sales channel. - CLASS_PASS: [ClassPass sales channel](https://support.wix.com/en/article/wix-bookings-letting-clients-book-your-services-with-classpass). - GLOBAL_E: Global-E sales channel. - FACEBOOK: [Facebook shop](https://support.wix.com/en/article/wix-stores-changes-to-facebook-shops). - ETSY: [Etsy sales channel](https://support.wix.com/en/article/wix-stores-request-adding-etsy-as-a-sales-channel). - TIKTOK: [TikTok sales channel](https://support.wix.com/en/article/wix-stores-request-adding-tiktok-as-a-sales-channel). - FAIRE_COM: [Faire marketplace integration](https://support.wix.com/en/article/wix-stores-creating-a-faire-store-using-the-faire-integration-app). - PAYPAL_AGENTIC_CHECKOUT: PayPal Agentic Checkout sales channel. - STRIPE_AGENTIC_CHECKOUT: Stripe Agentic Checkout sales channel. - name: externalOrderId | type: string | description: Reference to an order GUID from an external system. Relevant when recording orders from external platforms. - name: externalOrderUrl | type: string | description: URL to the order in the external system. Relevant when recording orders from external platforms. - name: seenByAHuman | type: boolean | description: Whether a human has seen the order. Set when an order is clicked on in the dashboard. - name: checkoutId | type: string | description: Checkout GUID. - name: customFields | type: array | description: Custom fields. - name: value | type: Value | description: Custom field value. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: title | type: string | description: Custom field title. - name: translatedTitle | type: string | description: Translated custom field title. - name: additionalFees | type: array | description: Additional fees applied to the order. - name: code | type: string | description: Additional fee's unique code for future processing. - name: name | type: string | description: Name of additional fee. - name: price | type: Price | description: Additional fee's price. - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for additional fee. - name: providerAppId | type: string | description: SPI implementer's `appId`. - name: priceBeforeTax | type: Price | description: Additional fee's price before tax. - name: priceAfterTax | type: Price | description: Additional fee's price after tax. - name: _id | type: string | description: Additional fee's id. - name: lineItemIds | type: array | description: Optional - Line items associated with this additional fee. If no `lineItemIds` are provided, the fee will be associated with the whole cart/checkout/order. - name: source | type: AdditionalFeeSource | description: Specifies the entity that added the additional fee. - enum: - SERVICE_PLUGIN: The additional fee was added by an additional fee service plugin. - ITEM: The additional fee was added to the item by a catalog or custom line item. - MANUAL: The additional fee was added manually on request. - SHIPPING: The additional fee was added by the shipping provider. - PLATFORM: The additional fee was added by the Wix eCommerce platform. - name: extendedFields | type: ExtendedFields | description: Custom field data for the order object. [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: purchaseFlowId | type: string | description: Persistent GUID that correlates between the various eCommerce elements: cart, checkout, and order. - name: recipientInfo | type: AddressWithContact | description: Final recipient's address and contact details. This field represents who will ultimately receive the order. It may differ from `shippingInfo.logistics.shippingDestination` when: + The chosen shipping option is a pickup point or store pickup, where `shippingDestination` contains the pickup location. + No shipping option is selected. - name: tags | type: Tags | description: Order tags. [Tags](https://dev.wix.com/docs/rest/business-management/tags/introduction.md) are labels attached to entities, allowing for flexible categorization and data management. - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, normally not given to site members or visitors. - name: tagIds | type: array | description: List of tag GUIDs - name: tags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: purchasedDate | type: Date | description: Date and time the order was originally purchased in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. Used for migration from external systems. - name: businessLocation | type: Location | description: Order location. - name: _id | type: string | description: Location GUID. Learn more about the [Wix Locations API](https://dev.wix.com/docs/rest/business-management/locations/introduction.md). - name: platformFeeSummary | type: PlatformFeeSummary | description: Summary of platform fees for this order, including totals by charge type and a breakdown of individual fees. - name: total | type: Price | description: Total sum of all platform fees. - name: totalPassOn | type: Price | description: Total amount of platform fees with `PASS_ON` charge type. - name: totalAbsorbed | type: Price | description: Total amount of platform fees with `ABSORBED` charge type. - name: fees | type: array | description: Specific information about each platform fee. - name: name | type: TranslatableString | description: Platform fee name. - name: original | type: string | description: __Required.__ String in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. - name: translated | type: string | description: String translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: amount | type: Price | description: Platform fee amount. - name: lineItemId | type: string | description: GUID of the line item the platform fee applies to. - name: chargeType | type: ChargeType | description: Platform fee charge type. - enum: - PASS_ON: Platform fee passed on to buyer. This type increases the order total, and is visible to the buyer and merchant as an additional fee. - ABSORBED: Platform fee absorbed by merchant. This type does not increase the order total, and is only visible to the merchant. - name: percentageRate | type: string | description: Percentage rate charged as platform fee. The fee rate percentage expressed as a decimal fraction between 0 and 1. For example, `0.05` for 5%. Return type: PROMISE - name: paymentSettings | type: PaymentSettings | description: Retrieved payment settings. - name: requires3dSecure | type: boolean | description: Whether to apply [3D Secure](https://support.wix.com/en/article/about-3d-secure-3ds-payments-with-third-party-payment-providers) during the payment process. > __Note:__ > + Not all payment providers offer this feature in their Wix integration. > + If the service plugin call fails, the value set in the [extension configuration](https://dev.wix.com/docs/rest/api-reference/wix-e-commerce/payment-settings-integration-spi/introduction.md#configuration) for `fallbackValueForRequires3dSecure` will be used. ``` ### Examples ### Example of a `paymentSettings` return value ```javascript import { paymentSettings } from '@wix/ecom/service-plugins'; paymentSettings.provideHandlers({ getPaymentSettings: async ( payload ) => { const {request, metadata} = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: paymentSettings: { requires3dSecure: false } } } }); ``` ### getPaymentSettings (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { paymentSettings } from '@wix/ecom/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { paymentSettings }, // Include the auth strategy and host as relevant }); async function getPaymentSettings(request,metadata) { const response = await myWixClient.paymentSettings.getPaymentSettings(request,metadata); }; ``` ---