PayPal

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

Server-side shipping callbacks

When Import shipping details is enabled, you can configure PayPal to call your server whenever the buyer changes their shipping address or selects a different shipping option during checkout. This lets you return updated shipping costs and available options in real time. To enable this, pass order_update_callback_config in connection_options["paypal-paypal"] when creating a transaction:

Field	Description
`callback_url`	The URL PayPal calls when the buyer updates their shipping details.
`callback_events`	Array of events to subscribe to. `"SHIPPING_ADDRESS"` fires when the buyer changes their shipping address; `"SHIPPING_OPTIONS"` fires when they change their selected shipping option.

When order_update_callback_config is set and shipping ingestion is enabled, Gr4vy sets the PayPal shipping_preference to GET_FROM_FILE so the buyer’s shipping details flow through your callback endpoint rather than being provided upfront.

var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "USD",
    Country = "US",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "paypal",
          Country = "US",
          Currency = "USD",
          RedirectUrl = "https://example.com/callback",
        }
      ),
    ConnectionOptions = new Dictionary<string, object>()
    {
      ["paypal-paypal"] = new Dictionary<string, object>()
      {
        ["order_update_callback_config"] = new Dictionary<string, object>()
        {
          ["callback_url"] = "https://example.com/shipping-callback",
          ["callback_events"] = new List<string> { "SHIPPING_ADDRESS", "SHIPPING_OPTIONS" },
        }
      }
    }
  }
);

amount := int64(1299)
currency := "USD"
country := "US"
method := components.RedirectPaymentMethodCreateMethodPaypal
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
  Method: method,
  Country: country,
  Currency: currency,
  RedirectURL: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
  Amount:        amount,
  Currency:      currency,
  Country:       &country,
  PaymentMethod: &paymentMethod,
  ConnectionOptions: map[string]interface{}{
    "paypal-paypal": map[string]interface{}{
      "order_update_callback_config": map[string]interface{}{
        "callback_url":    "https://example.com/shipping-callback",
        "callback_events": []string{"SHIPPING_ADDRESS", "SHIPPING_OPTIONS"},
      },
    },
  },
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
  .transactionCreate(TransactionCreate.builder()
    .amount(1299L)
    .currency("USD")
    .country("US")
    .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
      .method(RedirectPaymentMethodCreateMethod.PAYPAL)
      .country("US")
      .currency("USD")
      .redirectUrl("https://example.com/callback")
      .build()))
    .connectionOptions(Map.of(
      "paypal-paypal", Map.of(
        "order_update_callback_config", Map.of(
          "callback_url", "https://example.com/shipping-callback",
          "callback_events", List.of("SHIPPING_ADDRESS", "SHIPPING_OPTIONS")
        )
      )
    ))
    .build())
  .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
  amount: 1299,
  currency: 'USD',
  country: 'US',
  paymentMethod: new RedirectPaymentMethodCreate(
    method: 'paypal',
    country: 'US',
    currency: 'USD',
    redirectUrl: 'https://example.com/callback'
  ),
  connectionOptions: [
    'paypal-paypal' => [
      'order_update_callback_config' => [
        'callback_url' => 'https://example.com/shipping-callback',
        'callback_events' => ['SHIPPING_ADDRESS', 'SHIPPING_OPTIONS'],
      ]
    ]
  ]
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  payment_method={
    "method": "paypal",
    "country": "US",
    "currency": "USD",
    "redirect_url": "https://example.com/callback",
  },
  connection_options={
    "paypal-paypal": {
      "order_update_callback_config": {
        "callback_url": "https://example.com/shipping-callback",
        "callback_events": ["SHIPPING_ADDRESS", "SHIPPING_OPTIONS"],
      }
    }
  }
)

const transaction = await gr4vy.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  paymentMethod: {
    method: "paypal",
    country: "US",
    currency: "USD",
    redirectUrl: "https://example.com/callback"
  },
  connectionOptions: {
    "paypal-paypal": {
      order_update_callback_config: {
        callback_url: "https://example.com/shipping-callback",
        callback_events: ["SHIPPING_ADDRESS", "SHIPPING_OPTIONS"],
      }
    }
  }
})

