Working with Payments in PayPal

Overview

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

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

Operation	Description
`createPayment`	Creates a payment
`executeApprovedPayment`	Executes an approved PayPal payment
`lookupPayment`	Looks up a payment resource
`listPayments`	Lists payments that have been completed

Operation details

This section provides details on each of the operations.

Creating a payment

Depending on the payment method and the funding instrument, you can use the payment resource for direct credit card payments, stored credit card payments, or PayPal account payments.

createPayment

<paypal.createPayment>
	<intent>{$ctx:intent}</intent>
    <payer>{$ctx:payer}</payer>
	<redirectUrls>{$ctx:redirectUrls}</redirectUrls>
    <transactions>{$ctx:transactions}</transactions>
</paypal.createPayment>

Properties

intent: Required - Payment intent; must be set to sale for immediate payment or authorized for a delayed payment to be captured at a later time.
payer : Required - Source of the funds for this payment represented by a PayPal account or a credit card.
redirectURLs: Required - Set of redirect URLs you provide only for PayPal-based payments.
transactions : Required - Transactional details including the amount and item details.

Note: PayPal API does not accept multiple payments, and you will get the message "Only single payment transaction currently supported" for multiple payment calls.

Sample request

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

Sample request for createPayment

a) payment method is credit card
{
    "apiUrl":"https://api.sandbox.paypal.com",
    "accessToken":"uT2s1nXTr1zFP6vwtGu30VE.BpdTPok59UAeM245mUI",
    "intent": "authorize",
    "payer": {
    	"payment_method":"credit_card",
    	"funding_instruments":[
      {
        "credit_card":{
          "number":"4417119669820331",
          "type":"visa",
          "expire_month":11,
          "expire_year":2018,
          "cvv2":"874",
          "first_name":"Betsy",
          "last_name":"Buyer",
          "billing_address":{
            "line1":"111 First Street",
            "city":"Saratoga",
            "state":"CA",
            "postal_code":"95070",
            "country_code":"US"
          }
        }
      }
    ]
  },
  "transactions": [
    {
      "amount":{
        "total":"7.47",
        "currency":"USD",
        "details":{
          "subtotal":"7.41",
          "tax":"0.03",
          "shipping":"0.03"
        }
      },
      "description":"This is the payment transaction description."
    }
  ],
  "redirectUrls": {
  }
}

b) payment method is paypal
{
    "apiUrl":"https://api.sandbox.paypal.com",
    "accessToken":"M9FW5RPolCL7IF4py-NNFZyLWPGwvbiZYHBmLGyYo24",
    "intent": "sale",
    "redirectUrls": {
    	"return_url": "http://localhost",
    	"cancel_url": "http://localhost"
    },
    "payer": {
    	"payment_method":"paypal"
  },
  "transactions": [
    {
      "amount":{
        "total":"7.47",
        "currency":"USD",
        "details":{
          "subtotal":"7.41",
          "tax":"0.03",
          "shipping":"0.03"
        }
      },
      "description":"This is the payment transaction description."
    }
  ]
}

Following is more information on the payer, redirectUrls, and transactions properties.

payer
- payment_method: Required - This defines the payment method. The value for this parameter should be either credit_card or paypal.
- funding_instruments: A list of funding instruments for the current payment.
- payer_info: Information related to the payer.
  - number: Required - The credit card number.
  - type: Required - The credit card type: visa, mastercard, amex, or discover
  - expireMonth: Required - Expiration month with no leading zero. Acceptable values are 1 through 12.
  - expireYear: Required - 4-digit expiration year.
  - cvv2: Required - 3-4 digit card validation code.
  - firstName: Required - The first name of the credit card holder.
  - lastName: Required - The last name of the credit card holder.
  - address: Required - The address of the credit card holder.
  - city: Required - The city of the address.
  - state: Required - The state of the address.
  - postalCode: Required - The postal code of the address.
  - countryCode: Required - The 2-letter country code.
redirectURLs
- return_url: Optional - The payer is redirected to this URL after approving the payment. Required for PayPal account payments.
- cancel_url: Optional - The payer is redirected to this URL after canceling the payment. Required for PayPal account payments.
transactions
- total: Required - This is the total amount of the payment.
- currency: Required - The 3-letter currency code.
- subtotal: Required - This defines the subtotal before tax and shipping.
- tax: Required - This defines the tax amount.
- shipping: Required - This defines the shipping cost.

Executing an approved PayPal payment

Use this operation to execute (complete) a PayPal payment that has been approved by the payer. You can optionally update transaction information when executing the payment by passing in one or more transactions.

executeApprovedPayment

<paypal.executeApprovedPayment>
	<id>{$ctx:id}</id>
    <payerId>{$ctx:payerId}</payerId>
    <transactions>{$ctx:transactions}</transactions>
</paypal.executeApprovedPayment>

Properties

id: Required - The payment ID.
payerId: Required - The payer ID.
transactions: This object provides payment transactions details.

Sample request

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

Sample request for executeApprovedPayment

