paypal开发整理文档（14）——PayPal Orders API整理

Posted 2022-12-02 起名字是很难的事

官方文档地址：https://developer.paypal.com/docs/api/orders/v2/

目录

Orders

1. Create Order - 创建订单

Header parameters

Request body

Response

2. Update order

Header parameters

Path parameters

Request body

Response

3. Show order details

Header parameters

---

在REST API调用中，包括环境API服务的URL：

sandbox： https://api.sandbox.paypal.com
live： https://api.paypal.com

Orders

Use the /orders resource to create, update, retrieve, authorize, and capture orders.

使用/orders资源创建、更新、检索、授权和捕获订单。

---

1. Create Order - 创建订单

post：/v2/checkout/orders

创建一个订单。只支持一个采购单元的订单

 

Header parameters

名称	类型	是否必填	备注
PayPal-Request-Id	string	否
PayPal-Partner-Attribution-Id	string	否
Prefer	string	否
Authorization	string	是	Bearer <Access-Token> or Basic <client_id:secret>
Content-Type	string	是	application/<json>

 

Request body

名称	类型	是否必填	值	备注
intent	enum 枚举	是	CAPTURE 商家在顾客付款后立即获得付款 AUTHORIZE 商户打算授权付款，并在客户付款后暂停资金。授权付款的担保期最长为3天，但最多可获得29天的付款。三天的兑现期过后，原授权付款到期，您必须重新授权付款。您必须提出单独的请求以获取按需付款。当您的订单中有多个“purchase_unit”时，不支持此意图。	立即捕获付款，或者在订单创建后授权订单的付款
payer	object	否		付款人
purchase_units	array	是		购买单元的数组。每个购买单位在付款人和收款人之间建立一份合同。每个采购单元代表付款人打算向收款人购买的全部或部分订单。
application_context	object	否		在使用PayPal付款的审批过程中自定义付款人体验

 

Response

成功的请求将返回HTTP 201创建的状态码和一个JSON响应体，其中默认包含包含ID、status和HATEOAS链接的最小响应。如果需要完整的订单资源表示，则必须传递Prefer: return=representation请求头。这个头值不是默认值。

