PayPal

Transaction management

This guide explains how to manage transactions with PayPal. It covers adding shipping details, checking for seller protection eligibility, handling authorizations, and managing settlement flows.

The code provided in the guide is for testing in the sandbox. After successful testing, ensure to review the API reference document to adjust the code settings for your live environment.

Currency supportAnchorIcon

The transaction currency is determined by the merchantAccountId you specify in the chargePayPalAccount or authorizePayPalAccount mutation. Braintree supports all currencies available through the PayPal REST APIs.

To learn more about accepting multiple currencies with PayPal, see the PayPal account setup guide.

Pass shipping addressAnchorIcon

If you collect a shipping address from the payer, ensure to include it in the chargePayPalAccount mutation. Providing the shipping address helps you obtain potential seller protection.

For the required fields for shipping addresses, see the AddressInput object reference. Keep in mind that PayPal validates the shipping address, so the information you provide must follow PayPal's address conventions.

API reference: chargePayPalAccount

  1. Mutation
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
        }
      }
    }
  }
}
  1. Variables
{ "input": { "paymentMethodId": "token_id", "transaction": { "amount": "10.00", "orderId": "order_id", "riskData": { "customerBrowser": "web_browser_type", "customerIp": "127.0.0.1", "deviceData": "device_type" }, "vaultPaymentMethodAfterTransacting": { "when": "ON_SUCCESSFUL_TRANSACTION" }, "shipping": { "shippingAmount": "2.00", "shippingAddress": { "addressLine1": "123 Main St", "addressLine2": "STE 800", "adminArea1": "CA", "adminArea2": "Anytown", "postalCode": "12345", "countryCode": "US" } } }, "options": { "customField": "PayPal custom field", "description": "Description for PayPal email reciept" } } }
  1. Response
{ "data": { "chargePayPalAccount": { "transaction": { "id": "transaction_id", "amount": { "value": "10.00", "currencyCode": "USD" }, "paymentMethodSnapshot": { "captureId": "capture_id", "payerStatus": "VERIFIED" }, "shipping": { "shippingAmount": "2.00", "shippingAddress": { "addressLine1": "123 Main St", "addressLine2": "STE 800", "adminArea1": "CA", "adminArea2": "Anytown", "postalCode": "12345", "countryCode": "US" } } } } }, "extensions": { "requestId": "request_id" } }

Verify seller-protection statusAnchorIcon

Providing a shipping address might make you eligible for PayPal seller protection. To check the status of seller protection for a specific transaction, call the chargePayPalAccount endpoint and include the sellerProtectionStatus field in the paymentMethodSnapshot.

API reference: chargePayPalAccount

  1. Mutation
mutation ChargePayPalAccount($input: ChargePayPalAccountInput!) {
  chargePayPalAccount(input: $input) {
    transaction {
      id
      amount {
        value
        currencyCode
      }
      paymentMethodSnapshot {
        ... on PayPalTransactionDetails {
          captureId
          payerStatus
          sellerProtectionStatus
        }
      }
    }
  }
}
  1. Variables
{ "input": { "paymentMethodId": "token_id", "transaction": { "amount": "10.00", "orderId": "order_id", "riskData": { "customerBrowser": "web_browser_type", "customerIp": "127.0.0.1", "deviceData": "device_type" }, "vaultPaymentMethodAfterTransacting": { "when": "ON_SUCCESSFUL_TRANSACTION" } }, "options": { "customField": "PayPal custom field", "description": "Description for PayPal email reciept" } } }
  1. Response
{ "data": { "chargePayPalAccount": { "transaction": { "id": "transaction_id", "amount": { "value": "10.00", "currencyCode": "USD" }, "paymentMethodSnapshot": { "captureId": "capture_id", "payerStatus": "VERIFIED", "sellerProtectionStatus": "ELIGIBLE" } } } }, "extensions": { "requestId": "request_id" } }

Manage settlementAnchorIcon

PayPal transactions are captured and settled immediately after a successful chargePayPalAccount call. This differs from most payment types, which typically settle in batches.

Handle authorized PayPal purchasesAnchorIcon

You can use the authorizePayPalAccount mutation to authorize a purchase on a PayPal account for a specific amount without immediately capturing the funds. This is useful in scenarios where you must verify inventory or complete another task before finalizing the transaction. The input for authorizePayPalAccount is similar to chargePayPalAccount.

API reference: authorizePayPalAccount

  1. Mutation
mutation AuthorizePayPalAccount($input: AuthorizePayPalAccountInput!) {
  authorizePayPalAccount(input: $input) {
    transaction {
      id
      amount {
        value
        currencyCode
      }
      merchantAccountId
      paymentMethodSnapshot {
        ... on PayPalTransactionDetails {
          captureId
          payerStatus
        }
      }
    }
  }
}
  1. Variables
{ "input": { "paymentMethodId": "token_id", "transaction": { "amount": "10.00", "orderId": "order_id", "riskData": { "customerBrowser": "web_browser_type", "customerIp": "127.0.0.1", "deviceData": "device_type" }, "vaultPaymentMethodAfterTransacting": { "when": "ON_SUCCESSFUL_TRANSACTION" } }, "options": { "customField": "PayPal custom field", "description": "Description for PayPal email reciept" } } }
  1. Response
{ "data": { "authorizePayPalAccount": { "transaction": { "id": "transaction_id", "amount": { "value": "10.00", "currencyCode": "USD" }, "merchantAccountId": "merchant_id", "paymentMethodSnapshot": { "captureId": null, "payerStatus": "VERIFIED" } } } }, "extensions": { "requestId": "request_id" } }

Note
As the response shows, the captureId field is null because the account has not been charged yet.

Capture greater than authorized amountAnchorIcon

It is generally not possible to capture more than the authorized amount. However, if your industry and processor support settlement adjustments, you might be able to capture an amount over the authorized limit. Contact us for details about settlement adjustment.

Capture multiple partial amounts against an authorizationAnchorIcon

If you fulfill orders with multiple shipments, you can capture the total authorized amount across multiple partial captures by using the partialCaptureTransaction mutation. This allows you to incrementally charge the payer's account as items are shipped.