On Ramp integration

On Ramp is a PayPal service that lets users buy fiat cryptocurrencies directly in their crypto wallets. Your customers can buy crypto with their PayPal account and then transfer it from their PayPal crypto balance to their crypto wallets.

On Ramp is currently only available to approved partners.

Eligibility

PayPal's On Ramp supports the following:

• Country: Available in all states in the US except Hawaii.
• Cryptocurrencies: Ethereum, Bitcoin, Bitcoin Cash, Litecoin, and PYUSD.
• Payment methods: Bank, PayPal balance, and Debit Cards.
• Limit for buying and transfering: USD to 10,000 USD.

How it works

1. The customer logs in to their crypto wallet, selects their country, and enters the amount of cryptocurrency they want to buy.
2. Your backend server calls the Configurations API to check if the customer is eligible to use PayPal as a payment method.
3. Based on the Configurations API’s response, your Web3 wallet presents PayPal as payment option. The customer selects the Buy with PayPal option.
4. Your backend server calls the Create Order Entry API to set up an order.
5. Your crypto wallet launches the PayPal On Ramp experience.
6. The customer logs in to PayPal, reviews, and approves the crypto order in the PayPal On Ramp experience.
7. The customer is redirected back to your crypto wallet from the PayPal On Ramp experience.
8. Your backend server calls the Get Order Details API to get the status of the order.
9. Your crypto wallet shows the customer a confirmation message.

Mobile user experience

Check out the mobile experience demo.

1. Choose your cryptocurrency

Start by selecting the cryptocurrency you want to buy. Enter the amount that you want to buy and confirm the order.

2. Review your order and buy

Review your order details and buy the cryptocurrency.

Test and live environments

In the test environment, the transactions take place on the testnets. In the live environment, all cryptocurrency transactions are executed on the mainnet.

Integration

To integrate this product, a PayPal representative will help you get a client ID and client secret, set up the stage environment, integrate the APIs, and go live.

1. Set up staging environment and get credentials

A PayPal sales representative will help you setup your staging environment and provide the Client ID and client secret required to access the PayPal APIs.

2. API reference

Call the PayPal APIs from your server-side code. This is to ensure a secure connection between the your system and PayPal, minimizing the possibility of your client ID and client secret getting compromised.

• Staging endpoint: https://api.test51.stage.paypal.com
• Production endpoint: https://api-m.paypal.com/

API sequence diagram

Authentication API

PayPal APIs use OAuth2 to authenticate the requests. To invoke the PayPal APIs, the partner is required to get the access token using the client ID and client secret created for the partner. The client ID and client secret must be accessed on the PayPal developer portal by the partner. The auth token expiration is 8 hours. Caching is recommended. Plan the refresh of the auth token accordingly.

POST https://api-m.paypal.com/v1/oauth2/token: Generate access token. Use this access token in the authorization header to invoke the below APIs. You need to refresh the access token after 8 hours after which it will expire.

Configurations API

The Configurations API returns the attributes to identify the eligibility of PayPal as a payment method. A GET call to the Configurations API returns attributes that show the eligibility of PayPal as a payment method depending on the request body. The attributes returned by the API includes supported fiat currency codes, countries, and your token.

GET https://api-m.paypal.com/v1/crypto/configurations

Modify the ACCESS-TOKEN with your token.

Sample request

1curl -v -k -X GET 'https://api-m.paypal.com/v1/crypto/configurations'  -H 'Authorization: Bearer ACCESS-TOKEN'  -H 'Content-Type: application/json'

Sample response

The response returns a HTTP 201 Created.

1{
2  "configurations": [
3    {
4      "intent": "TOPUP",
5      "country_codes": [
6        "US"
7      ],
8      "asset_symbols": [
9        "ETH"
10      ],
11      "attributes": {
12        "channels": [
13          "WEB"
14        ],
15        "currency_codes": [
16          "USD"
17        ],
18        "regions": {
19          "includes": {
20            "regions": [
21              "TX",
22              "CA"
23            ]
24          }
25        },
26        "min_limit": {
27          "value": "5",
28          "currency_code": "USD"
29        },
30        "max_limit": {
31          "value": "10000",
32          "currency_code": "USD"
33        }
34      }
35    },
36    {
37      "intent": "TOPUP",
38      "country_codes": [
39        "UK"
40      ],
41      "asset_symbols": [
42        "ETH"
43      ],
44      "attributes": {
45        "channels": [
46          "WEB"
47        ],
48        "currency_codes": [
49          "GBP"
50        ],
51        "regions": {
52          "includes": {
53            "include_all": true
54          }
55        },
56        "min_limit": {
57          "value": "5",
58          "currency_code": "GBP"
59        },
60        "max_limit": {
61          "value": "10000",
62          "currency_code": "GBP"
63        }
64      }
65    }
66  ],
67  "last_update_time ": "2023-02-25T01:20:00.000Z"
68}

The asset_symbol in the response can be either of the following:

