PayPal

Creating TransactionsAnchorIcon

After the customer has authenticated with PayPal, include the paymentMethodId parameter in the chargePayPalAccount call on your server.

Using device dataAnchorIcon

If the PayPal transaction was initiated from a Vault record and is not a recurring transaction, collect device data from the client and include the collected client device data via the deviceData parameter inside riskData. Doing so will help reduce decline rates.

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

  1. Mutation
mutation ChargePayPalAccount($input: ChargePayPalAccountInput!) {
  chargePayPalAccount(input: $input) {
    transaction {
      id
      amount {
        value
        currencyCode
      }
      paymentMethodSnapshot {
        ... on PayPalTransactionDetails {
          captureId
          payerStatus
        }
      }
    }
  }
}
  1. Variables
{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "10.00",
      "orderId": "id_of_order",
      "riskData": {
        "customerBrowser": "web_browser_type",
        "customerIp": "ip_address",
        "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": "id_of_transaction",
        "amount": { "value": "10.00", "currencyCode": "USD" },
        "paymentMethodSnapshot": {
          "captureId": "id_of_capture",
          "payerStatus": "VERIFIED"
        }
      }
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}
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 a value of 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.

Currency supportAnchorIcon

The customer will be charged in the currency associated with the merchantAccountId passed in the chargePayPalAccount 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 addressesAnchorIcon

If you’ve collected a shipping address, you will need to pass that along with the chargePayPalAccount call. For details on shipping address fields, see our AddressInput object reference. PayPal validates the shipping address, so it must follow the PayPal address conventions.

Following is an example call including shipping details:

  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": "id_of_payment_method",
    "transaction": {
      "amount": "10.00",
      "orderId": "id_of_order",
      "riskData": {
        "customerBrowser": "web_browser_type",
        "customerIp": "ip_address",
        "deviceData": "device_type"
      },
      "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"
    }
  }
}
  1. Response
{
  "data": {
    "chargePayPalAccount": {
      "transaction": {
        "id": "id_of_transaction",
        "amount": { "value": "10.00", "currencyCode": "USD" },
        "paymentMethodSnapshot": {
          "captureId": "id_of_capture",
          "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": "a-uuid-for-the-request" }
}

Seller ProtectionAnchorIcon

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

  1. Mutation
mutation ChargePayPalAccount($input: ChargePayPalAccountInput!) {
  chargePayPalAccount(input: $input) {
    transaction {
      id
      amount {
        value
        currencyCode
      }
      paymentMethodSnapshot {
        ... on PayPalTransactionDetails {
          captureId
          payerStatus
          sellerProtectionStatus
        }
      }
    }
  }
}
  1. Variables
{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "10.00",
      "orderId": "id_of_order",
      "riskData": {
        "customerBrowser": "web_browser_type",
        "customerIp": "ip_address",
        "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": "id_of_transaction",
        "amount": { "value": "10.00", "currencyCode": "USD" },
        "paymentMethodSnapshot": {
          "captureId": "id_of_capture",
          "payerStatus": "VERIFIED",
          "sellerProtectionStatus": "ELIGIBLE"
        }
      }
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}

SettlementAnchorIcon

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

Authorizing PayPal PurchasesAnchorIcon

In order to authorize a purchase on a PayPal account for a specified amount, use the authorizePayPalAccount call. This can be useful when you need to complete a task before finalizing the transaction, like verifying that you have the item in stock. An input very similar to chargePayPalAccount is used for this call.

  1. Mutation
mutation AuthorizePayPalAccount($input: AuthorizePayPalAccountInput!) {
  authorizePayPalAccount(input: $input) {
    transaction {
      id
      amount {
        value
        currencyCode
      }
      merchantAccountId
      paymentMethodSnapshot {
        ... on PayPalTransactionDetails {
          captureId
          payerStatus
        }
      }
    }
  }
}
  1. Variables
{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "10.00",
      "orderId": "id_of_order",
      "riskData": {
        "customerBrowser": "web_browser_type",
        "customerIp": "ip_address",
        "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": "id_of_transaction",
        "amount": { "value": "10.00", "currencyCode": "USD" },
        "merchantAccountId": "id_of_merchant_account",
        "paymentMethodSnapshot": {
          "captureId": null,
          "payerStatus": "VERIFIED"
        }
      }
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}

As you can see by the response, the captureId field is null because the account has yet to be charged.

Capturing greater than the authorization amountAnchorIcon

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 for details. If your capture amount exceeds the allowable limit, you will receive the respective settlement response code.

Capturing multiple partial amounts against the same authorizationAnchorIcon

If you send physical goods to customers in multiple shipments, you can capture the total authorized amount across multiple partial settlements using partialCaptureTransaction.

Recurring transactionsAnchorIcon

Use the 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 – our logic automatically creates subscription transactions with this parameter. If you've built your own recurring logic, be sure your transaction sale calls include the recurring parameter.
  1. Mutation
mutation ChargePayPalAccount($input: ChargePayPalAccountInput!) {
  chargePayPalAccount(input: $input) {
    transaction {
      id
      amount {
        value
        currencyCode
      }
      paymentMethodSnapshot {
        ... on PayPalTransactionDetails {
          captureId
          payerStatus
          sellerProtectionStatus
        }
      }
    }
  }
}
  1. Variables
{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": { "amount": "10.00", "paymentInitiator": "RECURRING" }
  }
}
  1. Response
{
  "data": {
    "chargePayPalAccount": {
      "transaction": {
        "id": "id_of_transaction",
        "amount": { "value": "10.00", "currencyCode": "USD" },
        "paymentMethodSnapshot": {
          "captureId": "id_of_capture",
          "payerStatus": "VERIFIED",
          "sellerProtectionStatus": "ELIGIBLE"
        }
      }
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}