One-time payments

You can set up one-time payments to process a buyer’s single-immediate payment through PayPal without storing the payment method for future use.

This guide explains how to use the Braintree GraphQL APIs to integrate PayPal one-time payments into your application. Use this integration for infrequent payments with high Average Order Value (AOV), typically physical-goods purchases.

For information on how to set up the checkout-with-vault flow to process one-time payments and store the buyer’s payment method, see Create PayPal one-time payment under Checkout-with-vault.

Workflow

The following diagram illustrates the process to create PayPal one-time payments flow.

Create PayPal one-time payment

In your server-side code, use the createPayPalOneTimePayment mutation, as shown in the following sample, to initiate a PayPal one-time payment. Pass the following input fields and their values:

• returnUrl: The URL to which the payer is redirected after payer authentication, to enter the PayPal payment details.
• cancelUrl: The URL to which the payer is redirected, if they cancel the one-time payment.
• payerEmail: The buyer’s email address (buyer identifier).
• lineItems: The items that the buyer purchases. The details passed to PayPal are presented to the buyer, in the post-purchase email sent to the buyer about their payment transaction and in the buyer's PayPal account Activity > Transactions > All transactions section.
• recipientEmail: The digital good recipient's email address. When customers purchase digital goods (such as gift cards, movies, and software) and check out with PayPal, you can ask the customers to input the digital good recipient's email address and pass it to PayPal, through this field.
• shippingAddress: The shipping address details that you can optionally collect from your customers. You can pass the shipping address details to PayPal to be eligible for PayPal seller protection.
• shippingOptions: The list of shipping options offered to the payer to ship or pick up their items.

On successful processing of createPayPalOneTimePayment, Braintree generates and sends an approval URL to your server. In your client-side code, use the approval URL to redirect the payer to PayPal to authenticate and authorize the payment.

API Reference: createPayPalOneTimePayment

mutation CreatePayPalOneTimePayment($input: CreatePayPalOneTimePaymentInput!) {
  createPayPalOneTimePayment(input: $input) {
    approvalUrl
    paymentId
  }
}

{ "input": { "merchantAccountId": "merchant_account_id", "amount": { "value": "100.00", "currencyCode": "AUD" }, "returnUrl": "https://merchant_domain_name/paypal/returnURL", "cancelUrl": "https://merchant_domain_name/paypal/cancelURL", "intent": "SALE", "email": "abc@gmail.com", "payerEmail": "payerEmail@gmail.com", "recipientEmail": "recipientEmail@gmail.com", "lineItems": [ { "name": "Test Customer", "quantity": 1, "unitAmount": "1", "type": "DEBIT", "description": "Authentic", "productCode": "asdf", "unitTaxAmount": "0.01", "url": "https://example.com", "imageUrl": "https://example.com/products/12345.png", "upc": { "upcType": "UPC_A", "upcCode": "042100005264" } } ], "offerPayLater": false, "paypalRiskCorrelationId": "", "paypalExperienceProfile": { "collectShippingAddress": true, "shippingAddressEditable": false, "brandName": "Empire Co.", "landingPageType": "DEFAULT", "locale": "en-US", "userAction": "COMMIT" }, "billingAgreementDescription": "My BA(d)", "shippingAddress": { "addressLine1": "123 George Street", "adminArea2": "Sydney", "adminArea1": "NSW", "postalCode": "2000", "countryCode": "AU", "phone": { "countryPhoneCode": "1", "phoneNumber": "1234567890" } }, "shippingOptions": [ { "amount": { "value": "1.00", "currencyCode": "USD" }, "id": "first", "selected": true, "description": "One Buck Chuck", "type": "SHIPPING" }, { "amount": { "value": "5.00", "currencyCode": "USD" }, "id": "second", "selected": false, "description": "Five Buck Chuck", "type": "SHIPPING" } ] } }

{ "data": { "createPayPalOneTimePayment": { "approvalUrl": "https://www.paypal.com/checkoutnow?token=EC-8ME9490685298683M", "paymentId": "PAYID-M577O5A8LE10108ST746620W" } }
}

Create transaction risk context

You can use the createTransactionRiskContext mutation to pass supplementary risk-related data to PayPal and create a transaction risk context that helps in risk management. On successful processing of createTransactionRiskContext PayPal returns a clientMetadataId and a paypalRiskCorrelationId.

Pass the clientMetadataId in the chargePaymentMethod mutation > riskData.deviceData.correlation_id.

mutation CreateTransactionRiskContext(
  $input: CreateTransactionRiskContextInput!
) {
  createTransactionRiskContext(input: $input) {
    clientMetadataId
    paypalRiskCorrelationId
  }
}

{ "input": { "riskContext": { "fields": [ { "name": "sender_account_id", "value": "xyz123" }, { "name": "txn_count_total", "value": "15987" } ] } } }

{ "data": { "createTransactionRiskContext": { "clientMetadataId": "01e59aa07d2187e13b1bf9cf42a45596", "paypalRiskCorrelationId": "01e59aa07d2187e13b1bf9cf42a45596" } } }

Send payers to PayPal to approve payment

From your server-side code, send the approvalURL returned in createPayPalOneTimePayment response to your client-side code. In your client-side code, include the logic to redirect payers to the PayPal site where they can authorize the payment. After the payer authorizes the payment on the PayPal site,

1. Payers are redirected to your returnUrl.
2. payment ID, payer ID, and payment token values are sent to the onApprove callback function in your server-side code.

Tokenize payment method

In your server-side code’s onApprove callback function, use the tokenizePayPalOneTimePayment mutation to convert the payment into a tokenized payment method. Use the payment ID, payer ID, and payment token values received, in the input payload of tokenizePayPalOneTimePayment.

On successful processing of tokenizePayPalOneTimePayment, Braintree/PayPal returns a paymentMethod.id that represents the payment method. You can use the id to charge or save the payment method.

API Reference: tokenizePayPalOneTimePayment

mutation TokenizePayPalOneTimePayment(
  $input: TokenizePayPalOneTimePaymentInput!
) {
  tokenizePayPalOneTimePayment(input: $input) {
    paymentMethod {
      id
      details {
        payerId
        selectedFinancingOption {
          term
          monthlyPayment {
            currencyCode
            value
          }
        }
      }
    }
  }
}

{ "input": { "merchantAccountId": "merchant_account_id", "paypalOneTimePayment": { "payerId": "MULBFTULQUMD8", "paymentId": "0CE93643D9475033S", "paymentToken": "EC-10V35072UM5141945" } } }

{ "data": { "tokenizePayPalOneTimePayment": { "paymentMethod": { "id": "tokencc_bj_hfqww2_rtyn7b_ggmjvs_6c9gd6_k9z", "details": { "payerId": "payer-id", "selectedFinancingOption": { "term": 12, "monthlyPayment": { "currencyCode": "GBP", "value": "10.0" } } } } } } }

Charge payment method

In your server-side code, use the chargePaymentMethod mutation to capture the payment and receive the transaction details.

API Reference: chargePaymentMethod

mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) {
  chargePaymentMethod(input: $input) {
    transaction {
      id
      status
    }
  }
}

{ "input": { "paymentMethodId": "tokencc_bj_hfqww2_rtyn7b_ggmjvs_6c9gd6_k9z", "transaction": { "amount": "10.00", "merchantAccountId": "merchant_account_id", "riskData": { "deviceData": "{\"correlation_id\": \"01e59aa07d2187e13b1bf9cf42a45596\"}" } } } }

{ "data": { "chargePaymentMethod": { "transaction": { "id": "dHJhbnNhY3Rpb25fZzVmNDY2djE", "status": "SETTLING" } } } }