Accept PayPal with the Payments API

The Payments API provides:

  • Advanced web checkout that gives you control of the checkout process.
  • Trusted payment processing that’s streamlined and easy to use.
  • Full-featured checkout that includes payment and shipping pages handled through the customer’s PayPal account.
  • Light-touch payment servicing that handles the customer funding-source details for you when you supply item details and capture the payer ID.

How it works

Checkout work flow from shopping cart to PayPal to confirmation Shopping Cart PAYPAL PayPal LOGIN PayPal REVIEW Shopping Cart CONFIRM

When a customer selects PayPal to checkout, they are redirected to PayPal where they can log in to review the transaction details. After agreeing to fund the transaction with their PayPal account, PayPal redirects the customer back to the confirmation page on your website where you capture the payment.

Implementing PayPal checkout

You can choose to place the PayPal button on your checkout page using the PayPal shortcut or on the funding source selection page within your checkout flow. Learn more about getting the most out of PayPal Express Checkout in the Designing an Optimal Checkout Flow section.

Step 1:

Get an OAuth access token

These credentials (client_id, client_secret) are for testing purposes only. Visit the My Apps & Credentials page to create an app using your live credentials.

curl https://api.sandbox.paypal.com/v1/oauth2/token \
  -v \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "EOJ2S-Z6OoN_le_KS1d75wsZ6y0SFdVsY9183IvxFyZp:EClusMEUk8e9ihI7ZdVLF5cZ6y0SFdVsY9183IvxFyZp" \
  -d "grant_type=client_credentials"
require 'paypal-sdk-rest'
include PayPal::SDK::REST
PayPal::SDK.configure({
  :mode => "sandbox",
  :client_id => "AQkquBDf1zctJOWGKWUEtKXm6qVhueUEMvXO_-MCI4DQQ4-LWvkDLIN2fGsd",
  :client_secret => "EL1tVxAjhT7cJimnz5-Nsx9k2reTKSVfErNQF-CmrwJgxRtylkGTKlU4RvrX"
})
import paypalrestsdk
paypalrestsdk.configure({
  'mode': 'sandbox',
  'client_id': 'AQkquBDf1zctJOWGKWUEtKXm6qVhueUEMvXO_-MCI4DQQ4-LWvkDLIN2fGsd',
  'client_secret': 'EL1tVxAjhT7cJimnz5-Nsx9k2reTKSVfErNQF-CmrwJgxRtylkGTKlU4RvrX'
})
$sdkConfig = array(
  "mode" => "sandbox"
);

$cred = new OAuthTokenCredential("AQkquBDf1zctJOWGKWUEtKXm6qVhueUEMvXO_-MCI4DQQ4-LWvkDLIN2fGsd","EL1tVxAjhT7cJimnz5-Nsx9k2reTKSVfErNQF-CmrwJgxRtylkGTKlU4RvrX", $sdkConfig);
Map<String, String> sdkConfig = new HashMap<String, String>();
sdkConfig.put("mode", "sandbox");

String accessToken = new OAuthTokenCredential("AQkquBDf1zctJOWGKWUEtKXm6qVhueUEMvXO_-MCI4DQQ4-LWvkDLIN2fGsd", "EL1tVxAjhT7cJimnz5-Nsx9k2reTKSVfErNQF-CmrwJgxRtylkGTKlU4RvrX", sdkConfig).getAccessToken();
Dictionary<string, string> sdkConfig = new Dictionary<string, string>();
sdkConfig.Add("mode", "sandbox");
string accessToken = new OAuthTokenCredential("AQkquBDf1zctJOWGKWUEtKXm6qVhueUEMvXO_-MCI4DQQ4-LWvkDLIN2fGsd", "EL1tVxAjhT7cJimnz5-Nsx9k2reTKSVfErNQF-CmrwJgxRtylkGTKlU4RvrX", sdkConfig).GetAccessToken();

Step 2:

Add PayPal buttons to your site

Copy and paste the HTML snippet for the PayPal button into your code. When a customer clicks the button, a call is made to the Payments API.

Create a payment

Set the intent to sale, the payment_method to paypal and include redirect URLs. Now the customer will be presented with the Payments Review page where they can edit the funding source and shipping details. The user is then redirected to the specified URLs where they can approve or cancel the payment.

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":"https://example.com/your_redirect_url.html",
      "cancel_url":"https://example.com/your_cancel_url.html"
    },
    "payer":{
      "payment_method":"paypal"
    },
    "transactions":[
      {
        "amount":{
          "total":"7.47",
          "currency":"USD"
        }
      }
    ]
  }'
@payment = PayPal::SDK::REST::Payment.new({
  :intent => "sale",
  :payer => {
    :payment_method => "paypal" },
  :redirect_urls => {
    :return_url => "https://example.com/success/",
    :cancel_url => "https://example.com/canceled/" },
  :transactions => [ {
    :amount => {
      :total => "12",
      :currency => "USD" },
    :description => "creating a payment" } ] } )

@payment.create

payment = paypalrestsdk.Payment({
"intent": "sale",
"payer": {
"payment_method": "paypal" },
"redirect_urls": {
"return_url": "https://example.com/success/",
"cancel_url": "https://example.com/canceled/" },

"transactions": [ { "amount": { "total": "12", "currency": "USD" }, "description": "creating a payment" } ] } )

payment.create()

$sdkConfig = array(
"mode" => "sandbox"
);

$cred = "Bearer Access-Token"; $apiContext = new ApiContext($cred, 'Request' . time()); $apiContext->setConfig($sdkConfig);

$payer = new Payer(); $payer->setPayment_method("paypal");

