PayPal payments

Use the Payments REST API to easily and securely accept online and mobile PayPal payments. You can enable customers to make PayPal payments with only a few clicks, depending on the country. A completed payment is known as a sale.

Integration steps

To accept a PayPal payment:

1. Required Prerequisites.
2. Required Create PayPal payment.
3. Required Get payment approval.
4. Required Execute payment.

Prerequisites

  1. Get an access token.

    To get an access token, you must create a PayPal app. When you create an app, PayPal generates a set of OAuth client_id and secret keys for your app for both the sandbox and live environments. Then, to get an access token, you pass the client_id:secret credentials in the Authorization header in a get access token request. The authorization server issues an access token in exchange for your client ID and secret credentials. You use the access token for authentication when you make REST API requests.

    For more information, see make your first call. If you are a non-US developer, see International Developer Questions. You can use your sandbox access token to try any of the code in the REST API reference.

    Each API response includes HATEOAS links that enable you to construct a payment flow.

  2. To receive payments in a currency that you do not hold, first configure your Payment Receiving Preferences in your PayPal account. Otherwise, your payment status might be pending until you manually approve the payment in your PayPal account.

  3. To receive guest checkout payments, which allow credit cards, enable the PayPal Account Optional option in your account settings. The path to this option for US accounts is:

    Profile > My selling tools > Website preferences > PayPal Account Optional

Create PayPal payment

After you collect the payment details from the customer, specify the payment details in a /payment call.

In the request URI, set the Access-Token.

In the JSON request body, set the intent to sale, the redirect URLs, the payment_method to paypal, and the transaction information in the transactions array, which contains one or more transaction objects:

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "intent": "sale",
  "payer": {
  "payment_method": "paypal"
  },
  "transactions": [
  {
    "amount": {
    "total": "30.11",
    "currency": "USD",
    "details": {
      "subtotal": "30.00",
      "tax": "0.07",
      "shipping": "0.03",
      "handling_fee": "1.00",
      "shipping_discount": "-1.00",
      "insurance": "0.01"
    }
    },
    "description": "This is the payment transaction description.",
    "custom": "EBAY_EMS_90048630024435",
    "invoice_number": "48787589673",
    "payment_options": {
    "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
    },
    "soft_descriptor": "ECHI5786786",
    "item_list": {
    "items": [
      {
      "name": "hat",
      "description": "Brown color hat",
      "quantity": "5",
      "price": "3",
      "tax": "0.01",
      "sku": "1",
      "currency": "USD"
      },
      {
      "name": "handbag",
      "description": "Black color hand bag",
      "quantity": "1",
      "price": "15",
      "tax": "0.02",
      "sku": "product34",
      "currency": "USD"
      }
    ],
    "shipping_address": {
      "recipient_name": "Hello World",
      "line1": "4thFloor",
      "line2": "unit#34",
      "city": "SAn Jose",
      "country_code": "US",
      "postal_code": "95131",
      "phone": "011862212345678",
      "state": "CA"
    }
    }
  }
  ],
  "note_to_payer": "Contact us for any questions on your order.",
  "redirect_urls": {
  "return_url": "http://www.amazon.com",
  "cancel_url": "http://www.hawaii.com"
  }
}'

A successful call returns confirmation of the transaction, with the created state and a payment ID that you can use in subsequent calls:

{
  "id": "PAY-1B56960729604235TKQQIYVY",
  "create_time": "2014-09-22T20:53:43Z",
  "update_time": "2014-09-22T20:53:44Z",
  "state": "created",
  "intent": "sale",
  "payer": {
    "payment_method": "paypal"
  },
  "transactions": [
    {
      "amount": {
        "total": "30.11",
        "currency": "USD",
        "details": {
          "subtotal": "30.00",
          "tax": "0.07",
          "shipping": "0.03",
          "handling_fee": "1.00",
          "insurance": "0.01",
          "shipping_discount": "-1.00"
        }
      },
      "description": "This is the payment transaction description.",
      "custom": "EBAY_EMS_90048630024435",
      "invoice_number": "48787589673",
      "item_list": {
        "items": [
          {
            "name": "hat",
            "sku": "1",
            "price": "3.00",
            "currency": "USD",
            "quantity": "5",
            "description": "Brown color hat",
            "tax": "0.01"
          },
          {
            "name": "handbag",
            "sku": "product34",
            "price": "15.00",
            "currency": "USD",
            "quantity": "1",
            "description": "Black color handbag",
            "tax": "0.02"
          }
        ],
        "shipping_address": {
          "recipient_name": "HelloWorld",
          "line1": "4thFloor",
          "line2": "unit#34",
          "city": "SAn Jose",
          "state": "CA",
          "phone": "011862212345678",
          "postal_code": "95131",
          "country_code": "US"
        }
      }
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/payments//cgi-bin/webscr?cmd=_express-checkout&token=EC-60385559L1062554J",
      "rel": "approval_url",
      "method": "REDIRECT"
    },
    {
      "href": "https://api.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY/execute",
      "rel": "execute",
      "method": "POST"
    }
  ]
}

