Checkout-with-vault

You can set up checkout-with-vault payments to process a payer’s immediate payment through PayPal and save the payment method for future transactions.

This guide explains how to use the Braintree GraphQL APIs to integrate PayPal checkout-with-vault payments into your application.

The checkout-with-vault integration is similar to the one-time payments integration. The primary difference is that you must include the requestBillingAgreement parameter in the createPayPalOneTimePayment mutation.

Workflow

The following diagram illustrates the process to create checkout-with-vault 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.
• requestBillingAgreement: Enables the vault flow when set to true, allowing you to store the billing agreement for future use.
• 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@example.com", "payerEmail": "payerEmail@example.com", "recipientEmail": "recipientEmail@example.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": "risk-correlation-id", "paypalExperienceProfile": { "collectShippingAddress": true, "shippingAddressEditable": false, "brandName": "Empire Co.", "landingPageType": "DEFAULT", "locale": "en-US", "userAction": "COMMIT" }, "billingAgreementDescription": "My BA(d)", "requestBillingAgreement": true, "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.sandbox.paypal.com/checkoutnow?nolegacy=1&token=EC-9AU84436HU477610R", "paymentId": "PAYID-M6TF2FA0Y465462BX686072Y" } } }

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 PayPal account

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

API Reference: chargePaymentMethod

mutation ChargePayPalAccount($input: ChargePayPalAccountInput!) {
  chargePayPalAccount(input: $input) {
    transaction {
      id
      paymentMethod {
        id
      }
      billingAgreementWithPurchasePaymentMethod {
        id
      }
    }
  }
}

{ "input": { "clientMutationId": "abc123", "paymentMethodId": "tokencc_bj_hfqww2_rtyn7b_ggmjvs_6c9gd6_k9z", "options": { "customField": "a custom field", "description": "a description", "payee": { "email": "payee@example.com" } }, "transaction": { "amount": "10.00" } } }

{ "data": { "chargePayPalAccount": { "transaction": { "id": "dHJhbnNhY3Rpb25fODUyYzN2NWE", "paymentMethod": null }, "billingAgreementWithPurchasePaymentMethod": { "id": "cGF5bWVudG1ldGhvZF9wcF9FQy0wMFg4ODAwNUwyMzI2MTA0SA" } } } }