1* `ETH`: Etherium
2* `BTC`: Bitcoin
3* `BCH`: Bitcoin cash
4* `LTC`: Litecoin
5* `PYUSD`: PayPal Stablecoin

Order Entry API

When the customer selects PayPal as the payment method and clicks the Buy with PayPal button, a call to create an order entry is made to the Order Entry API. The call makes an order entry for this transaction in PayPal and returns a redirect URL to initiate the On Ramp web flow.

POST https://api-m.paypal.com/v1/crypto/order-entries: Create an order entry in PayPal which returns a redirect URL on successful order creation.

This API creates an order entry in the crypto system that is used to create an order.

Copy the following code and modify it as follows:

• Set asset_symbol to the cryptocurrency you want. The four cryptocurrency type can set to are:

  • ETH: Etherium
  • BTC: Bitcoin
  • BCH: Bitcoin cash
  • LTC: Litecoin

• ReplaceACCESS-TOKEN with your token.

Note that intent must be set to `TOPUP.

Sample request

1curl -v -k -X POST 'https://api-m.paypal.com/v1/crypto/orders-entries'  -H 'PayPal-Request-Id: RequestID123'  -H 'Authorization: Bearer ACCESS-TOKEN'  -H 'Content-Type: application/json'  -d '{
2    "intent": "TOPUP",
3    "asset_symbol": "ETH",
4    "country_code": "US",
5    "region": "CA",
6    "fiat_amount": {
7        "value": "10",
8        "currency_code": "USD"
9    },
10    "receiver": {
11        "type": "BLOCKCHAIN_ADDRESS",
12        "id": "0xb794f5ea0ba39494ce839613fffba74279579268"
13    },
14    "partner": {
15        "order_id": "10000001",
16        "redirect_url": "/metamask/dashboard",
17        "channel": "WEB"
18    }
19}'

Sample response

The response returns a HTTP 201 Created.

1{
2  "id": "BCZXXK2PVTFDB",
3  "intent": "TOPUP",
4  "asset_symbol": "ETH",
5  "country_code": "US",
6  "region": "CA",
7  "fiat_amount": {
8    "value": "10",
9    "currency_code": "USD"
10  },
11  "receiver": {
12    "type": "BLOCKCHAIN_ADDRESS",
13    "id": "0xb794f5ea0ba39494ce839613fffba74279579268"
14  },
15  "partner": {
16    "order_id": "10000001",
17    "redirect_url": "/metamask/dashboard",
18    "channel": "WEB"
19  },
20  "token": "73895b68-1f45-11ed-861d-0242ac120002",
21  "redirect_url": "https://www.paypal.com/myaccount/crypto/ETH/topup/ingress?token=73895b68-1f45-11ed-861d-0242ac120002",
22  "create_time": "2020-01-17T01:20:00.000Z"
23}

PayPal order processing

The customer reviews and confirms the order on the review screen. The order is created. A risk and compliance check runs automatically in the back end.

After the order is created, PayPal Crypto front end redirects the user back to your platform using the redirect URL you shared in the Order Entry call.

This API returns the order status after you make the topup order. You will then be redirected to the PayPal Crypto URL which will initiate the On Ramp flow on PayPal.

Best practices for polling the Get Orders API are in the Reference section.

Order Details API

After you're redirected to your platform, call the Get Orders API to get the status of the order.

GET https://api-m.paypal.com/v1/crypto/orders: Get the order status after an order is made.

The asset_symbol in the response can be either of the following:

• ETH: Etherium
• BTC: Bitcoin
• BCH: Bitcoin cash
• LTC: Litecoin
• PYUSD: PayPal Stablecoin

Sample request

1curl -v -k -X GET 'https://api-m.paypal.com/v1/crypto/orders?order_entry_id=BCZXXK2PVTFDB'  -H 'Authorization: Bearer ACCESS-TOKEN'  -H 'Content-Type: application/json'

Sample response

The response returns a HTTP 200 OK.

1{
2  "orders": [
3    {
4      "id": "59L91489E3426142J",
5      "intent": "TOPUP",
6      "partner": {
7        "order_id": "10000001",
8        "channel": "WEB"
9      },
10      "type": "BUY",
11      "status": "COMPLETED",
12      "asset_symbol": "ETH",
13      "links": [
14        {
15          "href": "https://www.paypal.com/myaccount/activities/details/59L91489E3426142J",
16          "rel": "about"
17        }
18      ],
19      "topup_summary": {
20        "amount_breakdown": {
21          "total": {
22            "currency_code": "USD",
23            "value": "100.00"
24          },
25          "net": {
26            "currency_code": "USD",
27            "value": "103.50"
28          },
29          "fee": {
30            "currency_code": "USD",
31            "value": "3.50"
32          }
33        },
34        "asset_quantity": {
35          "asset_symbol": "ETH",
36          "quantity": "0.0040000"
37        },
38        "asset_exchange_rate": {
39          "fiat_amount": {
40            "currency_code": "USD",
41            "value": "8000.00"
42          },
43          "asset_quantity": {
44            "asset_symbol": "ETH",
45            "quantity": "1.0000000"
46          }
47        },
48        "blockchain_address": {
49          "value": "3Mbrg8W1nLERhX997ifHfoNVbdCP1hpq5c"
50        },
51        "transaction_hash": "f9bdcec15188150b0be44e1de4183e234541f4f96f24db86a03463e8a35213ed"
52      },
53      "create_time ": "2022-02-25T01:20:00.000Z",
54      "update_time": "2022-02-25T01:20:00.000Z"
55    }
56  ]
57}

A PayPal integration engineer will send you the Postman collection through email.

Go live

You'll need to go through the following steps to configure your live account.

Live account set up

You'll need to create a new PayPal business account that would act as your partner account. You can create a live PayPal Business account at PayPal.com.

When you have your PayPal business account ready, create a REST app and generate the client ID and client secret as follows:

1. Log into the developer dashboard with your live PayPal business account credentials.
2. Go to Apps & Credentials and select Create App.
3. Provide an app name and select sandbox developer account > Create App.
4. Toggle to Live on the top right and copy the client ID and client secret.
5. After you have the Rest app created with your live account, send the details below for the configurations to your PayPal integration engineer:
   1. Business account email address for your live PayPal account.
   2. Client ID of the REST app created for the live business account.

It takes up to 5 business days to get an account configured after your PayPal integration engineer receives your information. You'll be notified after the configurations are done.

Integration updates

You'll need to update your code to use the live account credentials and point to the PayPal live environment for your PayPal API calls when your live account is configured.

Integration verification

Before your PayPal integration goes live, we will do an integration verification. We'll tell you when the live testing can begin. You'll also need to provide us the emails of all the engineers who will be testing the integration.

As part of this live integration verification, you'll need to:

• Provide the test PayPal transaction IDs in the live environment and make sure all use cases are tested.
• Provide the buyer PayPal email addresses of all the people who will be involved in the live testing.
• Provide the screenshots of the completed testing of all the use cases.
• Follow the transaction limits by PayPal for each buyer. For example, $100 per user.

Your integration can go live when these steps are completed and we give you the approval.

Reports

These are the information you should refer to when integrating, such as reports and error cases when polling. There are 2 types of reports:

1. Daily Transactions Report

Used to share details of every single transaction daily for in-depth analysis. This report is available one day after data is collected.

Details included:

• Asset Symbol
• Crypto Address
• Chain-ID, fiat_amt
• Fiat_amt_usd
• Crypto_amt_out
• Crypto_fiat_amt_out
• Currency_code
• Asset_exchange_rate
• Transaction_Fee
• Blockchain_Transaction_Fee
• Partner_Fee
• Status
• Channel
• Order_Type
• Country

2. Monthly Revenue Share Report

Highlights total transaction volume and associated revenue share based on negotiated rate. Typically available within the first few days of every month.

Details included:

• Transaction type count
• Volume
• Fee
• Revshare
• Crypto ID
• Country

Polling the Get Orders API

Polling starts after PayPal redirects the customer back to the partner experience after they checkout. This will guarantee that the partner only polls when an order is created in PayPal, which is after the customers has paid. PayPal monitors all error cases and will fix the issue as soon as possible. You should start polling every 10 seconds when an order is created.

Error cases

1. If an order is stuck in pending and not completed when an order is created.

This case is for orders between status=PENDING and status=COMPLETED.

Start by polling every 10 seconds, then doubling the time up to 24 hours. If the status is still PENDING after an hour, the blockchain is congested or there is a system issue.

2. GET Orders API returns an HTTP 500.

Start by polling every 10 seconds, then doubling the time up to 24 hours to allow the system to recover. PayPal will address these issues as soon as possible.

3. Early Polling.

This case is only for partners that are unable to continue polling after an order is confirmed. This means that the order is stuck between status=INITIATED and status=PENDING. Note that this is not recommended because polling should start when an order is created.

To fix this, start by polling every 10 seconds, then doubling the time up to 1 hour.

After 5 minutes, if the status is still INITIATED, either the user is in the PayPal experience for a long time or there is a system issue.

Security guidelines

Follow these guidelines when integrating On Ramp.

Desktop implementation

To render the PayPal experience on desktop for the web or browser extensions, you must open it in a new browser window or tab.

Mobile implementation

To render the PayPal experience on mobile, you must use SFSafariViewController for iOS and Chrome Custom Tab for Android devices. These are the approved frameworks mandated by the PayPal security team that support privacy protection. These are required for secure interactive web experiences. PayPal does not allow iFrames or WebViews. 

Server-side interaction

PayPal APIs should be invoked only from your back-end server and not from the customer's device. This is to ensure a secure connection between your system and PayPal's system to avoid the partner client ID and client secret being compromised.