How to Vault a Limited Use PayPal Account

This guide is intended for merchants using PayPal Order. Merchants can vault PayPal accounts for use in a PayPal Order using the vaultLimitedUsePayPalAccount mutation. Once vaulted, a limited use PayPal account can be reused to capture funds up to the amount specified in the Order (plus a tolerance limit) within 90 days.

Obtain a Single-Use Payment Method (Nonce)

Follow this guide to obtain a single-use payment method ID in your client with an intent of order.

Vault the Limited Use PayPal Account

Once you have a single-use payment method ID from your client you can pass it to the vaultLimitedUsePayPalAccount GraphQL mutation to create a payment method compatible with PayPal Order. This mutation allows you to manage the transactions processed against your new PayPal Order using the options input field:

  • amount: The total amount of the order. This is the limit of how much may be captured on the resulting payment method.
  • orderId: Use this field to pass an order id for the PayPal Order. On PayPal reporting, this field maps to the PayPal invoice number. PayPal invoice numbers must be unique in your PayPal business account.
  • customField: Use this field to pass information directly to PayPal via the API for your own tracking purposes. Customers do not see this value, but you can see it in reports from your PayPal console.
  • description: Description of the transaction that is displayed to customers in PayPal email receipts.
  • shippingAddress: Shipping address for the PayPal Order. See the documentation for more details.

You may also specify a customer by passing customerId to this mutation. For more information about linking payment methods to customers, see Vaulting Payment Methods.

Mutation

mutation ExampleVault($input: VaultLimitedUsePayPalAccountInput!) {
  vaultLimitedUsePayPalAccount(input: $input) {
    paymentMethod {
      id
    }
  }
}

Variables

{
  "input": {
    "paymentMethodId": "<single-use-payment-method-id-from-client>",
    "options": {
      "amount": "112.34",
      "customField": "custom field",
      "description": "a description",
      "orderId": "new order id",
      "shippingAddress": {
        "company": "Some Company",
        "streetAddress": "123 Fake St.",
        "extendedAddress": "6th Floor",
        "firstName": "Dale",
        "lastName": "Cooper",
        "locality": "San Francisco",
        "region": "CA",
        "postalCode": "94107",
        "countryCode": "USA"
      }
    }
  }
}

Full Request

curl \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Basic PUBLICKEY:PRIVATEKEY_BASE64ENCODED' \
 -H 'Braintree-Version: 2020-01-01' \
 -X POST https://payments.sandbox.braintree-api.com/graphql \
 -d '{
  "query": "mutation ExampleVault($input: VaultLimitedUsePayPalAccountInput!) {
    vaultLimitedUsePayPalAccount(input: $input) {
      paymentMethod {
        id
      }
    }
  }",
  "variables": {
    "input": {
      "paymentMethodId": "<single-use-payment-method-id-from-client>",
      "options": {
        "amount": "112.34",
        "customField": "custom field",
        "description": "a description",
        "orderId": "new order id",
        "shippingAddress": {
          "company": "Some Company",
          "streetAddress": "123 Fake St.",
          "extendedAddress": "6th Floor",
          "firstName": "Dale",
          "lastName": "Cooper",
          "locality": "San Francisco",
          "region": "CA",
          "postalCode": "94107",
          "countryCode": "USA"
        }
      }
    }
  }
}'

Response

A successful response will contain an ID representing a limited use PayPal account in the data object:

{
  "data": {
    "vaultLimitedUsePayPalAccount": {
      "paymentMethod": {
        "id": "<multi-use-payment-method-id>"
      }
    }
  }
}

This ID can be used to make transactions within 90 days of the creation of the order. You may capture up to the amount of the PayPal Order, plus a tolerance limit. See Creating Transactions for more information.