From 05251c84ed92af9e10da14412f2c86abf67c9db1 Mon Sep 17 00:00:00 2001 From: Philipp Sonntag Date: Fri, 15 Nov 2024 13:36:11 +0100 Subject: [PATCH] docs(payments-plugin): Smaller fixes for the PayPal plugin documentation --- .../elasticsearch-plugin/index.md | 2 +- .../payments-plugin/pay-pal-plugin.md | 143 ++++++++++++++++++ .../reference/graphql-api/admin/mutations.md | 24 +++ .../default-search-plugin/index.md | 2 +- .../tax/address-based-tax-zone-strategy.md | 46 ++++++ .../src/paypal/paypal.plugin.ts | 15 +- 6 files changed, 222 insertions(+), 10 deletions(-) create mode 100644 docs/docs/reference/core-plugins/payments-plugin/pay-pal-plugin.md create mode 100644 docs/docs/reference/typescript-api/tax/address-based-tax-zone-strategy.md diff --git a/docs/docs/reference/core-plugins/elasticsearch-plugin/index.md b/docs/docs/reference/core-plugins/elasticsearch-plugin/index.md index b908f2d0a1..a088454ce6 100644 --- a/docs/docs/reference/core-plugins/elasticsearch-plugin/index.md +++ b/docs/docs/reference/core-plugins/elasticsearch-plugin/index.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## ElasticsearchPlugin - + This plugin allows your product search to be powered by [Elasticsearch](https://github.com/elastic/elasticsearch) - a powerful Open Source search engine. This is a drop-in replacement for the DefaultSearchPlugin which exposes many powerful configuration options enabling your storefront diff --git a/docs/docs/reference/core-plugins/payments-plugin/pay-pal-plugin.md b/docs/docs/reference/core-plugins/payments-plugin/pay-pal-plugin.md new file mode 100644 index 0000000000..322103e052 --- /dev/null +++ b/docs/docs/reference/core-plugins/payments-plugin/pay-pal-plugin.md @@ -0,0 +1,143 @@ +--- +title: "PayPalPlugin" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + +## PayPalPlugin + + + +This plugin enables payments via the [PayPal Order API](https://developer.paypal.com/docs/api/orders/v2/#orders_create). + +> **_Note:_** This plugin only supports a [2 step flow](https://docs.vendure.io/guides/core-concepts/payment/#two-step). +> This means that the payment has to manually captured by an admin. + +## Requirements + +1. Create a PayPal business account. +2. Make sure you have the client ID and secret of your PayPal REST API app. +3. Get the merchant ID from your PayPal account. This is the account ID of your PayPal business account. +4. Install the Payments plugin: + + `yarn add @vendure/payments-plugin` + + or + + `npm install @vendure/payments-plugin` + +## Setup + +1. Add the plugin to your VendureConfig `plugins` array: +```ts +import { PayPalPlugin } from '@vendure/payments-plugin/package/paypal'; + +// ... + +plugins: [ + // Set the apiUrl to the PayPal sandbox environment + PayPalPlugin.init({ apiUrl: 'https://sandbox.paypal.com/' }), +] +``` +2. Create a new PaymentMethod in the Admin UI, and select "PayPal payments" as the handler. +3. Set your PayPal client ID, secret and merchant ID in the according fields. + +## Storefront usage + +To successfully make a payment, the following steps are explained in detail: +1. Create a PayPal order +2. Use the PayPal SDK to authorize the payment +3. Add the payment to the order +4. Capture the payment + +### Create PayPal order + +Begin by creating a new PayPal order. This order is the reference for the payment and is used to authorize the payment. +Make sure to store the order ID in your frontend, as it is needed in the next steps. + +This step does not modify any data on your Vendure instance. It only creates a new order in the PayPal system. + +Create the PayPal order using the following mutation: +```GraphQL +mutation CreatePayPalOrder { + createPayPalOrder() { + ... on PayPalOrder { + id + } + } +} +``` + +### Authorize payment +The PayPal order you created must be authorized by your customers. This step is handled by the PayPal SDK for the most part. + +For JavaScript projects, you can check out this integration guide to +integrate the PayPal SDK: [PayPal SDK Integration Guide](https://developer.paypal.com/studio/checkout/standard/integrate). + +### Add payment +After authorizing the payment, you need to add it to the Vendure order. This will add and validate the authorizations +add to the payment in the previous step. If the payment is valid, the order will be updated to the next state. + +```GraphQL +mutation AddPaymentToOrder() { + addPaymentToOrder(input: { + method: "paypal-payment-method", + metadata: { + orderId: "the PayPal order ID" + } + }) { + ... on Order { + id + code + state + payments { + id + state + transactionId + method + } + } + ... on ErrorResult { + message + errorCode + } + ... on PaymentFailedError { + paymentErrorMessage + } + } +} +``` + +### Capture payment +Using the admin ui, the admin can settle this payment. After this step, the payment is successfully captured. + +## Creating refunds +Refunds can be created like any other refund in Vendure. The refund will be processed through the PayPal API. + +```ts title="Signature" +class PayPalPlugin { + static options: PayPalPluginOptions; + init(options: PayPalPluginOptions) => Type; +} +``` + +
+ +### options + + + + +### init + + Type<PayPalPlugin>`} /> + +Initialize the PayPal payment plugin + + +
diff --git a/docs/docs/reference/graphql-api/admin/mutations.md b/docs/docs/reference/graphql-api/admin/mutations.md index 2bd20fa49d..09946c14ae 100644 --- a/docs/docs/reference/graphql-api/admin/mutations.md +++ b/docs/docs/reference/graphql-api/admin/mutations.md @@ -1538,6 +1538,30 @@ import MemberDescription from '@site/src/components/MemberDescription';
transitionPaymentToState(id: ID!, state: String!): TransitionPaymentToStateResult!
+
}
+ + +## unsetDraftOrderBillingAddress +
+
"""
+
Unsets the billing address for a draft Order
+
"""
+
type Mutation {
+
unsetDraftOrderBillingAddress(orderId: ID!): Order!
+ + +
}
+
+ +## unsetDraftOrderShippingAddress +
+
"""
+
Unsets the sthipping address for a draft Order
+
"""
+
type Mutation {
+
unsetDraftOrderShippingAddress(orderId: ID!): Order!
+ +
}
diff --git a/docs/docs/reference/typescript-api/default-search-plugin/index.md b/docs/docs/reference/typescript-api/default-search-plugin/index.md index cd72ce9522..07efdd07b9 100644 --- a/docs/docs/reference/typescript-api/default-search-plugin/index.md +++ b/docs/docs/reference/typescript-api/default-search-plugin/index.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## DefaultSearchPlugin - + The DefaultSearchPlugin provides a full-text Product search based on the full-text searching capabilities of the underlying database. diff --git a/docs/docs/reference/typescript-api/tax/address-based-tax-zone-strategy.md b/docs/docs/reference/typescript-api/tax/address-based-tax-zone-strategy.md new file mode 100644 index 0000000000..6eac410786 --- /dev/null +++ b/docs/docs/reference/typescript-api/tax/address-based-tax-zone-strategy.md @@ -0,0 +1,46 @@ +--- +title: "AddressBasedTaxZoneStrategy" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + +## AddressBasedTaxZoneStrategy + + + +Address based TaxZoneStrategy which tries to find the applicable Zone based on the +country of the billing address, or else the country of the shipping address of the Order. + +Returns the default Channel's default tax zone if no applicable zone is found. + +```ts title="Signature" +class AddressBasedTaxZoneStrategy implements TaxZoneStrategy { + determineTaxZone(ctx: RequestContext, zones: Zone[], channel: Channel, order?: Order) => Zone; +} +``` +* Implements: TaxZoneStrategy + + + +
+ +### determineTaxZone + +RequestContext, zones: Zone[], channel: Channel, order?: Order) => Zone`} /> + + + + +
diff --git a/packages/payments-plugin/src/paypal/paypal.plugin.ts b/packages/payments-plugin/src/paypal/paypal.plugin.ts index 85532590fa..a5d5ff3132 100644 --- a/packages/payments-plugin/src/paypal/paypal.plugin.ts +++ b/packages/payments-plugin/src/paypal/paypal.plugin.ts @@ -54,8 +54,11 @@ import { PayPalPluginOptions } from './types'; * 4. Capture the payment * * ### Create PayPal order - * This step creates the order within the PayPal REST API. It does not modify the current state of your - * Vendure instance. The information about your order is passed to the PayPal API in this step. + * + * Begin by creating a new PayPal order. This order is the reference for the payment and is used to authorize the payment. + * Make sure to store the order ID in your frontend, as it is needed in the next steps. + * + * This step does not modify any data on your Vendure instance. It only creates a new order in the PayPal system. * * Create the PayPal order using the following mutation: * ```GraphQL @@ -68,19 +71,15 @@ import { PayPalPluginOptions } from './types'; * } * ``` * - * The PayPal order ID will be used in the next step to add a payment to your order. - * * ### Authorize payment * The PayPal order you created must be authorized by your customers. This step is handled by the PayPal SDK for the most part. - * You should be able to create the payment using the SDK and the provided client ID and order ID. * * For JavaScript projects, you can check out this integration guide to - * integrate the PayPal SDK: [PayPal SDK Integration Guide](https://developer.paypal.com/studio/checkout/standard/integrate). Using this SDK, the - * payment should be added in the `onApprove` callback. + * integrate the PayPal SDK: [PayPal SDK Integration Guide](https://developer.paypal.com/studio/checkout/standard/integrate). * * ### Add payment * After authorizing the payment, you need to add it to the Vendure order. This will add and validate the authorizations - * add to the payment in the previous step. + * add to the payment in the previous step. If the payment is valid, the order will be updated to the next state. * * ```GraphQL * mutation AddPaymentToOrder() {