Working with Authorizations in PayPal

Overview

The following operations allow you to work with authorizations. Click an operation name to see details on how to use it.

For a sample proxy service the illustrates how to work with authorization, see Sample configuration.

Operation	Description
`captureAuthorization`	Captures and processes a previously created authorization
`lookupAuthorization`	Looks up details about authorizations
`voidAuthorization`	Voids a previously authorized payment
`reAuthorization`	Reauthorizes a PayPal account payment

Operation details

This section provides details on each of the operations.

Capturing an authorization

Use this operation to capture and process a previously created authorization.

captureAuthorization

<paypal.captureAuthorization>
	<authorizationId>{$ctx:authorizationId}</authorizationId>
    <total>{$ctx:total}</total>
    <currency>{$ctx:currency}</currency>
    <isFinalCapture>{$ctx:finalCapture}</isFinalCapture>
</paypal.captureAuthorization>

Properties

authorizationId: Required - ID of the authorization.
total: Required - Total amount charged from the payer to the payee. In case of a refund, this is the refunded amount to the original payer from the payee. 10 characters max. with support for two decimal places.
currency: Required - 3-letter currency code.
isFinalCapture: Required - Use this field when capturing an amount less than the originally authorized amount. If set to true, all remaining funds held by the authorization will be released in the funding instrument. Default is ‘false’.

Sample request

Following is a sample REST request that can be handled by the captureAuthorization operation.

Sample request for captureAuthorization

{
  "apiUrl":"https://api.sandbox.paypal.com",
  "accessToken":"uBMdhxyLxCi8dJztjRCLvoXIzlJ.Fq81tQ8vBYlvXwI",
  "authorizationId":"3CM0296674875493L",
  "currency":"USD",
  "total":"4.54",
  "isFinalCapture":true
}

Related PayPal documentation

https://developer.paypal.com/webapps/developer/docs/api/#capture-an-authorization

Looking up an authorization

Use this operation to get details about an authorization.

lookupAuthorization

<paypal.lookupAuthorization>
	<authorizationId>{$ctx:authorizationId}</authorizationId>
</paypal.lookupAuthorization>

Properties

authorizationId: Required - Authorization ID.

Sample request

Following is a sample REST request that can be handled by the lookupAuthorization operation.

Sample request for lookupAuthorization

{"apiUrl":"https://api.sandbox.paypal.com",
  "accessToken":"3zeI1AdW9pzNqwdVjrXGLAuUHGg24B.hE3e7WsGiKtg",
  "authorizationId":"1FS87370W3262503R"
}

Related PayPal documentation

https://developer.paypal.com/webapps/developer/docs/api/#authorizations

Voiding an authorization

Use this operation to void a previously authorized payment.

voidAuthorization

<paypal.voidAuthorization>
	<authorizationId>{$ctx:authorizationId}</authorizationId>
</paypal.voidAuthorization>

Properties

authorizationId: Required - Authorization ID.

Sample request

Following is a sample REST request that can be handled by the voidAuthorization operation.

Sample request for voidAuthorization

{
	"apiUrl" : "https://api.sandbox.paypal.com",
	"accessToken" : "FiUebZi3SkXRUVmVXOZr4N0yIshk6fIk4KkXbK40MpY",
	"authorizationId" : "2DC87612EK520411B"
}

Related PayPal documentation

https://developer.paypal.com/webapps/developer/docs/api/#void-an-authorization

Reauthorizing a payment

Use this operation to reauthorize a PayPal account payment. It is recommended that you reauthorize a payment after the initial 3-day honor period to ensure that funds are still available.

reAuthorization

<paypal.reAuthorization>
	<authorizationId>{$ctx:authorizationId}</authorizationId>
    <total>{$ctx:total}</total>
    <currency>{$ctx:currency}</currency>
    <details>{$ctx:details}</details>
</paypal.reAuthorization>

Properties

authorizationId: Required - ID of the authorization you are reauthorizing.
total: Required - Total amount charged from the payer to the payee. In case of a refund, this is the refunded amount to the original payer from the payee. 10 characters max. with support for two decimal places.
currency: Required - 3-letter currency code. PayPal does not support all currencies.
details: Required - Additional details related to a payment amount.

Sample request

Following is a sample REST request that can be handled by the reAuthorization operation.

Sample request for reAuthorization

{
	"apiUrl": "https://api.sandbox.paypal.com",
	"accessToken": "uT2s1nXTr1zFP6vwtGu30VE.BpdTPok59UAeM245mUI",
	"authorizationId": "5TP77355U9771970B",
	"total": "7.00",
	"currency": "USD",
	"details": {
		"subtotal":"7.41",
          "tax":"0.03",
          "shipping":"0.03"
	}
}

Following is more information on the details property:

shipping: Required - Amount charged for shipping. 10 characters max. with support for two decimal places.
subtotal: Required - Subtotal (amount) of items being paid for before tax and shipping. 10 characters max. with support for two decimal places.
tax: Required - Amount charged for tax. 10 characters max. with support for two decimal places.

Related PayPal documentation

https://developer.paypal.com/webapps/developer/docs/api/#reauthorize-a-payment

Sample configuration

Following is a sample proxy service that illustrates how to connect to PayPal with the init operation and use the captureAuthorization operation. The sample request for this proxy can be found in captureAuthorization sample request. You can use this sample as a template for using other operations in this category.

As a best practice, create a separate sequence for handling the response payload for errors. In the following sample, this sequence is "faultHandlerSeq".

Sample Proxy

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="PayPal_captureAuthorization"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
      <inSequence onError="faultHandlerSeq">
         <property name="apiUrl" expression="json-eval($.apiUrl)"/>
         <property name="accessToken" expression="json-eval($.accessToken)"/>
         <property name="authorizationId" expression="json-eval($.authorizationId)"/>
         <property name="total" expression="json-eval($.total)"/>
         <property name="currency" expression="json-eval($.currency)"/>
         <property name="finalCapture" expression="json-eval($.isFinalCapture)"/>
         <paypal.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <accessToken>{$ctx:accessToken}</accessToken>
         </paypal.init>
         <paypal.captureAuthorization>
            <authorizationId>{$ctx:authorizationId}</authorizationId>
            <total>{$ctx:total}</total>
            <currency>{$ctx:currency}</currency>
            <isFinalCapture>{$ctx:finalCapture}</isFinalCapture>
         </paypal.captureAuthorization>
         <filter source="$axis2:HTTP_SC" regex="^[^2][\d][\d]">
            <then>
               <property name="ERROR_CODE" expression="$axis2:HTTP_SC"/>
               <switch source="$axis2:HTTP_SC">
                  <case regex="401">
                     <property name="ERROR_MESSAGE" value="Unauthorized"/>
                  </case>
                  <case regex="404">
                     <property name="ERROR_MESSAGE" value="Not Found"/>
                  </case>
                  <case regex="400">
                     <property name="ERROR_MESSAGE" value="Bad Request"/>
                     <property name="message" expression="json-eval($.message)"/>
                  </case>
               </switch>
               <sequence key="faultHandlerSeq"/>
            </then>
         </filter>
         <respond/>
      </inSequence>
      <outSequence>
        <send/>
      </outSequence>
   </target>
   <description/>
</proxy>