Template

forked from LiveCarta/PayPal-PHP-Server-SDK

Files

Patrick Powers 1fc2cf1e07 2.0.0 Release (#58 )

* Automated commit message

* Automated commit message

* add changelog

---------

Co-authored-by: PayPalServerSDKs <server-sdks@paypal.com>

2025-11-13 16:32:53 -06:00

26 KiB

Raw Blame History

Orders

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

$ordersController = $client->getOrdersController();

Class Name

OrdersController

Methods

Create Order

Creates an order. Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout. Note: For error handling and troubleshooting, see Orders v2 errors.

function createOrder(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
`body`	`OrderRequest`	Body, Required	-
`paypalMockResponse`	`?string`	Header, Optional	PayPal's REST API uses a request header to invoke negative testing in the sandbox. This header configures the sandbox into a negative testing state for transactions that include the merchant.
`paypalRequestId`	`?string`	Header, Optional	The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. It is mandatory for all single-step create order calls (E.g. Create Order Request with payment source information like Card, PayPal.vault_id, PayPal.billing_agreement_id, etc). Constraints: Minimum Length: `1`, Maximum Length: `108`
`paypalPartnerAttributionId`	`?string`	Header, Optional	Constraints: Minimum Length: `1`, Maximum Length: `36`
`paypalClientMetadataId`	`?string`	Header, Optional	Constraints: Minimum Length: `1`, Maximum Length: `36`
`prefer`	`?string`	Header, Optional	The preferred server response upon successful completion of the request. Value is: return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links. return=representation. The server returns a complete resource representation, including the current state of the resource. Default: `'return=minimal'` Constraints: Minimum Length: `1`, Maximum Length: `25`, Pattern: `^[a-zA-Z=,-]*$`
`paypalAuthAssertion`	`?string`	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.

Response Type

This method returns an ApiResponse instance. The getResult() method on this instance returns the response data which is of type Order.

Example Usage

$collect = [
    'body' => OrderRequestBuilder::init(
        CheckoutPaymentIntent::CAPTURE,
        [
            PurchaseUnitRequestBuilder::init(
                AmountWithBreakdownBuilder::init(
                    'currency_code6',
                    'value0'
                )->build()
            )->build()
        ]
    )->build(),
    'prefer' => 'return=minimal'
];

$apiResponse = $ordersController->createOrder($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
Default	The error response.	`ErrorException`

Get Order

Shows details for an order, by ID. Note: For error handling and troubleshooting, see Orders v2 errors.

function getOrder(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
`id`	`string`	Template, Required	The ID of the order for which to show details. Constraints: Minimum Length: `1`, Maximum Length: `36`, Pattern: `^[A-Z0-9]+$`
`paypalMockResponse`	`?string`	Header, Optional	PayPal's REST API uses a request header to invoke negative testing in the sandbox. This header configures the sandbox into a negative testing state for transactions that include the merchant.
`paypalAuthAssertion`	`?string`	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
`fields`	`?string`	Query, Optional	A comma-separated list of fields that should be returned for the order. Valid filter field is `payment_source`. Constraints: Pattern: `^[a-z_]*$`

Response Type

This method returns an ApiResponse instance. The getResult() method on this instance returns the response data which is of type Order.

Example Usage

$collect = [
    'id' => 'id0'
];

$apiResponse = $ordersController->getOrder($collect);

Errors

HTTP Status Code	Error Description	Exception Class
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
Default	The error response.	`ErrorException`

Patch Order

Updates an order with a CREATED or APPROVED status. You cannot update an order with the COMPLETED status.

To make an update, you must provide a reference_id. If you omit this value with an order that contains only one purchase unit, PayPal sets the value to default which enables you to use the path: "/purchase_units/@reference_id=='default'/{attribute-or-object}". Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout.

Note: For error handling and troubleshooting, see Orders v2 errors.

Patchable attributes or objects:

Attribute	Op	Notes
`intent`	replace
`payer`	replace, add	Using replace op for `payer` will replace the whole `payer` object with the value sent in request.
`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.email_address`	replace, add
`purchase_units[].shipping.phone_number`	replace, add
`purchase_units[].shipping.options`	replace, add
`purchase_units[].shipping.address`	replace, add
`purchase_units[].shipping.type`	replace, add
`purchase_units[].soft_descriptor`	replace, remove
`purchase_units[].amount`	replace
`purchase_units[].items`	replace, add, remove
`purchase_units[].invoice_id`	replace, add, remove
`purchase_units[].payment_instruction`	replace
`purchase_units[].payment_instruction.disbursement_mode`	replace	By default, `disbursement_mode` is `INSTANT`.
`purchase_units[].payment_instruction.payee_receivable_fx_rate_id`	replace, add, remove
`purchase_units[].payment_instruction.platform_fees`	replace, add, remove
`purchase_units[].supplementary_data.airline`	replace, add, remove
`purchase_units[].supplementary_data.card`	replace, add, remove
`application_context.client_configuration`	replace, add

function patchOrder(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
`id`	`string`	Template, Required	The ID of the order to update. Constraints: Minimum Length: `1`, Maximum Length: `36`, Pattern: `^[A-Z0-9]+$`
`paypalMockResponse`	`?string`	Header, Optional	PayPal's REST API uses a request header to invoke negative testing in the sandbox. This header configures the sandbox into a negative testing state for transactions that include the merchant.
`paypalAuthAssertion`	`?string`	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
`body`	`?(Patch[])`	Body, Optional	Constraints: Minimum Items: `0`, Maximum Items: `32767`

Response Type

This method returns an ApiResponse instance.

Example Usage

$collect = [
    'id' => 'id0',
    'body' => [
        PatchBuilder::init(
            PatchOp::ADD
        )->build()
    ]
];

$apiResponse = $ordersController->patchOrder($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
Default	The error response.	`ErrorException`

Confirm Order

Payer confirms their intent to pay for the the Order with the given payment source.

function confirmOrder(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
`id`	`string`	Template, Required	The ID of the order for which the payer confirms their intent to pay. Constraints: Minimum Length: `1`, Maximum Length: `36`, Pattern: `^[A-Z0-9]+$`
`paypalClientMetadataId`	`?string`	Header, Optional	Constraints: Minimum Length: `1`, Maximum Length: `36`
`paypalAuthAssertion`	`?string`	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
`prefer`	`?string`	Header, Optional	The preferred server response upon successful completion of the request. Value is: return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links. return=representation. The server returns a complete resource representation, including the current state of the resource. Default: `'return=minimal'` Constraints: Minimum Length: `1`, Maximum Length: `25`, Pattern: `^[a-zA-Z=]*$`
`body`	`?ConfirmOrderRequest`	Body, Optional	-

Response Type

This method returns an ApiResponse instance. The getResult() method on this instance returns the response data which is of type Order.

Example Usage

$collect = [
    'id' => 'id0',
    'prefer' => 'return=minimal'
];

$apiResponse = $ordersController->confirmOrder($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
403	Authorization failed due to insufficient permissions.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

Authorize Order

Authorizes payment for an order. To successfully authorize payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response. Note: For error handling and troubleshooting, see Orders v2 errors.

function authorizeOrder(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
`id`	`string`	Template, Required	The ID of the order for which to authorize. Constraints: Minimum Length: `1`, Maximum Length: `36`, Pattern: `^[A-Z0-9]+$`
`paypalMockResponse`	`?string`	Header, Optional	PayPal's REST API uses a request header to invoke negative testing in the sandbox. This header configures the sandbox into a negative testing state for transactions that include the merchant.
`paypalRequestId`	`?string`	Header, Optional	The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. It is mandatory for all single-step create order calls (E.g. Create Order Request with payment source information like Card, PayPal.vault_id, PayPal.billing_agreement_id, etc). Constraints: Minimum Length: `1`, Maximum Length: `108`
`prefer`	`?string`	Header, Optional	The preferred server response upon successful completion of the request. Value is: return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links. return=representation. The server returns a complete resource representation, including the current state of the resource. Default: `'return=minimal'` Constraints: Minimum Length: `1`, Maximum Length: `25`, Pattern: `^[a-zA-Z=,-]*$`
`paypalClientMetadataId`	`?string`	Header, Optional	Constraints: Minimum Length: `1`, Maximum Length: `36`
`paypalAuthAssertion`	`?string`	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
`body`	`?OrderAuthorizeRequest`	Body, Optional	-

Response Type

This method returns an ApiResponse instance. The getResult() method on this instance returns the response data which is of type OrderAuthorizeResponse.

Example Usage

$collect = [
    'id' => 'id0',
    'prefer' => 'return=minimal'
];

$apiResponse = $ordersController->authorizeOrder($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
403	The authorized payment failed due to insufficient permissions.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

Capture Order

Captures payment for an order. To successfully capture payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response. Note: For error handling and troubleshooting, see Orders v2 errors.

function captureOrder(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
`id`	`string`	Template, Required	The ID of the order for which to capture a payment. Constraints: Minimum Length: `1`, Maximum Length: `36`, Pattern: `^[A-Z0-9]+$`
`paypalMockResponse`	`?string`	Header, Optional	PayPal's REST API uses a request header to invoke negative testing in the sandbox. This header configures the sandbox into a negative testing state for transactions that include the merchant.
`paypalRequestId`	`?string`	Header, Optional	The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. It is mandatory for all single-step create order calls (E.g. Create Order Request with payment source information like Card, PayPal.vault_id, PayPal.billing_agreement_id, etc). Constraints: Minimum Length: `1`, Maximum Length: `108`
`prefer`	`?string`	Header, Optional	The preferred server response upon successful completion of the request. Value is: return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links. return=representation. The server returns a complete resource representation, including the current state of the resource. Default: `'return=minimal'` Constraints: Minimum Length: `1`, Maximum Length: `25`, Pattern: `^[a-zA-Z=,-]*$`
`paypalClientMetadataId`	`?string`	Header, Optional	Constraints: Minimum Length: `1`, Maximum Length: `36`
`paypalAuthAssertion`	`?string`	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
`body`	`?OrderCaptureRequest`	Body, Optional	-

Response Type

This method returns an ApiResponse instance. The getResult() method on this instance returns the response data which is of type Order.

Example Usage

$collect = [
    'id' => 'id0',
    'prefer' => 'return=minimal'
];

$apiResponse = $ordersController->captureOrder($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
403	The authorized payment failed due to insufficient permissions.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

Create Order Tracking

Adds tracking information for an Order.

function createOrderTracking(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
`id`	`string`	Template, Required	The ID of the order that the tracking information is associated with. Constraints: Minimum Length: `1`, Maximum Length: `36`, Pattern: `^[A-Z0-9]+$`
`body`	`OrderTrackerRequest`	Body, Required	-
`paypalAuthAssertion`	`?string`	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.

Response Type

This method returns an ApiResponse instance. The getResult() method on this instance returns the response data which is of type Order.

Example Usage

$collect = [
    'id' => 'id0',
    'body' => OrderTrackerRequestBuilder::init(
        'capture_id8'
    )
        ->notifyPayer(false)
        ->build()
];

$apiResponse = $ordersController->createOrderTracking($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
403	Authorization failed due to insufficient permissions.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

Update Order Tracking

Updates or cancels the tracking information for a PayPal order, by ID. Updatable attributes or objects: Attribute Op Notes items replace Using replace op for items will replace the entire items object with the value sent in request. notify_payer replace, add status replace Only patching status to CANCELLED is currently supported.

function updateOrderTracking(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
`id`	`string`	Template, Required	The ID of the order that the tracking information is associated with. Constraints: Minimum Length: `1`, Maximum Length: `36`, Pattern: `^[A-Z0-9]+$`
`trackerId`	`string`	Template, Required	The order tracking ID. Constraints: Minimum Length: `1`, Maximum Length: `36`, Pattern: `^[A-Z0-9]+$`
`paypalAuthAssertion`	`?string`	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
`body`	`?(Patch[])`	Body, Optional	Constraints: Minimum Items: `0`, Maximum Items: `32767`

Response Type

This method returns an ApiResponse instance.

Example Usage

$collect = [
    'id' => 'id0',
    'trackerId' => 'tracker_id2',
    'body' => [
        PatchBuilder::init(
            PatchOp::ADD
        )->build()
    ]
];

$apiResponse = $ordersController->updateOrderTracking($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
403	Authorization failed due to insufficient permissions.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

26 KiB Raw Blame History

Orders

Class Name

Methods

Create Order

Parameters

Response Type

Example Usage

Errors

Get Order

Parameters

Response Type

Example Usage

Errors

Patch Order

Parameters

Response Type

Example Usage

Errors

Confirm Order

Parameters

Response Type

Example Usage

Errors

Authorize Order

Parameters

Response Type

Example Usage

Errors

Capture Order

Parameters

Response Type

Example Usage

Errors

Create Order Tracking

Parameters

Response Type

Example Usage

Errors

Update Order Tracking

Parameters

Response Type

Example Usage

Errors

26 KiB

Raw Blame History