PayPal-PHP-Server-SDK/doc/controllers/payments.md

Payments

Use the /payments resource to authorize, capture, void authorizations, and retrieve captures.

$paymentsController = $client->getPaymentsController();

Class Name

PaymentsController

Methods

• Capture Authorized Payment
• Get Captured Payment
• Reauthorize Payment
• Void Payment
• Refund Captured Payment
• Get Authorized Payment
• Get Refund

Capture Authorized Payment

Captures an authorized payment, by ID.

function captureAuthorizedPayment(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
authorizationId	string	Template, Required	The PayPal-generated ID for the authorized payment to capture.
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 45 days.
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'
paypalAuthAssertion	?string	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.
body	?CaptureRequest	Body, Optional	-

Response Type

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

Example Usage

$collect = [
    'authorizationId' => 'authorization_id8',
    'prefer' => 'return=minimal',
    'body' => CaptureRequestBuilder::init()
        ->finalCapture(false)
        ->build()
];

$apiResponse = $paymentsController->captureAuthorizedPayment($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	The request failed because it is not well-formed or is syntactically incorrect or violates schema.	ErrorException
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	ErrorException
403	The request failed because the caller has insufficient permissions.	ErrorException
404	The request failed because the resource does not exist.	ErrorException
409	The server has detected a conflict while processing this request.	ErrorException
422	The request failed because it is semantically incorrect or failed business validation.	ErrorException
500	The request failed because an internal server error occurred.	ApiException
Default	The error response.	ErrorException

Get Captured Payment

Shows details for a captured payment, by ID.

function getCapturedPayment(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
captureId	string	Template, Required	The PayPal-generated ID for the captured payment for which to show details.
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.

Response Type

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

Example Usage

$collect = [
    'captureId' => 'capture_id2'
];

$apiResponse = $paymentsController->getCapturedPayment($collect);

Errors

HTTP Status Code	Error Description	Exception Class
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	ErrorException
403	The request failed because the caller has insufficient permissions.	ErrorException
404	The request failed because the resource does not exist.	ErrorException
500	The request failed because an internal server error occurred.	ApiException
Default	The error response.	ErrorException

Reauthorize Payment

Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires. If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment. A reauthorized payment itself has a new honor period of three days. You can reauthorize an authorized payment from 4 to 29 days after the 3-day honor period. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD. Supports only the amount request parameter. Note: This request is currently not supported for Partner use cases.

function reauthorizePayment(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
authorizationId	string	Template, Required	The PayPal-generated ID for the authorized payment to reauthorize.
paypalRequestId	?string	Header, Optional	The server stores keys for 45 days.
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'
paypalAuthAssertion	?string	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.
body	?ReauthorizeRequest	Body, Optional	-

Response Type

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

Example Usage

$collect = [
    'authorizationId' => 'authorization_id8',
    'prefer' => 'return=minimal'
];

$apiResponse = $paymentsController->reauthorizePayment($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	The request failed because it is not well-formed or is syntactically incorrect or violates schema.	ErrorException
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	ErrorException
404	The request failed because the resource does not exist.	ErrorException
422	The request failed because it either is semantically incorrect or failed business validation.	ErrorException
500	The request failed because an internal server error occurred.	ApiException
Default	The error response.	ErrorException

Void Payment

Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.

function voidPayment(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
authorizationId	string	Template, Required	The PayPal-generated ID for the authorized payment to void.
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. Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.
paypalRequestId	?string	Header, Optional	The server stores keys for 45 days.
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'

Response Type

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

Example Usage

$collect = [
    'authorizationId' => 'authorization_id8',
    'prefer' => 'return=minimal'
];

$apiResponse = $paymentsController->voidPayment($collect);

Errors

HTTP Status Code	Error Description	Exception Class
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	ErrorException
403	The request failed because the caller has insufficient permissions.	ErrorException
404	The request failed because the resource does not exist.	ErrorException
409	The request failed because a previous call for the given resource is in progress.	ErrorException
422	The request failed because it either is semantically incorrect or failed business validation.	ErrorException
500	The request failed because an internal server error occurred.	ApiException
Default	The error response.	ErrorException

Refund Captured Payment

Refunds a captured payment, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an amount object in the JSON request body.

function refundCapturedPayment(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
captureId	string	Template, Required	The PayPal-generated ID for the captured payment to refund.
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 45 days.
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'
paypalAuthAssertion	?string	Header, Optional	An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.
body	?RefundRequest	Body, Optional	-

Response Type

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

Example Usage

$collect = [
    'captureId' => 'capture_id2',
    'prefer' => 'return=minimal'
];

$apiResponse = $paymentsController->refundCapturedPayment($collect);

Errors

HTTP Status Code	Error Description	Exception Class
400	The request failed because it is not well-formed or is syntactically incorrect or violates schema.	ErrorException
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	ErrorException
403	The request failed because the caller has insufficient permissions.	ErrorException
404	The request failed because the resource does not exist.	ErrorException
409	The request failed because a previous call for the given resource is in progress.	ErrorException
422	The request failed because it either is semantically incorrect or failed business validation.	ErrorException
500	The request failed because an internal server error occurred.	ApiException
Default	The error response.	ErrorException

Get Authorized Payment

Shows details for an authorized payment, by ID.

function getAuthorizedPayment(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
authorizationId	string	Template, Required	The ID of the authorized payment for which to show details.
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. Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.

Response Type

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

Example Usage

$collect = [
    'authorizationId' => 'authorization_id8'
];

$apiResponse = $paymentsController->getAuthorizedPayment($collect);

Errors

HTTP Status Code	Error Description	Exception Class
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	ErrorException
404	The request failed because the resource does not exist.	ErrorException
500	The request failed because an internal server error occurred.	ApiException
Default	The error response.	ErrorException

Get Refund

Shows details for a refund, by ID.

function getRefund(array $options): ApiResponse

Parameters

Parameter	Type	Tags	Description
refundId	string	Template, Required	The PayPal-generated ID for the refund for which to show details.
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. Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.

Response Type

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

Example Usage

$collect = [
    'refundId' => 'refund_id4'
];

$apiResponse = $paymentsController->getRefund($collect);

Errors

HTTP Status Code	Error Description	Exception Class
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	ErrorException
403	The request failed because the caller has insufficient permissions.	ErrorException
404	The request failed because the resource does not exist.	ErrorException
500	The request failed because an internal server error occurred.	ApiException
Default	The error response.	ErrorException