$amount = new Amount(); $amount->setCurrency("USD"); $amount->setTotal("12");

$transaction = new Transaction(); $transaction->setDescription("creating a payment"); $transaction->setAmount($amount);

$baseUrl = getBaseUrl(); $redirectUrls = new RedirectUrls(); $redirectUrls->setReturn_url("https://example.com/success/); $redirectUrls->setCancel_url("https://example.com/canceled/");

$payment = new Payment(); $payment->setIntent("sale"); $payment->setPayer($payer); $payment->setRedirect_urls($redirectUrls); $payment->setTransactions(array($transaction));

$payment->create($apiContext);

Map<String, String> sdkConfig = new HashMap<String, String>();
sdkConfig.put("mode", "sandbox");

String accessToken = "Bearer Access-Token"; APIContext apiContext = new APIContext(accessToken); apiContext.setConfigurationMap(sdkConfig);

Amount amount = new Amount(); amount.setCurrency("USD"); amount.setTotal("12");

Transaction transaction = new Transaction(); transaction.setDescription("creating a payment"); transaction.setAmount(amount);

ListTransaction transactions = new ArrayListTransaction(); transactions.add(transaction);

Payer payer = new Payer(); payer.setPaymentMethod("paypal");

Payment payment = new Payment(); payment.setIntent("sale"); payment.setPayer(payer); payment.setTransactions(transactions); RedirectUrls redirectUrls = new RedirectUrls(); redirectUrls.setCancelUrl("https://example.com/canceled/"); redirectUrls.setReturnUrl("https://example.com/success/"); payment.setRedirectUrls(redirectUrls);

Payment createdPayment = payment.create(apiContext);

Dictionary<string, string> sdkConfig = new Dictionary<string, string>();
sdkConfig.Add("mode", "sandbox");
string accessToken = "Bearer Access-Token";
APIContext apiContext = new APIContext(accessToken);
apiContext.Config = sdkConfig;

Amount amnt = new Amount(); amnt.currency = "USD"; amnt.total = "12";

ListTransaction transactionList = new ListTransaction(); Transaction tran = new Transaction(); tran.description = "creating a payment"; tran.amount = amnt; transactionList.Add(tran);

Payer payr = new Payer(); payr.payment_method = "paypal";

RedirectUrls redirUrls = new RedirectUrls(); redirUrls.cancel_url = "https://example.com/canceled/"; redirUrls.return_url = "https://example.com/success/";

Payment pymnt = new Payment(); pymnt.intent = "sale"; pymnt.payer = payr; pymnt.transactions = transactionList; pymnt.redirect_urls = redirUrls;

Payment createdPayment = pymnt.Create(apiContext);

Receive a payment call response

If the preceding payment call is successful, PayPal returns a confirmation of the transaction with the state set to created as shown in the following sample.

{
  "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"
    }
  ]
}

Step 3:

Get payment approval and return user

Note the HATEOAS links in the example response above. Direct the user to the approval_url on the PayPal site, so that the user can approve the payment. PayPal then redirects the user to the return_url that was specified when the payment was created. A payer ID is appended to the return URL, as Payer-ID.

Step 4:

Execute payment request

Make a /payment/Payment-ID/execute call to execute the payment after the customer’s approval. Pass the Payment-ID (e.g., PAY-6RV70583SB702805EKEYSZ6Y) in the URL of the call. In the header, use the Access-Token that you used when you created the payment. In the body of the request, use the Payer-ID value that was appended to the return URL query string. For more information and code samples for payments, see Accept a PayPal Payment.

curl https://api.sandbox.paypal.com/v1/payments/payment/Payment-ID/execute/ \
  -v \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer Access-Token' \
  -d '{ "payer_id" : "Payer-ID " }'
@payment = PayPal::SDK::REST::Payment.new({
  :payment_id => "Payment-ID"})
@payment.execute( :payer_id => "Payer-ID " )
payment = paypalrestsdk.Payment.find("Payment-ID")
payment.execute({"payer_id": "Payer-ID "})
$sdkConfig = array(
  "mode" => "sandbox"
);

$cred = "Bearer Access-Token"; $apiContext = new ApiContext($cred, 'Request' . time()); $apiContext->setConfig($sdkConfig);

$payment = new Payment("Payment-ID"); $execution = new PaymentExecution(); $execution->setPayer_id("Payer-ID "); $payment->execute($execution, $apiContext);

String accessToken = "Bearer Access-Token";
APIContext apiContext = new APIContext(accessToken);
apiContext.setConfigurationMap(sdkConfig);

Payment payment = new Payment("Payment-ID"); PaymentExecution paymentExecute = new PaymentExecution(); paymentExecute.setPayerId("Payer-ID "); payment.execute(apiContext, paymentExecute);

Dictionary<string, string> sdkConfig = new Dictionary<string, string>();
sdkConfig.Add("mode", "sandbox");
string accessToken = "Bearer Access-Token";
APIContext apiContext = new APIContext(accessToken);
apiContext.Config = sdkConfig;

Payment payment = new Payment("Payment-ID"); PaymentExecution pymntExecution = new PaymentExecution(); pymntExecution.payer_id = ("Payer-ID "); Payment executedPayment = pymnt.Execute(apiContext,pymntExecution);

Customize your payment experience

Use the following APIs along with your PayPal integration to enhance your checkout experience and increase conversion.

  • Speed up payment and increase conversion by allowing customers to login through PayPal on your site using Log In with PayPal.
  • Increase flexibility by authorizing a transaction and capturing a payment later using Authorization and Capture.
  • Ensure repeat customers by accepting subscriptions or recurring payments using Billing Agreements.

For information about how to look up and refund a payment, see Payments.

Additional information