Checkout experience

You can customize the PayPal Checkout page by passing any of the following fields in connection_options["paypal-paypal"] when creating a transaction.

Field	Description
`user_action`	Controls the label on the PayPal Checkout button. `"PAY_NOW"` (default) shows an immediate pay button; `"CONTINUE"` shows a continue button for deferred-payment flows.
`shipping_preference`	Controls how the shipping address is sourced during checkout. `"NO_SHIPPING"` hides the shipping address fields; `"GET_FROM_FILE"` lets the buyer provide or change their address during checkout; `"SET_PROVIDED_ADDRESS"` pre-fills the address you supplied and prevents the buyer from changing it. When omitted, Gr4vy determines this value automatically (see the note below).
`brand_name`	The merchant brand name displayed on the PayPal Checkout page. Maximum 127 characters.
`landing_page`	The page shown to the buyer when they arrive at PayPal. `"LOGIN"` opens the PayPal login page; `"GUEST_CHECKOUT"` opens the guest checkout page; `"NO_PREFERENCE"` lets PayPal decide.
`locale`	A BCP 47 locale tag used to localize the PayPal Checkout page, for example `"en-US"` or `"fr-FR"`.

"GUEST_CHECKOUT" for landing_page only takes effect if PayPal account optional is enabled in your PayPal merchant account settings. If the setting is not enabled, PayPal falls back to showing the login page regardless.

locale is a hint to PayPal and may not always be honored. PayPal also determines locale from the buyer’s browser cookies and the configuration of its own SDK, so the effective locale can differ from the value you provide.

ConnectionOptions = new Dictionary<string, object>()
{
  ["paypal-paypal"] = new Dictionary<string, object>()
  {
    ["user_action"] = "PAY_NOW",
    ["shipping_preference"] = "GET_FROM_FILE",
    ["brand_name"] = "Acme Store",
    ["landing_page"] = "LOGIN",
    ["locale"] = "en-US",
  }
}

ConnectionOptions: map[string]interface{}{
  "paypal-paypal": map[string]interface{}{
    "user_action":         "PAY_NOW",
    "shipping_preference": "GET_FROM_FILE",
    "brand_name":          "Acme Store",
    "landing_page":        "LOGIN",
    "locale":              "en-US",
  },
},

.connectionOptions(Map.of(
  "paypal-paypal", Map.of(
    "user_action", "PAY_NOW",
    "shipping_preference", "GET_FROM_FILE",
    "brand_name", "Acme Store",
    "landing_page", "LOGIN",
    "locale", "en-US"
  )
))

connectionOptions: [
  'paypal-paypal' => [
    'user_action' => 'PAY_NOW',
    'shipping_preference' => 'GET_FROM_FILE',
    'brand_name' => 'Acme Store',
    'landing_page' => 'LOGIN',
    'locale' => 'en-US',
  ]
]

transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  payment_method={
    "method": "paypal",
    "country": "US",
    "currency": "USD",
    "redirect_url": "https://example.com/callback",
  },
  connection_options={
    "paypal-paypal": {
      "user_action": "PAY_NOW",
      "shipping_preference": "GET_FROM_FILE",
      "brand_name": "Acme Store",
      "landing_page": "LOGIN",
      "locale": "en-US",
    }
  }
)

const transaction = await gr4vy.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  paymentMethod: {
    method: "paypal",
    country: "US",
    currency: "USD",
    redirectUrl: "https://example.com/callback",
  },
  connectionOptions: {
    "paypal-paypal": {
      user_action: "PAY_NOW",
      shipping_preference: "GET_FROM_FILE",
      brand_name: "Acme Store",
      landing_page: "LOGIN",
      locale: "en-US",
    },
  },
});

