> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PayPal
> Configure PayPal as a payment method in Gr4vy.
PayPal is a digital wallet that enables buyers to pay using their PayPal balance, bank accounts, or cards. It provides a trusted payment experience with buyer protection and is widely recognized by consumers worldwide.
## Setup
Follow the [PayPal setup instructions](./paypal) before configuring PayPal payments.
### Vaulting
To allow customers to tokenize their PayPal account for future payments, you need to contact PayPal and request that your account be enabled for **Vault**.
Once Vault has been enabled on your PayPal merchant account, you can toggle the tokenization feature on within the PayPal connector settings in the dashboard.
### Ingest billing and shipping details
By default, billing, and shipping details received from PayPal are not imported. To enable this feature, head over to **Connections** → **Configured** and select your PayPal connector. Next, go to **Credentials** and toggle **Import billing details** and/or **Import shipping details**.
When **Import billing details** is enabled, any of the user's name, email address, and billing address are automatically imported into your transaction, merging it with any data already present on the transaction. Linked buyers are not updated, but only the snapshot of the buyer on the transaction.
When **Import shipping details** is enabled, the user's shipping address is automatically **requested** and imported into your transaction, merging it with any data already present on the transaction. Linked buyers are not updated, but only the snapshot of the buyer on the transaction.
The ingestion of billing and shipping details is not available for tokenized payments.
### Payment receiving preferences
By default, PayPal only settles payments automatically if the payment is in the primary currency of the PayPal merchant account. If you need to accept payments in additional currencies, you need to open a PayPal account balance in each of the currencies you intend to accept. Alternatively, you can configure your PayPal merchant account to automatically convert payments into the primary currency.
If you receive a payment in a currency that your PayPal merchant account is not configured to accept, the payment enters a pending state and you need to log in to the PayPal merchant dashboard to trigger settlement, either by opening the required currency balance, or converting the payment into the primary currency of your PayPal account.
Payments left in a pending state are eventually reversed by PayPal.
### 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, 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 the API directly, you need to use the [device fingerprinting library](../../guides/features/anti-fraud/fingerprint) which includes the PayPal FraudNet library.
## Features
PayPal supports the following features:
* **Payment method tokenization** - Store PayPal accounts for recurring or future transactions
* **Delayed capture** - Authorize a payment and capture it at a later time (up to 3 days for PayPal, 29 days with Vault)
* **Over capture** - Capture up to 115% of the authorized amount or authorized amount + \$75 USD (whichever is less)
* **Partial capture** - Capture a portion of the authorized amount
* **Refunds** - Refund transactions in full or in part (up to 180 days)
* **Partial refunds** - Issue multiple partial refunds up to the captured amount
* **Void** - Cancel an authorized transaction before capture
* **Deep linking** - Direct integration with PayPal mobile app using deep links
* **Transaction sync** - Automatic synchronization of transaction status updates
* **Settlement reporting** - Detailed settlement reports via SFTP
* **Webhook integration** - Real-time notifications for payment events
## Supported countries
PayPal supports transactions from buyers in the following countries:
| Country code | Country code | Country code | Country code | Country code | Country code | Country code | Country code |
| ------------ | ------------ | ------------ | ------------ | ------------ | ------------ | ------------ | ------------ |
| `AD` | `AE` | `AG` | `AI` | `AL` | `AM` | `AO` | `AR` |
| `AT` | `AU` | `AW` | `AZ` | `BA` | `BB` | `BE` | `BF` |
| `BG` | `BH` | `BI` | `BJ` | `BM` | `BN` | `BO` | `BR` |
| `BS` | `BT` | `BW` | `BY` | `BZ` | `CA` | `CD` | `CG` |
| `CH` | `CI` | `CK` | `CL` | `CM` | `CO` | `CR` | `CV` |
| `CY` | `CZ` | `DE` | `DJ` | `DK` | `DM` | `DO` | `DZ` |
| `EC` | `EE` | `EG` | `ER` | `ES` | `ET` | `FI` | `FJ` |
| `FK` | `FM` | `FO` | `FR` | `GA` | `GB` | `GD` | `GE` |
| `GF` | `GI` | `GL` | `GM` | `GN` | `GP` | `GR` | `GT` |
| `GW` | `GY` | `HK` | `HN` | `HR` | `HU` | `ID` | `IE` |
| `IL` | `IN` | `IS` | `IT` | `JM` | `JO` | `JP` | `KE` |
| `KG` | `KH` | `KI` | `KM` | `KN` | `KR` | `KW` | `KY` |
| `KZ` | `LA` | `LC` | `LI` | `LK` | `LS` | `LT` | `LU` |
| `LV` | `MA` | `MC` | `MD` | `ME` | `MG` | `MH` | `MK` |
| `ML` | `MN` | `MQ` | `MR` | `MS` | `MT` | `MU` | `MV` |
| `MW` | `MX` | `MY` | `MZ` | `NA` | `NC` | `NE` | `NF` |
| `NG` | `NI` | `NL` | `NO` | `NP` | `NR` | `NU` | `NZ` |
| `OM` | `PA` | `PE` | `PF` | `PG` | `PH` | `PL` | `PM` |
| `PN` | `PT` | `PW` | `PY` | `QA` | `RE` | `RO` | `RS` |
| `RU` | `RW` | `SA` | `SB` | `SC` | `SE` | `SG` | `SH` |
| `SI` | `SJ` | `SK` | `SL` | `SM` | `SN` | `SO` | `SR` |
| `ST` | `SV` | `SZ` | `TC` | `TD` | `TG` | `TH` | `TJ` |
| `TM` | `TN` | `TO` | `TT` | `TV` | `TW` | `TZ` | `UA` |
| `UG` | `US` | `UY` | `VA` | `VC` | `VE` | `VG` | `VN` |
| `VU` | `WF` | `WS` | `YE` | `YT` | `ZA` | `ZM` | `ZW` |
## Supported currencies
PayPal supports processing payments in the following currencies:
| Currency code | Currency code | Currency code | Currency code | Currency code | Currency code | Currency code | Currency code |
| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
| `AUD` | `BRL` | `CAD` | `CHF` | `CNY` | `CZK` | `DKK` | `EUR` |
| `GBP` | `HKD` | `HUF` | `ILS` | `INR` | `JPY` | `MXN` | `MYR` |
| `NOK` | `NZD` | `PHP` | `PLN` | `RUB` | `SEK` | `SGD` | `THB` |
| `TWD` | `USD` | | | | | | |
## Limitations
The following features are not supported by this connector:
* **Zero auth** - Zero-dollar verification transactions are not supported
* **Partial authorization** - Partial authorization for insufficient funds is not available
## Integration
For PayPal, the default integration is through a redirect to PayPal's hosted checkout page.
Start by creating a new transaction with the following required fields.
```csharp C# theme={"system"}
var transaction = await client.Transactions.CreateAsync(
transactionCreate: new TransactionCreate()
{
Amount = 1299,
Currency = "USD",
Country = "US",
PaymentMethod =
TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
new RedirectPaymentMethodCreate()
{
Method = "paypal",
RedirectUrl = "https://example.com/callback",
}
),
}
);
```
```go Go theme={"system"}
amount := int64(1299)
currency := "USD"
country := "US"
method := "paypal"
redirectUrl := "https://example.com/callback"
redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
Method: method,
RedirectUrl: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)
transactionCreate := components.TransactionCreate{
Amount: amount,
Currency: currency,
Country: &country,
PaymentMethod: &paymentMethod,
}
transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
```
```java Java theme={"system"}
CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
.transactionCreate(TransactionCreate.builder()
.amount(1299L)
.currency("USD")
.country("US")
.paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
.method("paypal")
.redirectUrl("https://example.com/callback")
.build()))
.build())
.call();
Transaction transaction = transactionResponse.transaction().orElse(null);
```
```php PHP theme={"system"}
$transactionCreate = new TransactionCreate(
amount: 1299,
currency: 'USD',
country: 'US',
paymentMethod: new RedirectPaymentMethodCreate(
method: 'paypal',
redirectUrl: 'https://example.com/callback'
)
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;
```
```python Python theme={"system"}
transaction: models.Transaction = client.transactions.create(
amount=1299,
currency="USD",
country="US",
payment_method={
"method": "paypal",
"redirect_url": "https://example.com/callback",
}
)
```
```ts TypeScript theme={"system"}
const transaction = await gr4vy.transactions.create({
amount: 1299,
currency: "USD",
country: "US",
paymentMethod: {
method: "paypal",
redirectUrl: "https://example.com/callback"
}
})
```
After the transaction is created, the API response includes `payment_method.approval_url` and the `buyer_approval_pending` status.
```json theme={"system"}
{
"type": "transaction",
"id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
"payment_method": {
"type": "payment-method",
"approval_url": "https://www.paypal.com/checkoutnow?token=..."
},
"method": "paypal"
}
```
Redirect the buyer to the `approval_url` so they can log in to PayPal, review the transaction, and approve the payment. After approval, the buyer is redirected to the `redirect_url` you provided when creating the transaction. Do not rely solely on the redirect - either poll the transaction or (recommended) rely on webhooks to detect the final status (for example `capture_succeeded` or failure states).
### Direct integration
PayPal provides a [JavaScript SDK](https://developer.paypal.com/docs/checkout/standard/integrate/) for a direct integration. For this flow you should create a transaction on the server and then use the resulting `session_token` to get the session data required to initialize the PayPal JS SDK on your checkout page.
To start, follow the steps below for your integration path.
#### Web integration
1. Create a new transaction with the `integration_client` set to `web`.
```csharp C# theme={"system"}
var transaction = await client.Transactions.CreateAsync(
transactionCreate: new TransactionCreate()
{
Amount = 1299,
Currency = "USD",
Country = "US",
IntegrationClient = "web",
PaymentMethod =
TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
new RedirectPaymentMethodCreate()
{
Method = "paypal",
RedirectUrl = "https://example.com/callback",
}
),
}
);
```
```go Go theme={"system"}
amount := int64(1299)
currency := "USD"
country := "US"
integrationClient := "web"
method := "paypal"
redirectUrl := "https://example.com/callback"
redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
Method: method,
RedirectUrl: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)
transactionCreate := components.TransactionCreate{
Amount: amount,
Currency: currency,
Country: &country,
IntegrationClient: &integrationClient,
PaymentMethod: &paymentMethod,
}
transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
```
```java Java theme={"system"}
CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
.transactionCreate(TransactionCreate.builder()
.amount(1299L)
.currency("USD")
.country("US")
.integrationClient("web")
.paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
.method("paypal")
.redirectUrl("https://example.com/callback")
.build()))
.build())
.call();
Transaction transaction = transactionResponse.transaction().orElse(null);
```
```php PHP theme={"system"}
$transactionCreate = new TransactionCreate(
amount: 1299,
currency: 'USD',
country: 'US',
integrationClient: 'web',
paymentMethod: new RedirectPaymentMethodCreate(
method: 'paypal',
redirectUrl: 'https://example.com/callback'
)
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;
```
```python Python theme={"system"}
transaction: models.Transaction = client.transactions.create(
amount=1299,
currency="USD",
country="US",
integration_client="web",
payment_method={
"method": "paypal",
"redirect_url": "https://example.com/callback",
}
)
```
```ts TypeScript theme={"system"}
const transaction = await gr4vy.transactions.create({
amount: 1299,
currency: "USD",
country: "US",
integrationClient: "web",
paymentMethod: {
method: "paypal",
redirectUrl: "https://example.com/callback"
}
})
```
2. Use the `session_token` from the response to get the [session data](/reference/transactions/get-transaction-session) for the transaction.
```sh theme={"system"}
POST /transactions/:transaction_id/session?token=:session_token
```
```json theme={"system"}
{
"session_data": {
"intent": "CAPTURE",
"orderId": "5O190127JK314159X",
"clientId": "Ac3..._8",
"currency": "USD",
"merchantId": "9X...L",
"fundingSource": "paypal"
},
"default_completion_url": "https://api.sandbox.spider.gr4vy.app/transactions/:transaction_id/approval/some-token",
"integration_client": "web"
}
```
3. Load and initialize the PayPal JS SDK using the session data.
```js theme={"system"}
const sessionData = response.session_data;
const defaultCompletionUrl = response.default_completion_url;
const { orderId, clientId, currency, merchantId, fundingSource } = sessionData;
// Load the PayPal SDK with the clientId, currency, and merchantId
//
paypal.Buttons({
fundingSource: fundingSource,
createOrder: function(data, actions) {
// Return the orderId from the session data
return orderId;
},
onApprove: function(data, actions) {
// After the buyer approves the payment, send a GET request to the tokenized
// default_completion_url to finalize the transaction.
fetch(defaultCompletionUrl)
.then(response => {
if (response.ok) {
// Transaction completed successfully, redirect or show success message
} else {
// Completion failed - display error message and consider retrying
console.error('Transaction completion failed:', response.status);
}
})
.catch(error => {
// Network error - display error message to user
console.error('Network error during completion:', error);
});
}
}).render('#paypal-button-container');
```
#### Mobile integration
1. Create a new transaction with the `integration_client` set to `ios` or `android`. Use your app deep link for `redirect_url` (for example, `yourapp://`).
```csharp C# theme={"system"}
var transaction = await client.Transactions.CreateAsync(
transactionCreate: new TransactionCreate()
{
Amount = 1299,
Currency = "USD",
Country = "US",
IntegrationClient = "ios",
PaymentMethod =
TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
new RedirectPaymentMethodCreate()
{
Method = "paypal",
RedirectUrl = "yourapp://callback",
}
),
}
);
```
```go Go theme={"system"}
amount := int64(1299)
currency := "USD"
country := "US"
integrationClient := "ios"
method := "paypal"
redirectUrl := "yourapp://callback"
redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
Method: method,
RedirectUrl: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)
transactionCreate := components.TransactionCreate{
Amount: amount,
Currency: currency,
Country: &country,
IntegrationClient: &integrationClient,
PaymentMethod: &paymentMethod,
}
transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
```
```java Java theme={"system"}
CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
.transactionCreate(TransactionCreate.builder()
.amount(1299L)
.currency("USD")
.country("US")
.integrationClient("ios")
.paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
.method("paypal")
.redirectUrl("yourapp://callback")
.build()))
.build())
.call();
Transaction transaction = transactionResponse.transaction().orElse(null);
```
```php PHP theme={"system"}
$transactionCreate = new TransactionCreate(
amount: 1299,
currency: 'USD',
country: 'US',
integrationClient: 'ios',
paymentMethod: new RedirectPaymentMethodCreate(
method: 'paypal',
redirectUrl: 'yourapp://callback'
)
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;
```
```python Python theme={"system"}
transaction: models.Transaction = client.transactions.create(
amount=1299,
currency="USD",
country="US",
integration_client="ios",
payment_method={
"method": "paypal",
"redirect_url": "yourapp://callback",
}
)
```
```ts TypeScript theme={"system"}
const transaction = await gr4vy.transactions.create({
amount: 1299,
currency: "USD",
country: "US",
integrationClient: "ios",
paymentMethod: {
method: "paypal",
redirectUrl: "yourapp://callback"
}
})
```
2. Use the `session_token` to get the session data for mobile.
```sh theme={"system"}
POST /transactions/:transaction_id/session?token=:session_token
```
```json iOS theme={"system"}
{
"session_data": {
"intent": "capture",
"orderId": "5O190127JK314159X",
"clientId": "Ac3..._8",
"currency": "USD",
"merchantId": "9X...L",
"fundingSource": "paypal.FUNDING.PAYPAL"
},
"default_completion_url": "https://api.sandbox.spider.gr4vy.app/transactions/:transaction_id/approval/some-token",
"integration_client": "ios"
}
```
```json Android theme={"system"}
{
"session_data": {
"intent": "capture",
"orderId": "5O190127JK314159X",
"clientId": "Ac3..._8",
"currency": "USD",
"merchantId": "9X...L",
"fundingSource": "paypal.FUNDING.PAYPAL"
},
"default_completion_url": "https://api.sandbox.spider.gr4vy.app/transactions/:transaction_id/approval/some-token",
"integration_client": "android"
}
```
3. Initialize the PayPal Mobile SDK.
```swift iOS theme={"system"}
let orderId = sessionData.orderId
let clientId = sessionData.clientId
let defaultCompletionUrl = sessionData.defaultCompletionUrl
let config = CoreConfig(clientID: clientId, environment: .sandbox)
let checkoutClient = CheckoutNativeClient(config: config)
checkoutClient.start(presentingViewController: self, orderID: orderId) { result in
switch result {
case .success:
// After successful approval, call the default_completion_url
guard let url = URL(string: defaultCompletionUrl) else { return }
URLSession.shared.dataTask(with: url) { data, response, error in
// Handle success
}.resume()
case .failure(let error):
// Handle error
}
}
```
```kotlin Android theme={"system"}
val orderId = sessionData.orderId
val clientId = sessionData.clientId
val defaultCompletionUrl = sessionData.defaultCompletionUrl
val config = CheckoutConfig(
application = application,
clientId = clientId,
environment = Environment.SANDBOX,
currencyCode = CurrencyCode.USD,
userAction = UserAction.PAY_NOW
)
PayPalCheckout.setConfig(config)
PayPalCheckout.startCheckout { createOrder ->
createOrder.set(orderId)
}
// In the result callback, call the defaultCompletionUrl
val url = URL(defaultCompletionUrl)
val connection = url.openConnection() as HttpURLConnection
connection.requestMethod = "GET"
if (connection.responseCode == HttpURLConnection.HTTP_OK) {
// Transaction finalized
}
```
#### Complete the transaction
After the buyer completes the payment flow, the PayPal SDK provides an `onApprove` callback (Web) or a completion block/callback (Mobile). To finalize the payment, send a `GET` request to the tokenized `default_completion_url` from the session response. This URL is safe to call from the client as it contains an embedded token.
```sh theme={"system"}
GET :default_completion_url
```
The system automatically authorizes or captures the transaction once you call the approval endpoint. If `intent=capture`, the system captures the transaction.
Please refer to the [PayPal SDK documentation](https://developer.paypal.com/docs/checkout/standard/integrate/) for further guidance.
## Testing
PayPal provides a sandbox environment for testing transactions. After setting up your sandbox PayPal developer account, you can create test buyer accounts in the [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/accounts).
Use these test buyer accounts to log in during the redirect flow and approve test transactions. The sandbox environment simulates the production flow without processing real payments.
For detailed testing instructions and test account setup, see the [PayPal Developer documentation](https://developer.paypal.com/api/rest/sandbox/).