Creating transactions

Once the customer has successfully authenticated with PayPal, include the payment_method_nonce parameter in the call on your server. Below includes an example call with relevant PayPal parameters:

result =
  :amount => "10.00",
  :payment_method_nonce => params[:payment_method_nonce],
  :order_id => "Mapped to PayPal Invoice Number",
  :options => {
    :paypal => {
      :custom_field => "PayPal custom field",
      :description => "Description for PayPal email receipt",
if result.success?
  "Success ID: #{}"

If you want to create a new payment method in the Vault upon a successful transaction, use the options.store_in_vault_on_success option. If a customer_id is not included, a new customer will be created.

Using device data

If the PayPal transaction was initiated from a Vault record and is not a recurring transaction, include the collected client device data via the top-level device_data parameter. Doing so will help reduce decline rates.

Here's an example of passing device data with the transaction:

result =
  :amount => "1000.00",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :submit_for_settlement => true
  :device_data => params[:device_data]

See the recurring transactions section below for more information on recurring transactions.

Currency support

The customer will be charged in the currency associated with the merchant_account_id passed in the call. We support all currencies that PayPal REST APIs support.

For details on accepting foreign currencies with PayPal, see our PayPal account setup guide.

Shipping addresses

If you’ve collected a shipping address, you will need to pass that along with the call. The following fields are required when passing a shipping address for PayPal transactions:

For details on how to add a shipping address when creating a transaction, see the transaction reference full example. PayPal validates the shipping address, so it must follow the PayPal address conventions.

When creating a transaction using a PayPal account stored in the Vault, see the example of using stored addresses as well as the billing_address_id and shipping_address_id parameters.

Seller Protection

By passing a shipping address, you may also be eligible for PayPal Seller Protection. You can check the status of Seller Protection as follows:

transaction = Braintree::Transaction.find("the_transaction_id")



Unlike most payment types that settle in batches, we capture PayPal funds immediately when you submit each transaction for settlement.

Capturing greater than authorization amount

You cannot settle more than the authorized amount unless your industry and processor support settlement adjustment (settling a certain percentage over the authorized amount); contact our Accounts team for details. If your capture amount exceeds the allowable limit you will receive the respective settlement response code.

Recurring transactions

Use the recurring parameter 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.


You won't need to do this if you're using our recurring billing system – 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.

result =
  :amount => "1000.00",
  :payment_method_token => "payment_method_token",
  :recurring => true,

See also

Next: Testing and Go Live →

Still have questions?

If you can’t find an answer, contact our Support team.