名称	类型	值	备注
create_time	string	Minimum length: 20. Maximum length: 64. Pattern: ^[0-9]4-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]2:[0-9]2)$	交易发生的日期和时间，采用Internet日期和时间格式。 只读
update_time	string	Minimum length: 20. Maximum length: 64. Pattern: ^[0-9]4-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]2:[0-9]2)$	上次更新事务的日期和时间，采用Internet日期和时间格式。 只读
id	string		order的id 只读
payment_source	object		用于支付款项的支付来源。
intent	enum 枚举	CAPTURE 商家在顾客付款后立即获得付款 AUTHORIZE 商户打算授权付款，并在客户付款后暂停资金。授权付款的担保期最长为3天，但最多可获得29天的付款。三天的兑现期过后，原授权付款到期，您必须重新授权付款。您必须提出单独的请求以获取按需付款。当您的订单中有多个“purchase_unit”时，不支持此意图。	立即捕获付款，或者在订单创建后授权订单的付款
payer	object		付款人
purchase_units	array		购买单元的数组。每个购买单位在付款人和收款人之间建立一份合同。每个采购单元代表付款人打算向收款人购买的全部或部分订单。
status	enum 枚举	CREATED 订单是用指定的上下文创建的 SAVED 订单被保存并持久化。订单状态继续进行，直到对订单中的所有购买单元使用final_capture = true进行捕获。 APPROVED 客户通过PayPal钱包或其他支付方式批准付款。例如，信用卡、银行账户等等。 VOIDED 订单中的所有采购单位都将作废 COMPLETED 已授权付款或已获取订单的授权付款 PAYER_ACTION_REQUIRED 订单要求付款人采取行动(例如3DS身份验证)。将付款人重定向到“rel”:“payer-action”HATEOAS链接，该链接作为响应的一部分返回，在授权或捕获订单之前 Minimum length: 1. Maximum length: 255. Pattern: ^[0-9A-Z_]+$	只读
links	array		一组与请求相关的HATEOAS链接。要完成付款人的批准，使用批准链接重定向付款人。API调用者有3个小时(默认设置，这可以由你的客户经理更改为24/48/72小时，以适应你的用例)，从订单被创建的时候，重定向你的付款人。一旦被重定向，API调用者有72小时的时间让付款人批准订单，授权或捕获订单。如果你没有使用贝宝支付SDK (JS)(例如:https://developer.paypal.com/docs/checkout/integrate/#4-set-up-the-transaction)来启动贝宝付款体验(在上下文中)，确保你包括application_context。如果return_url被指定，那么在付款人批准付款后，你将会收到“We're sorry, Things don't appear to be working at the moment” 只读

---

2. Update order

post：/v2/checkout/orders/id

• 更新具有“CREATED” 或“APPROVED” 状态的订单。
• 无法更新“COMPLETED ”状态的订单
• 更新时，必须提供reference_id
• 如果您省略了一个购买单元的订单的reference_id, PayPal默认为默认的reference_id，这使您可以使用路径

• "path": "/purchase_units/@reference_id=='default'/attribute-or-object"

 

 

可以更新以下内容：

intent — replace.
purchase_units — replace, add.
purchase_units[].custom_id — replace, add, remove.
purchase_units[].description — replace, add, remove.
purchase_units[].payee.email — replace.
purchase_units[].shipping.name — replace, add.
purchase_units[].shipping.address — replace, add.
purchase_units[].soft_descriptor — replace, remove.
purchase_units[].amount — replace.
purchase_units[].invoice_id — replace, add, remove.
purchase_units[].payment_instruction — replace.
purchase_units[].payment_instruction.disbursement_mode — replace
    disbursement_mode默认为INSTANT.
purchase_units[].payment_instruction.platform_fees — replace, add, remove.

Header parameters

名称	类型	是否必填	值
Authorization	string	是	Bearer <Access-Token> 或  Basic <client_id:secret>
Content-Type	string	是	application/json

Path parameters

名称	类型	是否必填
id	string	是	要更新的订单id

Request body

Response

成功的请求将返回HTTP 204 No Content状态代码，并在JSON响应体中返回一个空对象。

---

3. Show order details

GET:/v2/checkout/orders/id

Header parameters

名称	类型	是否必填	值
Authorization	string	是	Bearer <Access-Token> 或  Basic <client_id:secret>
Content-Type	string	是	application/json

Path parameters

名称	类型	是否必填
id	string	是	要展示详情的订单id

Query parameters

Response

成功的请求将返回HTTP 200 OK状态码和一个JSON响应体，该响应体显示订单细节。

名称	类型	值	备注
create_time	string	Minimum length: 20. Maximum length: 64. Pattern: ^[0-9]4-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]2:[0-9]2)$	交易发生的日期和时间，采用Internet日期和时间格式。 只读
update_time	string	Minimum length: 20. Maximum length: 64. Pattern: ^[0-9]4-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]2:[0-9]2)$	上次更新事务的日期和时间，采用Internet日期和时间格式。 只读
id	string		order的id 只读
payment_source	object		用于支付款项的支付来源。
intent	enum 枚举	CAPTURE 商家在顾客付款后立即获得付款 AUTHORIZE 商户打算授权付款，并在客户付款后暂停资金。授权付款的担保期最长为3天，但最多可获得29天的付款。三天的兑现期过后，原授权付款到期，您必须重新授权付款。您必须提出单独的请求以获取按需付款。当您的订单中有多个“purchase_unit”时，不支持此意图。	立即捕获付款，或者在订单创建后授权订单的付款
payer	object		付款人
purchase_units	array		购买单元的数组。每个购买单位在付款人和收款人之间建立一份合同。每个采购单元代表付款人打算向收款人购买的全部或部分订单。
status	enum 枚举	CREATED 订单是用指定的上下文创建的 SAVED 订单被保存并持久化。订单状态继续进行，直到对订单中的所有购买单元使用final_capture = true进行捕获。 APPROVED 客户通过PayPal钱包或其他支付方式批准付款。例如，信用卡、银行账户等等。 VOIDED 订单中的所有采购单位都将作废 COMPLETED 已授权付款或已获取订单的授权付款 PAYER_ACTION_REQUIRED 订单要求付款人采取行动(例如3DS身份验证)。将付款人重定向到“rel”:“payer-action”HATEOAS链接，该链接作为响应的一部分返回，在授权或捕获订单之前 Minimum length: 1. Maximum length: 255. Pattern: ^[0-9A-Z_]+$	只读
links	array		一组与请求相关的HATEOAS链接。要完成付款人的批准，使用批准链接重定向付款人。API调用者有3个小时(默认设置，这可以由你的客户经理更改为24/48/72小时，以适应你的用例)，从订单被创建的时候，重定向你的付款人。一旦被重定向，API调用者有72小时的时间让付款人批准订单，授权或捕获订单。如果你没有使用贝宝支付SDK (JS)(例如:https://developer.paypal.com/docs/checkout/integrate/#4-set-up-the-transaction)来启动贝宝付款体验(在上下文中)，确保你包括application_context。如果return_url被指定，那么在付款人批准付款后，你将会收到“We're sorry, Things don't appear to be working at the moment” 只读

---

Authorize payment for order—授权订单付款

POST:/v2/checkout/orders/id/authorize

授权支付订单。要成功授权订单的付款，买方必须首先批准订单，或者请求中必须提供一个有效的payment_source。在重定向到create order响应中的HATEOAS链接中返回的rel:approve URL时，买方可以批准订单。

Header parameters

名称	类型	是否必填	说明
PayPal-Request-Id	string	否	服务器存储keys45天。有关PayPal-Request-Id的更多信息，请参见PayPal-Request-Id.
Prefer	string	否	成功完成请求时的首选服务器响应 return=minimal 默认。服务器返回最小响应以优化API调用者和服务器之间的通信。最小的响应包括id、状态和HATEOAS链接。 return=representation 服务器返回一个完整的资源表示，包括资源的当前状态。
PayPal-Client-Metadata-Id	string	否	有关PayPal-Client-Metadata-Id的更多信息，请参见 PayPal-Client-Metadata-Id.
Authorization	string	是	值为 Bearer <Access-Token> 或 Basic <client_id:secret>
PayPal-Auth-Assertion	string	否	api调用方提供的用于标识商家的JSON Web令牌声明。有关详细信息，请参见PayPal-Auth-Assertion。
Content-Type	string	是	值为 application/json

Path parameters

Request body

名称	类型	是否必填	备注
payment_source	object	否	订单的付款来源，它可以是一个令牌或一张卡。只有在订单创建后没有重定向用户以批准付款时，才使用此对象。在这种情况下,用户选择付款方法隐式使用paypal流。
application_context	object	否	定制付款人在审批过程中使用PayPal支付的经验。

Response

对非幂等请求的成功响应将返回HTTP 201创建的状态码和一个JSON响应体，该响应体显示已授权的支付细节。如果重试重复响应,返回的HTTP状态码200 OK。默认情况下，响应是最小的。如果您需要完整的资源表示，您必须传递preferred: return=representation请求头。

名称	类型	值	备注
create_time	string	Minimum length: 20. Maximum length: 64. Pattern: ^[0-9]4-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]2:[0-9]2)$	交易发生的日期和时间，采用Internet日期和时间格式。 只读
update_time	string	Minimum length: 20. Maximum length: 64. Pattern: ^[0-9]4-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]2:[0-9]2)$	上次更新事务的日期和时间，采用Internet日期和时间格式。 只读
id	string		order的id 只读
payment_source	object		用于支付款项的支付来源。
intent	enum 枚举	CAPTURE 商家在顾客付款后立即获得付款 AUTHORIZE 商户打算授权付款，并在客户付款后暂停资金。授权付款的担保期最长为3天，但最多可获得29天的付款。三天的兑现期过后，原授权付款到期，您必须重新授权付款。您必须提出单独的请求以获取按需付款。当您的订单中有多个“purchase_unit”时，不支持此意图。	立即捕获付款，或者在订单创建后授权订单的付款
payer	object		付款人
purchase_units	array		购买单元的数组。每个购买单位在付款人和收款人之间建立一份合同。每个采购单元代表付款人打算向收款人购买的全部或部分订单。
status	enum 枚举	CREATED 订单是用指定的上下文创建的 SAVED 订单被保存并持久化。订单状态继续进行，直到对订单中的所有购买单元使用final_capture = true进行捕获。 APPROVED 客户通过PayPal钱包或其他支付方式批准付款。例如，信用卡、银行账户等等。 VOIDED 订单中的所有采购单位都将作废 COMPLETED 已授权付款或已获取订单的授权付款 PAYER_ACTION_REQUIRED 订单要求付款人采取行动(例如3DS身份验证)。将付款人重定向到“rel”:“payer-action”HATEOAS链接，该链接作为响应的一部分返回，在授权或捕获订单之前 Minimum length: 1. Maximum length: 255. Pattern: ^[0-9A-Z_]+$	只读
links	array		一组与请求相关的HATEOAS链接。要完成付款人的批准，使用批准链接重定向付款人。API调用者有3个小时(默认设置，这可以由你的客户经理更改为24/48/72小时，以适应你的用例)，从订单被创建的时候，重定向你的付款人。一旦被重定向，API调用者有72小时的时间让付款人批准订单，授权或捕获订单。如果你没有使用贝宝支付SDK (JS)(例如:https://developer.paypal.com/docs/checkout/integrate/#4-set-up-the-transaction)来启动贝宝付款体验(在上下文中)，确保你包括application_context。如果return_url被指定，那么在付款人批准付款后，你将会收到“We're sorry, Things don't appear to be working at the moment” 只读

---

Capture payment for order

POST:/v2/checkout/orders/id/capture

捕获支付订单。要成功获取订单的付款，买方必须首先批准订单，或者请求中必须提供一个有效的payment_source。在重定向到create order响应中的HATEOAS链接中返回的rel:approve URL时，买方可以批准订单。

Header parameters

名称	类型	是否必填	说明
PayPal-Request-Id	string	否	服务器存储keys45天。有关PayPal-Request-Id的更多信息，请参见PayPal-Request-Id.
Prefer	string	否	成功完成请求时的首选服务器响应 return=minimal 默认。服务器返回最小响应以优化API调用者和服务器之间的通信。最小的响应包括id、状态和HATEOAS链接。 return=representation 服务器返回一个完整的资源表示，包括资源的当前状态。
PayPal-Client-Metadata-Id	string	否	有关PayPal-Client-Metadata-Id的更多信息，请参见 PayPal-Client-Metadata-Id.
Authorization	string	是	值为 Bearer <Access-Token> 或 Basic <client_id:secret>
PayPal-Auth-Assertion	string	否	api调用方提供的用于标识商家的JSON Web令牌声明。有关详细信息，请参见PayPal-Auth-Assertion。
Content-Type	string	是	值为 application/json

Path parameters

Request body

名称	类型	是否必填	备注
payment_source	object	否	订单的付款来源，它可以是一个令牌或一张卡。只有在订单创建后没有重定向用户以批准付款时，才使用此对象。在这种情况下,用户选择付款方法隐式使用paypal流。
application_context	object	否	定制付款人在审批过程中使用PayPal支付的经验。

Response

对非幂等请求的成功响应将返回HTTP 201创建的状态代码和一个JSON响应体，该响应体显示捕获的支付细节。如果重复响应重试，返回HTTP 200 OK状态码。默认情况下，响应是最小的。如果需要完整的资源表示，请传递preferred: return=representation请求头。

名称	类型	值	备注
create_time	string	Minimum length: 20. Maximum length: 64. Pattern: ^[0-9]4-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]2:[0-9]2)$	交易发生的日期和时间，采用Internet日期和时间格式。 只读
update_time	string	Minimum length: 20. Maximum length: 64. Pattern: ^[0-9]4-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]2:[0-9]2)$	上次更新事务的日期和时间，采用Internet日期和时间格式。 只读
id	string		order的id 只读
payment_source	object		用于支付款项的支付来源。
intent	enum 枚举	CAPTURE 商家在顾客付款后立即获得付款 AUTHORIZE 商户打算授权付款，并在客户付款后暂停资金。授权付款的担保期最长为3天，但最多可获得29天的付款。三天的兑现期过后，原授权付款到期，您必须重新授权付款。您必须提出单独的请求以获取按需付款。当您的订单中有多个“purchase_unit”时，不支持此意图。	立即捕获付款，或者在订单创建后授权订单的付款
payer	object		付款人
purchase_units	array		购买单元的数组。每个购买单位在付款人和收款人之间建立一份合同。每个采购单元代表付款人打算向收款人购买的全部或部分订单。
status	enum 枚举	CREATED 订单是用指定的上下文创建的 SAVED 订单被保存并持久化。订单状态继续进行，直到对订单中的所有购买单元使用final_capture = true进行捕获。 APPROVED 客户通过PayPal钱包或其他支付方式批准付款。例如，信用卡、银行账户等等。 VOIDED 订单中的所有采购单位都将作废 COMPLETED 已授权付款或已获取订单的授权付款 PAYER_ACTION_REQUIRED 订单要求付款人采取行动(例如3DS身份验证)。将付款人重定向到“rel”:“payer-action”HATEOAS链接，该链接作为响应的一部分返回，在授权或捕获订单之前 Minimum length: 1. Maximum length: 255. Pattern: ^[0-9A-Z_]+$	只读
links	array		一组与请求相关的HATEOAS链接。要完成付款人的批准，使用批准链接重定向付款人。API调用者有3个小时(默认设置，这可以由你的客户经理更改为24/48/72小时，以适应你的用例)，从订单被创建的时候，重定向你的付款人。一旦被重定向，API调用者有72小时的时间让付款人批准订单，授权或捕获订单。如果你没有使用贝宝支付SDK (JS)(例如:https://developer.paypal.com/docs/checkout/integrate/#4-set-up-the-transaction)来启动贝宝付款体验(在上下文中)，确保你包括application_context。如果return_url被指定，那么在付款人批准付款后，你将会收到“We're sorry, Things don't appear to be working at the moment” 只读

---

Common object definitions - 常见的对象定义