PayPal via the API

To handle PayPal via the API directly, follow our quick start guide on direct API integrations, or use the steps below.

​

Create a transactions

To create a PayPal transaction, set the method to paypal and the redirect_url to the endpoint of your application that can handle the customer returning once they’ve completed approving the transaction on paypal.com.

See the POST /transactions API endpoint for more details.

If successful, the response of this transaction will include a status set to buyer_approval_pending as well as a payment_method.approval_url.

{
    "type": "transaction",
    "id": "0c41c8df-27f4-480e-97f0-9401558ae25e",
    "status": "buyer_approval_pending",
    "intent": "authorize",
    "payment_method": {
        "type": "payment-method",
        "method": "paypal",
        "mode": "redirect",
        "approval_url": "https://www.sandbox.paypal.com/checkoutnow?token=7NP38594266148058",
       ...
    },
    "method": "paypal",
    ...
}

​

About tokenization

If your PayPal account supports Reference Transactions, then you can pass the store=true parameter to each request to vault a buyer’s PayPal account for future use.

This does require you to tick the Payment tokenization toggle for your PayPal connection in your dashboard.

Once stored, you can use the stored PayPal account for future transactions without redirecting the buyer to PayPal.

​

Handle redirect to PayPal

Your application will need to redirect your customer to PayPal where they will be required to authenticate the payment. To do so, redirect the customer to the payment_method.approval_url. After they’ve authenticated themselves, the customer will be redirected back to the redirect_url that you set when creating the transaction.

​

Handle the return to your app

When the customer is redirected back to your app, the transaction status is not known. Your application will therefore need to call our API to get the latest transaction status. To do this, your redirect_url will be appended with the transaction_id.

[redirect_url]?transaction_id=2f37e0d0-5549-42c4-9c5c-e03d5fa97148&transaction_status=capture_succeeded

After you’ve handled the redirect, you can display a message to your customer letting them know the result of the transaction.

​

Fetch the latest status

Finally, after the transaction has been created your application can get the latest details and status using the transaction ID received via the callback to the redirect URL, or on direct callback from the API.

The transaction includes details about the payment method used and the status of the transaction.

{
  "type": "transaction",
  "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "status": "authorized",
  "amount": 1299,
  "currency": "AUD",
  "payment_method": {
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "method": "paypal",
    ...
  },
  ...
}

​

Webhooks

In order to receive timely updates regarding the status of your PayPal transactions please set up a PayPal webhook URL. In the PayPal Merchant Dashboard create a webhook with that URL. Once set up you will be given a webhook ID by PayPal, provide this back to the team.

​

FraudNet

FraudNet is a PayPal-developed, JavaScript library that collects browser-based data to help reduce fraud. Upon checkout, the FraudNet library sends data elements to PayPal Risk Services for fraud and risk assessment.

When creating transactions using PayPal Billing Agreements, the PayPal FraudNet library must be included on the checkout page for all transactions. When using Embed, the PayPal FraudNet library is included automatically. If you are using Direct API directly, you will need to use the device fingerprinting library which includes the PayPal FraudNet library.

​

Set Transaction Context Values (STC)

Set transaction context values (STC) are used to provide additional information to support PayPal’s advanced risk analysis. Below is an outline of the values required. These values should be included in the connection options for PayPal (connection_options[paypal-paypal]). Below are examples for a retail or a marketplace transaction where retail transactions are those sold directly by the merchant on record, while a marketplace transaction is sold by a third party on the merchant’s website.

PayPal uses sender and receiver to refer to the transfer of funds where the sender is the buyer who is transmitting funds to the reciever or merchant.