{"apiUrl":"https://api.sandbox.paypal.com",
  "accessToken":"BeDfvkIeb5-OcvyI3dSvYq22FmcqSKgGU1sT3wa-G4M",
  "id":"PAY-34629814WL663112AKEE3AWQ",
  "payerId":"CR87QHB7JTRSC",
  "transactions":[
    {
      "amount":{
        "total":"7.47",
        "currency":"USD",
        "details":{
          "subtotal":"7.41",
          "tax":"0.03",
          "shipping":"0.03"
        }
      },
      "description":"This is the payment transaction description."
    }
  ]
  }

For more information on the transactions property, see: https://developer.paypal.com/docs/api/#transaction-object

Looking up a payment resource

Use this operation to get details about a payment that has not been completed, such as when a payment is only created and approved, or when a payment has failed.

lookupPayment

<paypal.lookupPayment>
	<paymentId>{$ctx:paymentId}</paymentId>
</paypal.lookupPayment>

Properties

paymentId: Required - ID of the payment to look up.

Sample request

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

Sample request for lookupPayment

{
  "apiUrl":"https://api.sandbox.paypal.com",
  "accessToken":"I063AuQP0bwbR1z6g2EOgI38r.BaCRH1lCa3hMLKHdc",
  "paymentId":"PAY-13J04282552611503KL4PXVY"
}

Listing payments

Use this operation to get a list of payments.

listPayments

<paypal.listPayments>
	<count>{$ctx:count}</count>
    <startId>{$ctx:startId}</startId>
    <startIndex>{$ctx:startIndex}</startIndex>
    <startTime>{$ctx:startTime}</startTime>
    <endTime>{$ctx:endTime}</endTime>
    <sortBy>{$ctx:sortBy}</sortBy>
    <sortOrder>{$ctx:sortOrder}</sortOrder>
</paypal.listPayments>

Properties

count: Required - Number of items to return. Default is 10 with a maximum value of 20.
startId: Required - Resource ID that indicates the starting resource to return. When results are paged, you can use the next_id response value as the startId to continue with the next set of results.
startIndex: Required - Start index of the resources to be returned. Typically used to jump to a specific position in the resource history based on its order. The first resource is 0, so to return the second item in a list of results, you would set startIndex to 1.
startTime: Required - Resource creation time as defined in RFC 3339 Section 5.6 that indicates the start of a range of results. Example value: 2013-03-06T11:00:00Z
endTime: Required - Resource creation time that indicates the end of a range of results.
sortBy: Required - Sort based on create_time or update_time.
sortOrder: Required - Sort based on order of results. Options include asc for ascending order or desc for descending order (default).

Sample request

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

Sample request for listPayments

{
"apiUrl":"https://api.sandbox.paypal.com",
"accessToken":"IBMF82XFgTbq-Kg1D9N1LkDE9y9xucybaS31tOPQ71s",
"count":"5",
"startId":"PAY-5R041967CM1899051KL5S7QY",
"startIndex":"0",
"startTime":"2000-03-06T11:00:00Z",
"endTime":"",
"sortBy":"update_time",
"sortOrder":""
}

Sample configuration

Following is a sample proxy service that illustrates how to connect to PayPal with the init operation and use the createPayment operation. The sample request for this proxy can be found in createPayment 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_createPayment"
       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="intent" expression="json-eval($.intent)"/>
         <property name="payer" expression="json-eval($.payer)"/>
         <property name="transactions" expression="json-eval($.transactions)"/>
         <property name="redirectUrls" expression="json-eval($.redirectUrls)"/>
         <paypal.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <accessToken>{$ctx:accessToken}</accessToken>
         </paypal.init>
         <paypal.createPayment>
            <intent>{$ctx:intent}</intent>
            <payer>{$ctx:payer}</payer>
            <transactions>{$ctx:transactions}</transactions>
            <redirectUrls>{$ctx:redirectUrls}</redirectUrls>
         </paypal.createPayment>
         <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="400">
                     <property name="ERROR_MESSAGE" value="Bad Request"/>
                     <property name="issue" expression="json-eval($.details[0].issue)"/>
                     <property name="fieldName" expression="json-eval($.details[0].field)"/>
                     <filter xpath="get-property('issue') = '' or (not(string(get-property('issue'))))">
                        <then>
                           <property name="error_description" expression="json-eval($.message)"/>
                        </then>
                        <else>
                           <property name="error_description"
                                     expression="fn:concat( get-property('fieldName'), ' - ',get-property('issue'))"/>
                        </else>
                     </filter>
                  </case>
                  <case regex="401">
                     <property name="ERROR_MESSAGE" value="Unauthorized"/>
                  </case>
                  <case regex="404">
                     <property name="ERROR_MESSAGE" value="Not Found"/>
                  </case>
               </switch>
               <sequence key="faultHandlerSeq"/>
            </then>
         </filter>
         <respond/>
      </inSequence>
      <outSequence>
         <send/>
      </outSequence>
   </target>
   <description/>
</proxy>

WSO2 ESB Connectors Documentation

Working with Payments in PayPal

Overview

Operation details

Creating a payment

Sample request

Related PayPal documentation

Executing an approved PayPal payment

Sample request

Related PayPal documentation

Looking up a payment resource

Sample request

Listing payments

Sample request

Sample configuration