Skip to main content

PayPal

Creating Transactions

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

Using device data

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:

mutation

mutation ChargePayPalAccount($input: ChargePayPalAccountInput!){ 
  chargePayPalAccount(input: $input) {
      transaction {
        id
        amount {
          value
          currencyCode
        }
        paymentMethodSnapshot {
          ...on PayPalTransactionDetails{
            captureId
            payerStatus
          }
        }
      }
  }
}

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"
    }
  }
}

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 support

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 addresses

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:

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
          } 
        }
      }

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"
    }
  }
}

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 Protection

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

mutation

mutation ChargePayPalAccount($input: ChargePayPalAccountInput!) { 
  chargePayPalAccount(input: $input) { 
    transaction { 
      id 
      amount { 
        value 
        currencyCode 
      } 
      paymentMethodSnapshot { 
        ...on PayPalTransactionDetails
        { 
          captureId 
          payerStatus 
          sellerProtectionStatus 
        } 
      } 
    } 
  } 
}

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" 
    } 
  } 
}

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"
  }
}

Settlement

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

Authorizing PayPal Purchases

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.

mutation

mutation AuthorizePayPalAccount($input: AuthorizePayPalAccountInput!) { 
  authorizePayPalAccount(input: $input) { 
    transaction { 
      id 
      amount { 
        value 
        currencyCode 
      } 
      merchantAccountId 
      paymentMethodSnapshot { 
        ...on PayPalTransactionDetails { 
          captureId 
          payerStatus 
        } 
      } 
    } 
  } 
}

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" 
    } 
  } 
}

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 amount

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 authorization

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

Recurring transactions

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.

mutation

mutation ChargePayPalAccount($input: ChargePayPalAccountInput!){ 
  chargePayPalAccount(input: $input) {
      transaction {
        id
        amount {
          value
          currencyCode
        }
        paymentMethodSnapshot {
          ...on PayPalTransactionDetails{
            captureId
            payerStatus
            sellerProtectionStatus
          }
        }
      }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "10.00",
      "paymentInitiator": "RECURRING"
    }
  }
}

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"
  }
}