Accept PayPal payments

To accept a PayPal payment:

  1. Create a payment.
  2. Get payment approval.
  3. Execute the payment.

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

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

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

Create a payment

Collect the payment details from the buyer.

Request

Specify the payment details in a /payment call.

Set the intent to sale, include redirect URLs, and set the payment_method to paypal.

curl https://api.sandbox.paypal.com/v1/payments/payment \
  -v \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer Access-Token' \
  -d '{
  "intent": "sale",
  "redirect_urls":
  {
    "return_url": "http://return_URL_here",
    "cancel_url": "http://cancel_URL_here"
  },
  "payer":
  {
    "payment_method": "paypal"
  },
  "transactions": [
  {
    "amount":
    {
      "total": "7.47",
      "currency": "USD"
    },
    "description": "This is the payment transaction description."
  }]
}'

For information about the required access token, see How PayPal uses OAuth 2.0.

Response

A successful call returns a confirmation of the transaction with the state set to created.

{
  "id":"PAY-6RV70583SB702805EKEYSZ6Y",
  "create_time":"2013-03-01T22:34:35Z",
  "update_time":"2013-03-01T22:34:36Z",
  "state":"created",
  "intent":"sale",
  "payer":{
    "payment_method":"paypal"
  },
  "transactions":[
    {
      "amount":{
        "total":"7.47",
        "currency":"USD",
        "details":{
          "subtotal":"7.47"
        }
      },
      "description":"This is the payment transaction description."
    }
  ],
  "links":[
    {
      "href":"https://api.sandbox.paypal.com/v1/payments/payment/PAY-6RV70583SB702805EKEYSZ6Y",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"https://www.sandbox.paypal.com/webscr?cmd=_express-checkout&token=EC-60U79048BN7719609",
      "rel":"approval_url",
      "method":"REDIRECT"
    },
    {
      "href":"https://api.sandbox.paypal.com/v1/payments/payment/PAY-6RV70583SB702805EKEYSZ6Y/execute",
      "rel":"execute",
      "method":"POST"
    }
  ]
}

In the response:

  • id. The PayPal-generated ID for the payment.
  • state. The state of the payment. The value is:
    • created. The payment was successfully created.
    • approved. The buyer approved the payment.
    • failed. The payment request failed.
  • create_time. The date and time when the payment was created.

Get payment approval

The buyer must approve the payment before you can execute the sale. To enable the buyer to approve the payment, pass the id field to the payment function on your client. For detailed instructions, see Set up your client in the Advanced server integration.

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

Execute the payment

When the buyer approves the payment, PayPal calls your client-side onAuthorize callback. For details, see Set up your client in the advanced server integration. PayPal passes the data.paymentID and data.payerID to your call back.

Note: 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.

To execute the payment after the buyer'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 https://api.sandbox.paypal.com/v1/payments/payment/PAY-6RV70583SB702805EKEYSZ6Y/execute/ \
  -v \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer Access-Token' \
  -d '{
  "payer_id": "7E7MGXCWTTKK2"
}'

Note: A completed payment is known as a sale. You can show sale details and refund a sale.

Additional information