Creating transactions
Once the customer has successfully authenticated with PayPal, include the paymentMethodNonce parameter in the Transaction: Sale 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 top-level deviceData
parameter. Doing so will help reduce decline rates.
Below includes an example call with relevant PayPal parameters and device data:
const saleRequest = {
amount: req.body.amount,
paymentMethodNonce: req.body.nonce,
deviceData: req.body.device_data,
orderId: "Mapped to PayPal Invoice Number",
options: {
submitForSettlement: true,
paypal: {
customField: "PayPal custom field",
description: "Description for PayPal email receipt",
},
}
};
gateway.transaction.sale(saleRequest, (err, result) => {
if (err) {
console.log("Error: " + err);
} else if (result.success) {
console.log("Success! Transaction ID: " + result.transaction.id);
} else {
console.log("Error: " + result.message);
}
});
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 options.storeInVaultOnSuccess option. If a customerId
is not included, a new customer will be created.
Currency support
The customer will be charged in the currency associated with the merchantAccountId
passed in the Transaction: Sale 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 Transaction: Sale call. The following fields are required when passing a shipping address for PayPal transactions:
- shipping.firstName
- shipping.lastName
- shipping.streetAddress
- shipping.locality
- shipping.postalCode
- shipping.region
- shipping.countryCodeAlpha2
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 billingAddressId and shippingAddressId 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:
gateway.transaction.find("theTransactionId", (err, transaction) => {
transaction.paypalAccount.sellerProtectionStatus;
// "ELIGIBLE"
});
Settlement
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 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 Transaction: Submit For Partial Settlement.
Recurring transactions
Use the transactionSource 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.
gateway.transaction.sale({
amount: "1000.00",
paymentMethodToken: "theToken",
transactionSource: "recurring",
options: {
submitForSettlement: true,
}
}, function(err, result) { });