Server-Side Implementation
Your integration may be impacted by upcoming certificate changes. Visit our best practices guide to learn more.
Click here to view the server-side implementation using GraphQL.
Creating transactions
paymentMethodNonce
parameter in the Transaction: Sale
call on your server.Updating PayPal Payment Resource After Buyer Approval
In certain edge cases, merchants may need to update some transaction parameters, such as the total amount, after the buyer has approved the payment in the PayPal checkout window. In such cases, it is essential to include updated line items in the server-side call to ensure the final amount reflects the correct total.
These updates can include modifications to line items, currency, custom fields, or any other supported parameter.
To complete an update, use the PayPalPaymentResource.update() method on the server side after tokenization of the payment resource and before calling Customer.create() to vault the payment method.
- php
class PayPalPaymentResourceTest extends Setup
{
public function testUpdateIsSuccessful()
{
$nonce = Braintree\Test\Nonces::$paypalOneTimePayment;
$result = Braintree\PayPalPaymentResource::update([
'amount' => '55.00',
'amountBreakdown' => [
'discount' => '15.00',
'handling' => '0.00',
'insurance' => '5.00',
'itemTotal' => '45.00',
'shipping' => '10.00',
'shippingDiscount' => '0.00',
'taxTotal' => '10.00',
],
'currencyIsoCode' => 'USD',
'customField' => '0437',
'description' => 'This is a test',
'lineItems' => [
[
'description' => 'Shoes',
'imageUrl' => 'https://example.com/products/23434/pic.png',
'kind' => Braintree\TransactionLineItem::DEBIT,
'name' => 'Name #1',
'productCode' => '23434',
'quantity' => '1',
'totalAmount' => '45.00',
'unitAmount' => '45.00',
'unitTaxAmount' => '10.00',
'url' => 'https://example.com/products/23434',
],
],
'orderId' => 'order-123456789',
'payeeEmail' => 'bt_buyer_us@paypal.com',
'paymentMethodNonce' => $nonce,
'shipping' => [
'firstName' => 'John',
'lastName' => 'Doe',
'streetAddress' => '123 Division Street',
'extendedAddress' => 'Apt. #1',
'locality' => 'Chicago',
'region' => 'IL',
'postalCode' => '60618',
'countryName' => 'United States',
'countryCodeAlpha2' => 'US',
'countryCodeAlpha3' => 'USA',
'countryCodeNumeric' => '484',
'internationalPhone' => [
'countryCode' => '1',
'nationalNumber' => '4081111111',
],
],
'shippingOptions' => [
[
'amount' => '10.00',
'id' => 'option1',
'label' => 'fast',
'selected' => true,
'type' => 'SHIPPING',
],
],
]);
$this->assertTrue($result->success);
$this->assertNotNull($result->paymentMethodNonce);
$this->assertNotNull($result->paymentMethodNonce->nonce);
}
Using device data
Below includes an example call with relevant PayPal parameters and device data:
- PHP
$result = $gateway->transaction()->sale([
'amount' => $_POST['amount'],
'paymentMethodNonce' => $_POST['payment_method_nonce'],
'deviceData' => $_POST['device_data'],
'orderId' => $_POST["Mapped to PayPal Invoice Number"],
'options' => [
'submitForSettlement' => True,
'paypal' => [
'customField' => $_POST["PayPal custom field"],
'description' => $_POST["Description for PayPal email receipt"],
],
],
]);
if ($result->success) {
print_r("Success ID: " . $result->transaction->id);
} else {
print_r("Error Message: " . $result->message);
}
See the recurring transactions section below for more information on recurring transactions.
options-storeInVaultOnSuccess
option. 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
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
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.
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:
- PHP
$transaction = $gateway->transaction()->find('the_transaction_id');
$transaction->paypalDetails->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
Transaction: Submit For Partial Settlement
.Recurring transactions
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.- PHP
$result = $gateway->transaction()->sale([
'amount' => "1000.00",
'paymentMethodToken' => "payment_method_token",
'transactionSource' => "recurring",
'options' => [
'submitForSettlement' => True
],
]);