Next, get approval from the customer for the payment.

Get payment approval

When you create a payment for a PayPal payment, the customer must approve the payment before you can execute the sale. To enable the customer to approve the payment, pass the id field to the payment function on your client. When the customer approves the payment, PayPal calls your client-side onAuthorize callback. PayPal passes the data.paymentID and data.payerID to your call back.

For details, see Set up your client.

Note: For legacy full-page-redirect integrations, redirect the customer to the approval_url from the create-payment response so that he or she can approve the payment.

For NVP/SOAP API full-page redirect integrations, PayPal does a full-page redirect to the return_url that was specified when the payment was created, with PayerID and paymentId appended to the URL.

Next, execute the payment.

Execute payment

To execute the payment after the customer's approval, make a /payment/execute/ call. In the JSON request body, use the payerID value that was passed to your site. In the header, use the access token that you used when you created the payment.

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/payment/PAY-34629814WL663112AKEE3AWQ/execute \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "payer_id": "RRCYJUTFJGZTA"
}'

The execute payment call returns a payment object with transaction details:

{
  "id": "PAY-4N746561P0587231SKQQK6MY",
  "create_time": "2014-09-22T23:22:27Z",
  "update_time": "2014-09-22T23:31:13Z",
  "state": "approved",
  "intent": "sale",
  "payer": {
    "payment_method": "paypal",
    "payer_info": {
      "email": "npurayil-uspr-60@paypal.com",
      "first_name": "Brian",
      "last_name": "Robinson",
      "payer_id": "JMKDKJ4D7DG7G",
      "shipping_address": {
        "line1": "4thFloor",
        "line2": "unit#34",
        "city": "SAn Jose",
        "state": "CA",
        "postal_code": "95131",
        "country_code": "US",
        "phone": "011862212345678",
        "recipient_name": "HelloWorld"
      }
    }
  },
  "transactions": [
    {
      "amount": {
        "total": "30.11",
        "currency": "USD",
        "details": {
          "subtotal": "30.00",
          "tax": "0.07",
          "shipping": "0.03",
          "handling_fee": "1.00",
          "insurance": "0.01",
          "shipping_discount": "-1.00"
        }
      },
      "description": "This is the payment transaction description.",
      "item_list": {
        "items": [
          {
            "name": "hat",
            "sku": "1",
            "price": "3.00",
            "currency": "USD",
            "quantity": "5",
            "description": "Brown color hat",
            "tax": "0.01"
          },
          {
            "name": "handbag",
            "sku": "product34",
            "price": "15.00",
            "currency": "USD",
            "quantity": "1",
            "description": "Black color handbag",
            "tax": "0.02"
          }
        ],
        "shipping_address": {
          "recipient_name": "HelloWorld",
          "line1": "4thFloor",
          "line2": "unit#34",
          "city": "SAn Jose",
          "state": "CA",
          "phone": "011862212345678",
          "postal_code": "95131",
          "country_code": "US"
        }
      },
      "related_resources": [
        {
          "sale": {
            "id": "4XP56210M0797192Y",
            "create_time": "2014-09-22T23:22:27Z",
            "update_time": "2014-09-22T23:31:13Z",
            "amount": {
              "total": "30.11",
              "currency": "USD"
            },
            "payment_mode": "INSTANT_TRANSFER",
            "state": "completed",
            "protection_eligibility": "ELIGIBLE",
            "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE",
            "transaction_fee": {
              "value": "1.75",
              "currency": "USD"
            },
            "parent_payment": "PAY-4N746561P0587231SKQQK6MY",
            "links": [
              {
                "href": "https://api.paypal.com/v1/payments/sale/4XP56210M0797192Y",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.paypal.com/v1/payments/sale/4XP56210M0797192Y/refund",
                "rel": "refund",
                "method": "POST"
              },
              {
                "href": "https://api.paypal.com/v1/payments/payment/PAY-4N746561P0587231SKQQK6MY",
                "rel": "parent_payment",
                "method": "GET"
              }
            ]
          }
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/payments/payment/PAY-4N746561P0587231SKQQK6MY",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Next

A sale is a completed payment. You can use the payment ID to show sale details and refund a sale.

Then, learn how to make credit card payments.

Additional information