shipping_preference is automatically determined by Gr4vy when not set. It is set to GET_FROM_FILE when order_update_callback_config is set and shipping ingestion is enabled, SET_PROVIDED_ADDRESS when a shipping address is supplied on the transaction, and NO_SHIPPING otherwise. Setting shipping_preference explicitly overrides this automatic behavior.

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 which includes the PayPal FraudNet library.

Capabilities

Supported countries

Supported currencies

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.

var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "USD",
    Country = "US",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "paypal",
          Country = "US",
          Currency = "USD",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);

amount := int64(1299)
currency := "USD"
country := "US"
method := components.RedirectPaymentMethodCreateMethodPaypal
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
  Method: method,
  Country: country,
  Currency: currency,
  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, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
  .transactionCreate(TransactionCreate.builder()
    .amount(1299L)
    .currency("USD")
    .country("US")
    .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
      .method(RedirectPaymentMethodCreateMethod.PAYPAL)
      .country("US")
      .currency("USD")
      .redirectUrl("https://example.com/callback")
      .build()))
    .build())
  .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
  amount: 1299,
  currency: 'USD',
  country: 'US',
  paymentMethod: new RedirectPaymentMethodCreate(
    method: 'paypal',
    country: 'US',
    currency: 'USD',
    redirectUrl: 'https://example.com/callback'
  )
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  payment_method={
    "method": "paypal",
    "country": "US",
    "currency": "USD",
    "redirect_url": "https://example.com/callback",
  }
)

const transaction = await gr4vy.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  paymentMethod: {
    method: "paypal",
    country: "US",
    currency: "USD",
    redirectUrl: "https://example.com/callback"
  }
})

After the transaction is created, the API response includes payment_method.approval_url and the buyer_approval_pending status.

