PayPal Payments

Use the Payments 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

1. Optional To make calls on behalf of a third party, you must be a partner in the PayPal Partner Program.
2. Required Get an access token.
3. Required Create sandbox accounts.
4. Required Create PayPal payment.
5. Required Get payment approval.
6. Required Execute payment.
7. Optional Search payment details.

Get an access token

  1. Create a PayPal app. In response, PayPal generates a set of OAuth credentials.

  2. Pass the OAuth credentials in a get access token call. In response, the PayPal authorization server issues an access token that you must use for authentication when you make REST API calls.

Create sandbox accounts

To generate mock transactions to test your app, complete these steps twice. First, create a business account to represent the merchant in a transaction. Then, create a personal account to represent the customer in a transaction.

  1. From the Developer Portal, click Log into Dashboard and enter your PayPal business account email and password.

    Note: If you do not have a business account, click Sign Up.
  2. Under Sandbox, click Accounts. Then, click Create Account.

  3. In the dialog box, enter these required fields:

    Field Value
    Account Type Business (Merchant Account) or Personal (Buyer Account).
    Email Address A fake or valid email address. If you use a valid address, you receive email notifications when you run test transactions.
    Password A simple, easy-to-remember password, such as 12345678.
    PayPal Balance A high amount. For example, 5000.

    You can also enter optional fields.

  4. Click Create Account.

For more information, see Create a sandbox account.

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": "https://example.com",
    "cancel_url": "https://example.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 existing 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"
    }
  ]
}

Search payment details

You can use the Payments API to list completed payments with transaction details. Then, use the transaction IDs in the response to complete other payment operations. For example, you can issue a refund for a payment, by transaction ID.

List payments with transaction details

To list payments with transaction details, enter query parameters to specify the time range of the transaction, how many payments to list, and the sort order of the payments in the response:

Action Query parameters Description
List transactions for a time range start_time end_time Specify the start and end times Internet date and time format.

For example: start_time=2017-03-06T11:00:00Z and end_time=2017-03-06T16:00:00Z
Define how many payments to list in the response count The response includes the next_id link, which is the ID of the next element. In a subsequent list payments calls, set start_id to the next_id value to get the next set of payments.
Sort payments by create or update time sort_by Sort payments by the payment create_time or update_time.

Request

This example request lists ten payments by update time in ascending order:

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payment?count=10&start_index=0&sort_by=update_time&sort_order=desc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

Response

The JSON response body lists payments that match the search criteria. The count field indicates the number of payments in the response. In a subsequent list payments call, set start_id to the next_id value to list the next set of payments.

{
  "payments": [
  {
    "id": "PAY-0US81985GW1191216KOY7OXA",
    "create_time": "2017-06-30T23:48:44Z",
    "update_time": "2017-06-30T23:49:27Z",
    "state": "approved",
    "intent": "order",
    "payer":
    {
      "payment_method": "paypal"
    },
    "transactions": [
    {
      "amount":
      {},
      "description": "The payment transaction description.",
      "item_list":
      {},
      "related_resources": []
    }],
    "links": []
  },
  {},
  {}],
  "count": 3,
  "next_id": "PAY-9X4935091L753623RKOZTRHI"
}

Show payment with transaction details

The show payment details, show sale details, and show captured payment details calls return an array of transactions that include transaction IDs. To show transaction details, call show payment details with a transaction ID.

For example, a payment request returns the following ID:

"id": "PAY-1B56960729604235TKQQIYVY"

Request

To show transaction details, specify the id in the following call:

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

Response

The response lists transactions:

{
  "id": "PAY-5YK922393D847794YKER7MUI",
  "create_time": "2017-02-19T22:01:53Z",
  "update_time": "2017-02-19T22:01:55Z",
  "state": "approved",
  "intent": "sale",
  "payer": {
    "payment_method": "credit_card",
    "funding_instruments": []
  },
  "transactions": [{
    "amount": {},
    "description": "The payment transaction description.",
    "note_to_payer": "Contact us for any questions on your order.",
    "related_resources": [{
      "sale": {
        "id": "36C38912MN9658832",
        "create_time": "2017-02-19T22:01:53Z",
        "update_time": "2017-02-19T22:01:55Z",
        "state": "completed",
        "amount": {},
        "protection_eligibility": "ELIGIBLE",
        "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE",
        "transaction_fee": {},
        "parent_payment": "PAY-5YK922393D847794YKER7MUI",
        "links": [{},
          {},
          {}
        ]
      }
    }]
  }],
  "links": []
}

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 authorize and capture payments.

Additional information

Feedback