---
# System prepended metadata

title: PayPal

---

PayPal
===

### Integrate on your servers
#### Creating transactions
Once the customer has successfully authenticated with PayPal, include the [paymentMethodId](https://graphql.braintreepayments.com/guides/concepts/#the-lifecycle-of-a-payment) parameter in the [chargePayPalAccount](https://graphql.braintreepayments.com/reference/#Mutation--chargePayPalAccount) call on your server.
#### Using device data
If the PayPal transaction was initiated from a Vault record and is not a recurring transaction, [collect device data](https://developer.paypal.com/braintree/docs/guides/premium-fraud-management-tools/device-data-collection) from the client and include the collected client device data via the *deviceData* parameter inside *riskData*. Doing so will help reduce decline rates.

Below includes an example call with relevant PayPal parameters and device data:

<MutationCodeBlock>
{`mutation ChargePayPalAccount($input: ChargePayPalAccountInput!){ 
  chargePayPalAccount(input: $input) {
      transaction {
        id
        amount {
          value
          currencyCode
        }
        paymentMethodSnapshot {
          ...on PayPalTransactionDetails{
            captureId
            payerStatus
          }
        }
      }
  }
}`}
</MutationCodeBlock>
<VariablesCodeBlock>
{`{
  "input": {
    "paymentMethodId": "fake-paypal-one-time-nonce",
    "transaction": {
      "amount": "10.00",
      "orderId": "orderId",
      "riskData": {
        "customerBrowser": "netscap_1.0",
        "customerIp": "8.8.8.8",
        "deviceData": "android_v15.0_z2"
      },
      "vaultPaymentMethodAfterTransacting": {
        "when": "ON_SUCCESSFUL_TRANSACTION"
      }
    },
    "options": {
      "customField": "PayPal custom field",
      "description": "Description for PayPal email reciept"
    }
  }
}`}
</VariablesCodeBlock>
<ResponseCodeBlock>
{`{
  "data": {
    "chargePayPalAccount": {
      "transaction": {
        "id": "dHJhbnNhY3Rpb25fbW1yM3NjcWY",
        "amount": {
          "value": "10.00",
          "currencyCode": "USD"
        },
        "paymentMethodSnapshot": {
          "captureId": "CAPTURE-b0156a96f070",
          "payerStatus": "VERIFIED"
        }
      }
    }
  },
  "extensions": {
    "requestId": "48692bbb-67ad-4c87-9830-f20e630a2245"
  }
}`}
</ResponseCodeBlock>
See the recurring transactions section below for more information on recurring transactions.

If you want to create a new payment method in the Vault upon a successful transaction, use the *vaultPaymentMethodAfterTransacting* option with value *ON_SUCCESSFUL_TRANSACTION*. If a *customerId* is not included, a new customer will be created. If you want to include a PayPal Billing Agreement with the vaulted payment method, use the [Checkout with Vault flow](https://developer.paypal.com/braintree/docs/guides/paypal/checkout-with-vault).
#### Currency support
The customer will be charged in the currency associated with the merchantAccountId passed in the [chargePayPalAccount](https://graphql.braintreepayments.com/reference/#Mutation--chargePayPalAccount) call. We support [all currencies that PayPal REST APIs support](https://developer.paypal.com/reference/currency-codes/#paypal-account-payments).

For details on accepting foreign currencies with PayPal, see our [PayPal account setup guide](https://developer.paypal.com/braintree/articles/guides/payment-methods/paypal/setup-guide#foreign-currencies).
#### Shipping addresses
If you’ve collected a shipping address, you will need to pass that along with the [chargePayPalAccount](https://graphql.braintreepayments.com/reference/#Mutation--chargePayPalAccount) call. For details on shipping address fields, see our [AddressInput object reference](https://graphql.braintreepayments.com/reference/#input_object--addressinput). PayPal validates the shipping address, so it must follow the [PayPal address conventions](https://developer.paypal.com/docs/api/payments/v1/#definition-shipping_address).

Below is an example call including shipping details:

<MutationCodeBlock>
{`mutation ChargePayPalAccount($input: ChargePayPalAccountInput!) { 
  chargePayPalAccount(input: $input) {
      transaction {
        id
        amount {
          value
          currencyCode
        }
        paymentMethodSnapshot {
          ...on PayPalTransactionDetails{
            captureId
            payerStatus
          }
        }
        shipping {
          shippingAmount
          shippingAddress {
            addressLine1
            addressLine2
            adminArea1
            adminArea2
            postalCode
            countryCode
          } 
        }
      }`}
</MutationCodeBlock>
<VariablesCodeBlock>
{`{
  "input": {
    "paymentMethodId": "fake-paypal-one-time-nonce",
    "transaction": {
      "amount": "10.00",
      "orderId": "orderId",
      "riskData": {
        "customerBrowser": "netscap_1.0",
        "customerIp": "8.8.8.8",
        "deviceData": "android_v15.0_z2"
      },
      "vaultPaymentMethodAfterTransacting": {
        "when": "ON_SUCCESSFUL_TRANSACTION"
      },
      "shipping": {
        "shippingAmount": "2.00",
        "shippingAddress": {
          "addressLine1": "222 W Merchandise Mart Plaza",
          "addressLine2": "STE 800",
          "adminArea1": "IL",
          "adminArea2": "Chicago",
          "postalCode": "60654",
          "countryCode": "USA"
        }
      }
    },
    "options": {
      "customField": "PayPal custom field",
      "description": "Description for PayPal email reciept"
    }
  }
}`}
</VariablesCodeBlock>
<ResponseCodeBlock>
{`{
  "data": {
    "chargePayPalAccount": {
      "transaction": {
        "id": "dHJhbnNhY3Rpb25fZ2NkODdtMmc",
        "amount": {
          "value": "10.00",
          "currencyCode": "USD"
        },
        "paymentMethodSnapshot": {
          "captureId": "CAPTURE-777329b115ce",
          "payerStatus": "VERIFIED"
        },
        "shipping": {
          "shippingAmount": "2.00",
          "shippingAddress": {
            "addressLine1": "222 W Merchandise Mart Plaza",
            "addressLine2": "STE 800",
            "adminArea1": "IL",
            "adminArea2": "Chicago",
            "postalCode": "60654",
            "countryCode": "US"
          }
        }
      }
    }
  },
  "extensions": {
    "requestId": "eb6f0aa3-9cdc-4ff5-bac3-1ccdda4ad496"
  }
}`}
</ResponseCodeBlock>

#### Seller Protection
By passing a shipping address, you may also be eligible for [PayPal Seller Protection](https://www.paypal.com/us/webapps/mpp/security/seller-protection). You can check the status of Seller Protection as follows:
<MutationCodeBlock>
{`mutation ChargePayPalAccount($input: ChargePayPalAccountInput!){ 
  chargePayPalAccount(input: $input) {
      transaction {
        id
        amount {
          value
          currencyCode
        }
        paymentMethodSnapshot {
          ...on PayPalTransactionDetails{
            captureId
            payerStatus
            sellerProtectionStatus
          }
        }
      }
  }
}`}
</MutationCodeBlock>
<VariablesCodeBlock>
{`{
  "input": {
    "paymentMethodId": "fake-paypal-one-time-nonce",
    "transaction": {
      "amount": "10.00",
      "orderId": "orderId",
      "riskData": {
        "customerBrowser": "netscap_1.0",
        "customerIp": "8.8.8.8",
        "deviceData": "android_v15.0_z2"
      },
      "vaultPaymentMethodAfterTransacting": {
        "when": "ON_SUCCESSFUL_TRANSACTION"
      }
    },
    "options": {
      "customField": "PayPal custom field",
      "description": "Description for PayPal email reciept"
    }
  }
}`}
</VariablesCodeBlock>
<ResponseCodeBlock>
{`{
  "data": {
    "chargePayPalAccount": {
      "transaction": {
        "id": "dHJhbnNhY3Rpb25fMDNjcTVrcjg",
        "amount": {
          "value": "10.00",
          "currencyCode": "USD"
        },
        "paymentMethodSnapshot": {
          "captureId": "CAPTURE-b5f937f18cbf",
          "payerStatus": "VERIFIED",
          "sellerProtectionStatus": "ELIGIBLE"
        }
      }
    }
  },
  "extensions": {
    "requestId": "afdeb2cb-12f0-47be-8e83-d65b546d546d"
  }
}`}
</ResponseCodeBlock>
### Settlement
Unlike most payment types that settle in batches, [we capture PayPal funds immediately when you submit each transaction for settlement](https://developer.paypal.com/braintree/articles/guides/payment-methods/paypal/processing#settlement).
#### Authorizing PayPal Purchases
In order to authorize a purchase on a PayPal account for a specified amount, use the [authorizePayPalAccount](https://graphql.braintreepayments.com/reference/#Mutation--authorizePayPalAccount) call. This can be useful when you need to complete a task before finalizing the transaction, like verifying you have the item in stock. An input very similar to [chargePayPalAccount](https://graphql.braintreepayments.com/reference/#Mutation--chargePayPalAccount) is used for this call.<MutationCodeBlock>
{`mutation AuthorizePayPalAccount($input: AuthorizePayPalAccountInput!){ 
  authorizePayPalAccount(input: $input) {
      transaction {
        id
        amount {
          value
          currencyCode
        }
        merchantAccountId
        paymentMethodSnapshot {
          ...on PayPalTransactionDetails{
            captureId
            payerStatus
          }
        }
      }
  }
}`}
</MutationCodeBlock>
<VariablesCodeBlock>
{`{
  "input": {
    "paymentMethodId": "fake-paypal-one-time-nonce",
    "transaction": {
      "amount": "10.00",
      "orderId": "orderId",
      "riskData": {
        "customerBrowser": "netscap_1.0",
        "customerIp": "8.8.8.8",
        "deviceData": "android_v15.0_z2"
      },
      "vaultPaymentMethodAfterTransacting": {
        "when": "ON_SUCCESSFUL_TRANSACTION"
      }
    },
    "options": {
      "customField": "PayPal custom field",
      "description": "Description for PayPal email reciept"
    }
  }
}`}
</VariablesCodeBlock>
<ResponseCodeBlock>
{`{
  "data": {
    "authorizePayPalAccount": {
      "transaction": {
        "id": "dHJhbnNhY3Rpb25fazA4a3QyZDc",
        "amount": {
          "value": "10.00",
          "currencyCode": "USD"
        },
        "merchantAccountId": "braintree",
        "paymentMethodSnapshot": {
          "captureId": null,
          "payerStatus": "VERIFIED"
        }
      }
    }
  },
  "extensions": {
    "requestId": "3f7462ed-0ac5-4afc-a199-a7b5663e11a3"
  }
}`}
</ResponseCodeBlock>
As you can see by the response, the [captureId](https://graphql.braintreepayments.com/reference/#object--paypaltransactiondetails) field is null because the account has yet to be charged.

#### Capturing greater than authorization amount
You can't settle more than the authorized amount unless your industry and processor support settlement adjustment (settling a certain percentage over the authorized amount); [contact us](https://developer.paypal.com/braintree/help/) for details. If your capture amount exceeds the allowable limit you will receive the respective [settlement response code](https://developer.paypal.com/braintree/docs/reference/general/processor-responses/settlement-responses).
#### Capturing multiple partial amounts against the same authorization
If you send physical goods to customers in multiple shipments, you can capture the total authorized amount across multiple partial settlements using [partialCaptureTransaction](https://graphql.braintreepayments.com/reference/#Mutation--partialCaptureTransaction).
### Recurring transactions
Use the [paymentInitiator](https://graphql.braintreepayments.com/reference/#enum--paymentinitiator) parameter with a value of recurring if the customer is not present when you create a PayPal transaction from their Vault record. Typical examples are a recurring subscription or an automatic top-up charge.
> NOTE
You won't need to do this if you're using our [recurring billing system](https://developer.paypal.com/braintree/docs/guides/recurring-billing/overview) – our logic creates subscription transactions with this parameter automatically. If you've built your own recurring logic, though, be sure your transaction sale calls include the recurring parameter.

<MutationCodeBlock>
{`mutation ChargePayPalAccount($input: ChargePayPalAccountInput!){ 
  chargePayPalAccount(input: $input) {
      transaction {
        id
        amount {
          value
          currencyCode
        }
        paymentMethodSnapshot {
          ...on PayPalTransactionDetails{
            captureId
            payerStatus
            sellerProtectionStatus
          }
        }
      }
  }
}`}
</MutationCodeBlock>
<VariablesCodeBlock>
{`{
  "input": {
    "paymentMethodId": "fake-paypal-one-time-nonce",
    "transaction": {
      "amount": "10.00",
      "paymentInitiator": "RECURRING"
    }
  }
}`}
</VariablesCodeBlock>
<ResponseCodeBlock>
{`{
  "data": {
    "chargePayPalAccount": {
      "transaction": {
        "id": "dHJhbnNhY3Rpb25fcm5kZDB2YTM",
        "amount": {
          "value": "10.00",
          "currencyCode": "USD"
        },
        "paymentMethodSnapshot": {
          "captureId": "CAPTURE-8a510f1189f0",
          "payerStatus": "VERIFIED",
          "sellerProtectionStatus": "ELIGIBLE"
        }
      }
    }
  },
  "extensions": {
    "requestId": "3a765f9e-4fde-4570-889a-2cdb16c3a231"
  }
}`}
</ResponseCodeBlock>