{
  "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 client SDKs for a direct integration where PayPal’s own checkout UI runs on your page or in your app. The two platforms differ in one important way:

Web renders PayPal’s Smart Button on the page before the buyer acts, and the button needs the PayPal clientId to load. To get that without creating a transaction on every page load, you preload the connection’s clientId/merchantId from a standalone session, then create the transaction and PayPal order lazily inside the SDK’s createOrder callback.
Mobile does not need this preload. PayPal’s native iOS/Android SDK is launched with an order that already exists, so you create the transaction when the buyer taps and hand the resulting orderId to the SDK — there is no button to render up front.

Pick your platform below. Both finish with the shared completion step.

Both platforms below have Gr4vy create the PayPal order for you as part of creating the transaction. If you already run your own PayPal SDK integration and want to keep it, see Bring your own PayPal integration instead — you keep control of the order and hand Gr4vy the approved order id at the end.

A minimal end-to-end web example is available at gr4vy/sample-paypal-direct. It pairs an Express server that proxies the standalone session and creates the transaction through the Gr4vy SDK with a vanilla-JS frontend that renders the PayPal Smart Button and creates the order on click.

Web
Mobile

The Smart Button renders on page load, so you preload the clientId/merchantId and defer the transaction to createOrder.

On page load, fetch the standalone session to get the connection’s clientId and merchantId. This requires the transactions.write scope, so call it from your server. It creates no transaction and makes no call to PayPal.

var session = await client.PaymentServices.SessionAsync(
  paymentServiceId: "<payment_service_id>",
  requestBody: new Dictionary<string, object>()
);

// session.ResponseBody contains clientId and merchantId

session, err := client.PaymentServices.Session(
  ctx,
  "<payment_service_id>",
  map[string]any{},
  nil,
)

// session.ResponseBody contains clientId and merchantId

CreatePaymentServiceSessionResponse response = gr4vyClient.paymentServices().session()
  .paymentServiceId("<payment_service_id>")
  .requestBody(java.util.Map.of())
  .call();

CreateSession session = response.createSession().orElseThrow();
// session.responseBody() contains clientId and merchantId

$response = self::$sdk->paymentServices->session(
  paymentServiceId: '<payment_service_id>',
  requestBody: [],
);

$config = $response->createSession->responseBody; // clientId and merchantId

session = client.payment_services.session(
  payment_service_id="<payment_service_id>",
  request_body={},
)

# session.response_body contains clientId and merchantId

const session = await gr4vy.paymentServices.session({}, "<payment_service_id>");

// session.responseBody contains clientId and merchantId

The response body holds just the two IDs. It contains no orderId, because no order exists until the buyer clicks.

{
  "clientId": "Ac3..._8",
  "merchantId": null
}

This call is optional. The clientId and merchantId are static connection values, so if you already have them you can skip the standalone session and pass them straight to the PayPal JS SDK. The session endpoint exists so you don’t have to hard-code or separately distribute the connection’s credentials to your frontend.

Also on page load, initialize the PayPal JS SDK with the clientId from the standalone session and render the Smart Button. Set currency to the same currency as the order you create in createOrder (a mismatch fails the integration), and set intent to match the connection’s configured intent. The button defers the work to its createOrder callback, so the transaction and order are created on click (steps 3 and 4).

// From the standalone session in step 1:
const { clientId, merchantId } = standaloneSession;

// Load the PayPal SDK with the clientId. Set the intent parameter to match the
// transaction intent and the connection's configured intent (authorize or capture).
// This example uses capture, matching the transaction and session data below:
// <script src="https://www.paypal.com/sdk/js?client-id=${clientId}&currency=USD&intent=capture"></script>
//
// When merchantId is not null, add it as the merchant-id parameter:
// <script src="https://www.paypal.com/sdk/js?client-id=${clientId}&merchant-id=${merchantId}&currency=USD&intent=capture"></script>

let defaultCompletionUrl = null;

paypal.Buttons({
  fundingSource: paypal.FUNDING.PAYPAL,
  createOrder: async function() {
    // Step 3: your server creates the transaction (needs the private key).
    const { transactionId, sessionToken } = await createTransaction();

    // Step 4: exchange the session token for the orderId and completion URL.
    const session = await fetchTransactionSession(transactionId, sessionToken);
    defaultCompletionUrl = session.default_completion_url;
    return session.session_data.orderId;
  },
  onApprove: function() {
    // After the buyer approves, navigate to the default_completion_url to
    // finalize the transaction. That URL returns an HTTP 303 redirect back to
    // your redirect_url with the transaction result appended.
    window.location.assign(defaultCompletionUrl);
  }
}).render('#paypal-button-container');

Inside the SDK’s createOrder callback, create a transaction with the integration_client set to web. Keep this call server-side. Set the transaction intent to match the connection’s configured intent.

var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "USD",
    Country = "US",
    IntegrationClient = "web",
    Intent = "capture",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "paypal",
          Country = "US",
          Currency = "USD",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);

amount := int64(1299)
currency := "USD"
country := "US"
integrationClient := "web"
intent := components.TransactionIntentCapture
method := components.RedirectPaymentMethodCreateMethodPaypal
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
  Method: method,
  Country: country,
  Currency: currency,
  RedirectURL: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
  Amount:            amount,
  Currency:          currency,
  Country:           &country,
  IntegrationClient: &integrationClient,
  Intent:            &intent,
  PaymentMethod:     &paymentMethod,
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
  .transactionCreate(TransactionCreate.builder()
    .amount(1299L)
    .currency("USD")
    .country("US")
    .integrationClient("web")
    .intent(TransactionIntent.CAPTURE)
    .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
      .method(RedirectPaymentMethodCreateMethod.PAYPAL)
      .country("US")
      .currency("USD")
      .redirectUrl("https://example.com/callback")
      .build()))
    .build())
  .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
  amount: 1299,
  currency: 'USD',
  country: 'US',
  integrationClient: 'web',
  intent: 'capture',
  paymentMethod: new RedirectPaymentMethodCreate(
    method: 'paypal',
    country: 'US',
    currency: 'USD',
    redirectUrl: 'https://example.com/callback'
  )
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  integration_client="web",
  intent="capture",
  payment_method={
    "method": "paypal",
    "country": "US",
    "currency": "USD",
    "redirect_url": "https://example.com/callback",
  }
)

