PayPal via Braintree

Accept PayPal payments with Braintree as the payment service provider (PSP). The customer approves the payment on PayPal and returns to your site, and Payrails completes the payment with Braintree.

Supported workflows

Before you begin

Complete these steps before you send your first PayPal payment through Braintree:

Set up a Braintree integration in your workspace. Follow the Braintree integration setup guide if you don’t have one yet.
In the Braintree Control Panel, link your PayPal business account to your Braintree account.
Add the Payrails domain api.payrails.io to the PayPal domain names in Braintree, so that PayPal can return the customer to Payrails.
In your Braintree integration in Payrails, set the Merchant Account ID to the Braintree merchant account in the currency of your PayPal payments. To accept PayPal in more than one currency, create one Braintree integration per merchant account.
To save PayPal accounts for later payments, ask PayPal to enable billing agreements (reference transactions) on your PayPal account.
In the Payrails Portal, go to Settings → Integrations, open your Braintree integration, select PayPal under Payment methods, and save.
Add PayPal as a payment option in your workflow.

Request fields for Braintree

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to the PSP when you include them.

Field	Status	Description
`amount`	Required	Sent to PayPal as the payment amount and currency. Use the currency of your Braintree merchant account. An amount of `0` saves the PayPal account without charging it.
`meta.order.lines`	Optional	Sent as the line items. When you send lines, include `name`, `quantity` and `unitPrice` on each one.
`meta.order.reference`	Optional	Sent as the order ID. Use a new value for every payment: PayPal rejects an order ID it has seen before.
`meta.order.description`	Optional	Sent as the billing agreement description when you save the PayPal account.
`meta.order.deliveryAddress`	Optional	Sent as the shipping address. Include `country.code` and `street`.
`meta.order.softDescriptor`	Optional	Sent as the descriptor name.
`meta.order.totalTax`, `meta.order.totalDiscount`	Optional	Sent as the tax and discount amounts.
`meta.customer.email`	Optional	Sent as the payer email.
`meta.customer.phone`	Optional	Sent as the descriptor phone.
`meta.clientContext.ipAddress`, `userAgent`, `deviceFingerprint`	Optional	Sent as risk data for PayPal fraud checks.
`instrument.storeInstrument`	Optional	Saves the PayPal account for later payments, including merchant-initiated transactions (MIT).
`instrument.data.paymentToken`	Optional	A PayPal nonce from Braintree’s client SDK. When you send it, Payrails charges it directly, with no redirect.

Authorize a PayPal payment

Call authorize a payment with payPal as the paymentMethodCode.

Authorize request

{
  "amount": {
    "value": "100.00",
    "currency": "USD"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "payPal",
      "amount": {
        "value": "100.00",
        "currency": "USD"
      },
      "storeInstrument": true
    }
  ],
  "meta": {
    "customer": {
      "email": "jane.doe@example.com"
    },
    "order": {
      "reference": "order-1234",
      "description": "Monthly subscription"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

The response includes a redirect to the PayPal approval page. After the customer approves the payment, PayPal returns them to Payrails, and Payrails charges or authorizes the payment with Braintree, depending on your capture mode. If the customer cancels on PayPal, the payment is canceled. Confirm the result through webhook notifications or the execution status before you fulfill the order.

How Braintree handles PayPal

With instant capture, Payrails charges the payment when the customer returns. With manual capture, Payrails authorizes it, and you capture it later in full or in parts.
You can refund the full amount or part of it, and cancel an authorized payment.
When you save the PayPal account, Braintree stores it as a billing agreement and Payrails returns it as a payment instrument. Use it for later subscription or unscheduled payments.
Braintree doesn’t send payment status webhooks for PayPal, so Payrails gets the result when the customer returns from PayPal.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Supported workflows

Before you begin

Request fields for Braintree

Authorize a PayPal payment

How Braintree handles PayPal

​Supported workflows

​Before you begin

​Request fields for Braintree

​Authorize a PayPal payment

​How Braintree handles PayPal

Supported workflows

Before you begin

Request fields for Braintree

Authorize a PayPal payment

How Braintree handles PayPal