# 收取运费 为您的客户创建不同的运费。 通过运费选项可以显示各种运输选项,如标准、快递和隔夜运输,并提供更准确的运费估计。使用不同的 Stripe 产品向客户收取运费。创建运费前,了解如何[收集账单地址和收货地址](https://docs.stripe.com/payments/collect-addresses.md)。 # 托管页面 > This is a 托管页面 for when payment-ui is stripe-hosted. View the full page at https://docs.stripe.com/payments/during-payment/charge-shipping?payment-ui=stripe-hosted. ## 创建运费 [管理平台] [服务器端] 运费仅支持整个订单的固定金额值。您无法根据订单中的商品数量调整运费。 #### 管理平台 通过管理平台添加[运费](https://dashboard.stripe.com/test/shipping-rates): 1. 点击**创建运费**。 1. 输入一个金额、描述和可选的预计送达时间。 1. 点击**保存**,然后复制运费 ID (`shr_123456`)。 ![](https://b.stripecdn.com/docs-statics-srv/assets/create-shipping-rate-dashboard.ddd79821d5edee523d7da9d22682be59.png) 输入运费详情 ### 更新运费 您无法更新已设定货币的运费金额。一旦为运费设置了货币和金额,只能通过添加新货币的方式进行更新。要在管理平台中修改运费,您必须先归档该运费率,再重新创建新的运费率。 ### 存档运费费率 存档运费费率: 1. 在[运费费率](https://dashboard.stripe.com/test/shipping-rates) 选项卡上,选择适用的运费费率。 1. 单击溢出菜单 ⋯,然后选择**存档**。 若要取消存档运费费率,请单击溢出菜单 ⋯,然后选择**取消存档运费费率**。 #### API > #### 对动态运费更新感兴趣? > > Checkout 支持让您根据客户提供的地址或订单价值动态更新运费。查看有关此预览功能的[动态自定义配送选项](https://docs.stripe.com/payments/checkout/custom-shipping-options.md)。 [创建运费](https://docs.stripe.com/api/shipping_rates.md),这至少需要 `type` 和 `display_name` 参数。以下代码示例使用这两个参数以及 `fixed_amount` 和 `delivery_estimate` 来创建运费: ```curl curl https://api.stripe.com/v1/shipping_rates \ -u "<>:" \ -d "display_name=Ground shipping" \ -d type=fixed_amount \ -d "fixed_amount[amount]=500" \ -d "fixed_amount[currency]=usd" \ -d "delivery_estimate[minimum][unit]=business_day" \ -d "delivery_estimate[minimum][value]=5" \ -d "delivery_estimate[maximum][unit]=business_day" \ -d "delivery_estimate[maximum][value]=7" ``` ### 更新运费 若要[更新运费费率](https://docs.stripe.com/api/shipping_rates/update.md),可调用`Stripe::ShippingRate.update`,并根据需要更新参数。 ## 创建一个 Checkout Session [服务器端] 要创建包含您的运费的 Checkout Session,请将生成的运费 ID 传递到 [shipping_options](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_options) 参数。如果想与 Checkout Session 同时创建运费,请使用带 `shipping_options` 的 `shipping_rate_data` 参数。仅 [payment mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) 下的 Checkout Sessions 支持配送选项。 以下代码示例向 Checkout Session 中添加两个配送选项: - 免运费,预计交货时间为 5-7 个工作日。 - 次日空运,费用为 15.00 美元,预计送达时间为 1 个工作日。 该例中,`shipping_options` 数组中的第一个选项是在结账页面上为客户预选的。但是,客户可以选择其中任何一个选项。 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "shipping_address_collection[allowed_countries][0]=US" \ -d "shipping_address_collection[allowed_countries][1]=CA" \ -d "shipping_options[0][shipping_rate_data][type]=fixed_amount" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][amount]=0" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][currency]=usd" \ -d "shipping_options[0][shipping_rate_data][display_name]=Free shipping" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][unit]=business_day" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][value]=5" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][unit]=business_day" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][value]=7" \ -d "shipping_options[1][shipping_rate_data][type]=fixed_amount" \ -d "shipping_options[1][shipping_rate_data][fixed_amount][amount]=1500" \ -d "shipping_options[1][shipping_rate_data][fixed_amount][currency]=usd" \ -d "shipping_options[1][shipping_rate_data][display_name]=Next day air" \ -d "shipping_options[1][shipping_rate_data][delivery_estimate][minimum][unit]=business_day" \ -d "shipping_options[1][shipping_rate_data][delivery_estimate][minimum][value]=1" \ -d "shipping_options[1][shipping_rate_data][delivery_estimate][maximum][unit]=business_day" \ -d "shipping_options[1][shipping_rate_data][delivery_estimate][maximum][value]=1" \ -d "line_items[0][price_data][currency]=usd" \ -d "line_items[0][price_data][product_data][name]=T-shirt" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success" ``` 如果操作成功,运费选择器将显示在您的结账流程中: ![结账流程中的运费选择器](https://b.stripecdn.com/docs-statics-srv/assets/example-checkout-session.5807984bdc0a25ddb53aab00768dd079.jpg) 结账流程中的运费选择器 ## Optional: 处理已完成的交易 付款成功后,您可以在 [shipping_cost](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-shipping_cost) 的 [amount_total](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-amount_total) 属性中检索运费金额。您也可以用 `shipping_cost` 中的 `shipping_rate` 属性来检索选择的运费。要访问 `shipping_cost` 属性,必须[创建一个事件处理程序](https://docs.stripe.com/checkout/fulfillment.md#create-payment-event-handler)来处理已完成的 Checkout Session。您可以通过[安装 Stripe CLI](https://docs.stripe.com/stripe-cli.md) 并用 `stripe listen --forward-to localhost:4242/webhook` [将事件转发到您的本地服务器](https://docs.stripe.com/webhooks.md#test-webhook)来测试处理程序。在下面的代码示例中,处理程序允许用户访问 `shipping_property`: #### Ruby ```ruby # Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/apikeys Stripe.api_key = "<>" require 'sinatra' # You can find your endpoint's secret in your webhook settings endpoint_secret = 'whsec_...' post '/webhook' do event = nil # Verify webhook signature and extract the event # See https://stripe.com/docs/webhooks#verify-events for more information. begin sig_header = request.env['HTTP_STRIPE_SIGNATURE'] payload = request.body.read event = Stripe::Webhook.construct_event(payload, sig_header, endpoint_secret) rescue JSON::ParserError => e # Invalid payload return status 400 rescue Stripe::SignatureVerificationError => e # Invalid signature return status 400 end if event['type'] == 'checkout.session.completed' checkout_session = event['data']['object'] fulfill_order(checkout_session) end status 200 end def fulfill_order(checkout_session)selected_shipping_rate = Stripe::ShippingRate.retrieve(checkout_session.shipping_cost.shipping_rate) shipping_total = checkout_session.shipping_cost.amount_total # TODO: Remove error and implement... raise NotImplementedError.new(<<~MSG) Given the Checkout Session "#{checkout_session.id}" load your internal order from the database then implement your own fulfillment logic. MSG end ``` ## Optional: 定义配送预估时间 您可以用一系列交付估计组合来配置运费。下表包含一些简单的英文送达时间估计,以及它们对应的 `delivery_estimate.minimum` 和 `delivery_estimate.maximum` 的值。 | 预计送达时间 | 最小 | 最大 | | ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | 1 天 | ```es6 { unit: 'day', value: 1, } ``` | ```es6 { unit: 'day', value: 1, } ``` | | 1 个工作日 | ```es6 { unit: 'business_day', value: 1, } ``` | ```es6 { unit: 'business_day', value: 1, } ``` | | 至少 2 个工作日 | ```es6 { unit: 'business_day', value: 2, } ``` | ```es6 null ``` | | 3 到 7 天 | ```es6 { unit: 'day', value: 3, } ``` | ```es6 { unit: 'day', value: 7, } ``` | | 4 到 8 小时 | ```es6 { unit: 'hour', value: 4, } ``` | ```es6 { unit: 'hour', value: 8, } ``` | | 4 小时到 2 个工作日 | ```es6 { unit: 'hour', value: 4, } ``` | ```es6 { unit: 'business_day', value: 2, } ``` | ## Optional: 对运费收取税费 您可以用 [Stripe Tax](https://docs.stripe.com/tax/checkout.md),通过在运费上设置一个 `tax_code` 和 `tax_behavior` 来计算运费的税额。Stripe Tax 自动确定运费是否应税([因为应税性因国家/地区而异](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior.md#shipping-tax-code)),并在需要时应用正确的税率。 用 `shipping_rate_data` 或通过 [Create a Shipping Rate](https://docs.stripe.com/api/shipping_rates/create.md) 创建运费时,可以向运费中添加一个 `tax_behavior` 和 `tax_code` 参数。 建议将 `tax_code` 设置为 `Shipping` (`txcd_92010001`),确保您始终收取正确的税额。如果不想收税,还可以将运费 `tax_code` 设置为 `Nontaxable` (`txcd_00000000`)。 该例中,我们将 `tax_behavior` 设置为 `exclusive`,这在美国是比较常见的。了解有关[税务行为](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior.md#tax-behavior) 的更多信息。 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d billing_address_collection=required \ -d "shipping_address_collection[allowed_countries][0]=US" \ -d "shipping_address_collection[allowed_countries][1]=CA" \ -d "shipping_options[0][shipping_rate_data][type]=fixed_amount" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][amount]=0" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][currency]=usd" \ -d "shipping_options[0][shipping_rate_data][display_name]=Free shipping" \ -d "shipping_options[0][shipping_rate_data][tax_behavior]=exclusive" \ -d "shipping_options[0][shipping_rate_data][tax_code]=txcd_92010001" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][unit]=business_day" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][value]=5" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][unit]=business_day" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][value]=7" \ -d "line_items[0][price_data][currency]=usd" \ -d "line_items[0][price_data][product_data][name]=T-shirt" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][price_data][tax_behavior]=exclusive" \ -d "line_items[0][quantity]=1" \ -d "automatic_tax[enabled]=true" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success" ``` 在结账流程中,您的客户可以看到已计入总销售税的运费税额: ![结账页面上运费费率的计算税费金额](https://b.stripecdn.com/docs-statics-srv/assets/taxed-shipping.14e1bb580c37e035fcf2f0016680db5a.jpg) 在结账流程中计算的运费税额 # 嵌入式页面 > This is a 嵌入式页面 for when payment-ui is embedded-form. View the full page at https://docs.stripe.com/payments/during-payment/charge-shipping?payment-ui=embedded-form. ## 创建运费 [管理平台] [服务器端] 运费仅支持整个订单的固定金额值。您无法根据订单中的商品数量调整运费。 #### 管理平台 通过管理平台添加[运费](https://dashboard.stripe.com/test/shipping-rates): 1. 点击**创建运费**。 1. 输入一个金额、描述和可选的预计送达时间。 1. 点击**保存**,然后复制运费 ID (`shr_123456`)。 ![](https://b.stripecdn.com/docs-statics-srv/assets/create-shipping-rate-dashboard.ddd79821d5edee523d7da9d22682be59.png) 输入运费详情 ### 更新运费 您无法更新已设定货币的运费金额。一旦为运费设置了货币和金额,只能通过添加新货币的方式进行更新。要在管理平台中修改运费,您必须先归档该运费率,再重新创建新的运费率。 ### 存档运费费率 存档运费费率: 1. 在[运费费率](https://dashboard.stripe.com/test/shipping-rates) 选项卡上,选择适用的运费费率。 1. 单击溢出菜单 ⋯,然后选择**存档**。 若要取消存档运费费率,请单击溢出菜单 ⋯,然后选择**取消存档运费费率**。 #### API > #### 对动态运费更新感兴趣? > > Checkout 支持让您根据客户提供的地址或订单价值动态更新运费。查看有关此预览功能的[动态自定义配送选项](https://docs.stripe.com/payments/checkout/custom-shipping-options.md)。 [创建运费](https://docs.stripe.com/api/shipping_rates.md),这至少需要 `type` 和 `display_name` 参数。以下代码示例使用这两个参数以及 `fixed_amount` 和 `delivery_estimate` 来创建运费: ```curl curl https://api.stripe.com/v1/shipping_rates \ -u "<>:" \ -d "display_name=Ground shipping" \ -d type=fixed_amount \ -d "fixed_amount[amount]=500" \ -d "fixed_amount[currency]=usd" \ -d "delivery_estimate[minimum][unit]=business_day" \ -d "delivery_estimate[minimum][value]=5" \ -d "delivery_estimate[maximum][unit]=business_day" \ -d "delivery_estimate[maximum][value]=7" ``` ### 更新运费 若要[更新运费费率](https://docs.stripe.com/api/shipping_rates/update.md),可调用`Stripe::ShippingRate.update`,并根据需要更新参数。 ## 创建一个 Checkout Session [服务器端] 要创建包含您的运费的 Checkout Session,请将生成的运费 ID 传递到 [shipping_options](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_options) 参数。如果想与 Checkout Session 同时创建运费,请使用带 `shipping_options` 的 `shipping_rate_data` 参数。仅 [payment mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) 下的 Checkout Sessions 支持配送选项。 以下代码示例向 Checkout Session 中添加两个配送选项: - 免运费,预计交货时间为 5-7 个工作日。 - 次日空运,费用为 15.00 美元,预计送达时间为 1 个工作日。 该例中,`shipping_options` 数组中的第一个选项是在结账页面上为客户预选的。但是,客户可以选择其中任何一个选项。 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d billing_address_collection=required \ -d "shipping_address_collection[allowed_countries][0]=US" \ -d "shipping_address_collection[allowed_countries][1]=CA" \ -d "shipping_options[0][shipping_rate_data][type]=fixed_amount" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][amount]=0" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][currency]=usd" \ -d "shipping_options[0][shipping_rate_data][display_name]=Free shipping" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][unit]=business_day" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][value]=5" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][unit]=business_day" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][value]=7" \ -d "shipping_options[1][shipping_rate_data][type]=fixed_amount" \ -d "shipping_options[1][shipping_rate_data][fixed_amount][amount]=1500" \ -d "shipping_options[1][shipping_rate_data][fixed_amount][currency]=usd" \ -d "shipping_options[1][shipping_rate_data][display_name]=Next day air" \ -d "shipping_options[1][shipping_rate_data][delivery_estimate][minimum][unit]=business_day" \ -d "shipping_options[1][shipping_rate_data][delivery_estimate][minimum][value]=1" \ -d "shipping_options[1][shipping_rate_data][delivery_estimate][maximum][unit]=business_day" \ -d "shipping_options[1][shipping_rate_data][delivery_estimate][maximum][value]=1" \ -d "line_items[0][price_data][currency]=usd" \ -d "line_items[0][price_data][product_data][name]=T-shirt" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d ui_mode=embedded_page \ --data-urlencode "return_url=https://example.com/return" ``` 如果操作成功,运费选择器将显示在您的结账流程中: ![结账流程中的运费选择器](https://b.stripecdn.com/docs-statics-srv/assets/example-checkout-session.5807984bdc0a25ddb53aab00768dd079.jpg) 结账流程中的运费选择器 ## Optional: 处理已完成的交易 付款成功后,您可以在 [shipping_cost](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-shipping_cost) 的 [amount_total](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-amount_total) 属性中检索运费金额。您也可以用 `shipping_cost` 中的 `shipping_rate` 属性来检索选择的运费。要访问 `shipping_cost` 属性,必须[创建一个事件处理程序](https://docs.stripe.com/checkout/fulfillment.md#create-payment-event-handler)来处理已完成的 Checkout Session。您可以通过[安装 Stripe CLI](https://docs.stripe.com/stripe-cli.md) 并用 `stripe listen --forward-to localhost:4242/webhook` [将事件转发到您的本地服务器](https://docs.stripe.com/webhooks.md#test-webhook)来测试处理程序。在下面的代码示例中,处理程序允许用户访问 `shipping_property`: #### Ruby ```ruby # Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/apikeys Stripe.api_key = "<>" require 'sinatra' # You can find your endpoint's secret in your webhook settings endpoint_secret = 'whsec_...' post '/webhook' do event = nil # Verify webhook signature and extract the event # See https://stripe.com/docs/webhooks#verify-events for more information. begin sig_header = request.env['HTTP_STRIPE_SIGNATURE'] payload = request.body.read event = Stripe::Webhook.construct_event(payload, sig_header, endpoint_secret) rescue JSON::ParserError => e # Invalid payload return status 400 rescue Stripe::SignatureVerificationError => e # Invalid signature return status 400 end if event['type'] == 'checkout.session.completed' checkout_session = event['data']['object'] fulfill_order(checkout_session) end status 200 end def fulfill_order(checkout_session)selected_shipping_rate = Stripe::ShippingRate.retrieve(checkout_session.shipping_cost.shipping_rate) shipping_total = checkout_session.shipping_cost.amount_total # TODO: Remove error and implement... raise NotImplementedError.new(<<~MSG) Given the Checkout Session "#{checkout_session.id}" load your internal order from the database then implement your own fulfillment logic. MSG end ``` ## Optional: 定义配送预估时间 您可以用一系列交付估计组合来配置运费。下表包含一些简单的英文送达时间估计,以及它们对应的 `delivery_estimate.minimum` 和 `delivery_estimate.maximum` 的值。 | 预计送达时间 | 最小 | 最大 | | ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | 1 天 | ```es6 { unit: 'day', value: 1, } ``` | ```es6 { unit: 'day', value: 1, } ``` | | 1 个工作日 | ```es6 { unit: 'business_day', value: 1, } ``` | ```es6 { unit: 'business_day', value: 1, } ``` | | 至少 2 个工作日 | ```es6 { unit: 'business_day', value: 2, } ``` | ```es6 null ``` | | 3 到 7 天 | ```es6 { unit: 'day', value: 3, } ``` | ```es6 { unit: 'day', value: 7, } ``` | | 4 到 8 小时 | ```es6 { unit: 'hour', value: 4, } ``` | ```es6 { unit: 'hour', value: 8, } ``` | | 4 小时到 2 个工作日 | ```es6 { unit: 'hour', value: 4, } ``` | ```es6 { unit: 'business_day', value: 2, } ``` | ## Optional: 对运费收取税费 您可以用 [Stripe Tax](https://docs.stripe.com/tax/checkout.md),通过在运费上设置一个 `tax_code` 和 `tax_behavior` 来计算运费的税额。Stripe Tax 自动确定运费是否应税([因为应税性因国家/地区而异](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior.md#shipping-tax-code)),并在需要时应用正确的税率。 用 `shipping_rate_data` 或通过 [Create a Shipping Rate](https://docs.stripe.com/api/shipping_rates/create.md) 创建运费时,可以向运费中添加一个 `tax_behavior` 和 `tax_code` 参数。 建议将 `tax_code` 设置为 `Shipping` (`txcd_92010001`),确保您始终收取正确的税额。如果不想收税,还可以将运费 `tax_code` 设置为 `Nontaxable` (`txcd_00000000`)。 该例中,我们将 `tax_behavior` 设置为 `exclusive`,这在美国是比较常见的。了解有关[税务行为](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior.md#tax-behavior) 的更多信息。 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d billing_address_collection=required \ -d "shipping_address_collection[allowed_countries][0]=US" \ -d "shipping_address_collection[allowed_countries][1]=CA" \ -d "shipping_options[0][shipping_rate_data][type]=fixed_amount" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][amount]=0" \ -d "shipping_options[0][shipping_rate_data][fixed_amount][currency]=usd" \ -d "shipping_options[0][shipping_rate_data][display_name]=Free shipping" \ -d "shipping_options[0][shipping_rate_data][tax_behavior]=exclusive" \ -d "shipping_options[0][shipping_rate_data][tax_code]=txcd_92010001" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][unit]=business_day" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][value]=5" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][unit]=business_day" \ -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][value]=7" \ -d "line_items[0][price_data][currency]=usd" \ -d "line_items[0][price_data][product_data][name]=T-shirt" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][price_data][tax_behavior]=exclusive" \ -d "line_items[0][quantity]=1" \ -d "automatic_tax[enabled]=true" \ -d mode=payment \ -d ui_mode=embedded_page \ --data-urlencode "return_url=https://example.com/return" ``` 在结账流程中,您的客户可以看到已计入总销售税的运费税额: ![结账页面上运费费率的计算税费金额](https://b.stripecdn.com/docs-statics-srv/assets/taxed-shipping.14e1bb580c37e035fcf2f0016680db5a.jpg) 在结账流程中计算的运费税额