const transaction = await gr4vy.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  integrationClient: "web",
  intent: "capture",
  paymentMethod: {
    method: "paypal",
    country: "US",
    currency: "USD",
    redirectUrl: "https://example.com/callback"
  }
})

Still inside createOrder, use the session_token from the transaction response to get the session data. This returns the orderId and a default_completion_url. It is meant to be called from the frontend and is not exposed in the SDKs, so call it with a plain request authenticated by the session_token. Return the orderId from createOrder so the PayPal SDK can open the approval flow.

POST /transactions/:transaction_id/session?token=:session_token

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

No standalone session is needed: PayPal’s native SDK is launched with an order that already exists, so you create the transaction when the buyer taps and pass the resulting orderId to the SDK.

Create a new transaction with the integration_client set to ios or android. Use your app deep link for redirect_url (for example, yourapp://).

var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "USD",
    Country = "US",
    IntegrationClient = "ios",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "paypal",
          Country = "US",
          Currency = "USD",
          RedirectUrl = "yourapp://callback",
        }
      ),
  }
);

amount := int64(1299)
currency := "USD"
country := "US"
integrationClient := "ios"
method := components.RedirectPaymentMethodCreateMethodPaypal
redirectUrl := "yourapp://callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
  Method: method,
  Country: country,
  Currency: currency,
  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, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
  .transactionCreate(TransactionCreate.builder()
    .amount(1299L)
    .currency("USD")
    .country("US")
    .integrationClient("ios")
    .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
      .method(RedirectPaymentMethodCreateMethod.PAYPAL)
      .country("US")
      .currency("USD")
      .redirectUrl("yourapp://callback")
      .build()))
    .build())
  .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
  amount: 1299,
  currency: 'USD',
  country: 'US',
  integrationClient: 'ios',
  paymentMethod: new RedirectPaymentMethodCreate(
    method: 'paypal',
    country: 'US',
    currency: 'USD',
    redirectUrl: 'yourapp://callback'
  )
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  integration_client="ios",
  payment_method={
    "method": "paypal",
    "country": "US",
    "currency": "USD",
    "redirect_url": "yourapp://callback",
  }
)

const transaction = await gr4vy.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  integrationClient: "ios",
  paymentMethod: {
    method: "paypal",
    country: "US",
    currency: "USD",
    redirectUrl: "yourapp://callback"
  }
})

Use the session_token to get the session data for mobile.

POST /transactions/:transaction_id/session?token=:session_token

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

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

Initialize the PayPal Mobile SDK.

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
    }
}

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, call the tokenized default_completion_url from the session response. This URL is safe to call from the client as it contains an embedded token. On Web, navigate the browser to the URL (for example, window.location.assign(default_completion_url)) so it follows the HTTP 303 redirect back to your redirect_url. On Mobile, send a GET request to the URL from your completion callback.

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 for further guidance.

Bring your own PayPal integration

If you already have a working PayPal SDK integration, you do not have to rebuild it around Gr4vy’s session and completion flow. You can keep driving PayPal yourself and involve Gr4vy only at the end, by passing the approved order id when you create the transaction. Compared to the Web and Mobile flows above, the ownership is reversed:

Responsibility	Web / Mobile above	Bring your own
Creates the PayPal order	Gr4vy, while creating the transaction	You, before any Gr4vy call
Needs the standalone session for `clientId`	Yes	No — you already have your own
Buyer approval	Driven by the `orderId` Gr4vy returns	Driven entirely by your PayPal SDK
Finalizing	`GET` the `default_completion_url`	The transaction creation call itself

The flow is:

Create a PayPal order — either through your own backend call to PayPal, or through Gr4vy’s order pass-through below.
Have the buyer approve it with your existing PayPal JS or native SDK integration.
Create the Gr4vy transaction with the approved order id in order_id.

Creating the order through Gr4vy

Gr4vy’s session endpoint can forward an order straight to PayPal’s Orders API, so you can retire your own order-creation endpoint and keep your PayPal credentials in one place. Send action: "create-order" with the order body in payload:

POST /payment-service-definitions/paypal-paypal/sessions

{
  "action": "create-order",
  "payload": {
    "intent": "AUTHORIZE",
    "purchase_units": [
      { "amount": { "currency_code": "USD", "value": "12.99" } }
    ]
  }
}

The payload is passed to PayPal untouched and PayPal’s response is returned unchanged, so anything the Orders API accepts works here without waiting on a Gr4vy release. No transaction is created by this call.

{
  "id": "5O190127TN364715T",
  "status": "PAYER_ACTION_REQUIRED",
  "intent": "AUTHORIZE",
  "links": [
    { "rel": "payer-action", "href": "https://www.paypal.com/checkoutnow?token=...", "method": "GET" }
  ]
}

Hand the returned id to your PayPal SDK exactly as you would an order created by your own backend. The same endpoint is also available per configured connection at POST /payment-services/{payment_service_id}/sessions if you need to target a specific connection rather than the definition.

Omitting action returns the connection’s clientId and merchantId instead, as used by the Web flow above. An unrecognized action, or create-order without a payload, is rejected.

Authorizing the approved order

Once the buyer has approved the order, create the transaction with order_id in connection_options["paypal-paypal"]:

Field	Description
`order_id`	The ID of an existing, buyer-approved PayPal order. When set, Gr4vy retrieves this order instead of creating a new one, then authorizes or captures it depending on the transaction’s `intent`.

The order must already be approved by the buyer before you create the transaction, and the transaction’s intent must match the intent the order was created with in PayPal (authorize or capture) - a mismatch is rejected before any authorization is attempted. Since approval already happened, this skips the buyer_approval_pending step - there is no approval_url to redirect to, and the transaction creation response returns the authorization or capture result directly.

ConnectionOptions = new Dictionary<string, object>()
{
  ["paypal-paypal"] = new Dictionary<string, object>()
  {
    ["order_id"] = "5O190127TN364715T",
  }
}

ConnectionOptions: map[string]interface{}{
  "paypal-paypal": map[string]interface{}{
    "order_id": "5O190127TN364715T",
  },
},

.connectionOptions(Map.of(
  "paypal-paypal", Map.of(
    "order_id", "5O190127TN364715T"
  )
))

connectionOptions: [
  'paypal-paypal' => [
    'order_id' => '5O190127TN364715T',
  ]
]

transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  intent="authorize",
  payment_method={
    "method": "paypal",
    "country": "US",
    "currency": "USD",
    "redirect_url": "https://example.com/callback",
  },
  connection_options={
    "paypal-paypal": {
      "order_id": "5O190127TN364715T",
    }
  }
)

const transaction = await gr4vy.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  intent: "authorize",
  paymentMethod: {
    method: "paypal",
    country: "US",
    currency: "USD",
    redirectUrl: "https://example.com/callback",
  },
  connectionOptions: {
    "paypal-paypal": {
      order_id: "5O190127TN364715T",
    },
  },
});

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

Introduction

Aggregators

Methods

Digital wallets

Anti-fraud

Browse

Setup

Vaulting

Ingest billing and shipping details

Server-side shipping callbacks

Checkout experience

Payment receiving preferences

FraudNet

Capabilities

Supported countries

Supported currencies

Integration

Direct integration

Complete the transaction

Bring your own PayPal integration

Creating the order through Gr4vy

Authorizing the approved order

Testing

​Setup

​Vaulting

​Ingest billing and shipping details

​Server-side shipping callbacks

​Checkout experience

​Payment receiving preferences

​FraudNet

​Capabilities

​Supported countries

​Supported currencies

​Integration

​Direct integration

​Complete the transaction

​Bring your own PayPal integration

Creating the order through Gr4vy

Authorizing the approved order

​Testing

Setup

Vaulting

Ingest billing and shipping details

Server-side shipping callbacks

Checkout experience

Payment receiving preferences

FraudNet

Capabilities

Supported countries

Supported currencies

Integration

Direct integration

Complete the transaction

Bring your own PayPal integration

Testing