Skip to main content
Welcome to the preview portal — This is an early release of the new Doc Hub experience, with more content coming soon.

PayPal


Digital wallets are secure applications or services that enable users to electronically store payment details, such as debit or credit cards.

For online transactions, the wallet securely passes a payment token to the merchant or payment processor. You do not handle sensitive customer data directly. This reduces friction at checkout, improves conversion rates, and enhances security through built-in authentication and tokenization.

Wallets are best suited for one-time online purchases and express checkout experiences. Support for subscriptions and recurring payments varies by wallet, so you must confirm compatibility if future charges or merchant-initiated transactions are required.

This table describes the available digital wallet payment methods:

Payment MethodCapture Context allowedPaymentTypesCapture Context completeMandate.typeSeparate Capture?Payment ConfirmationCustomer Country (Country Code)Customer ISO Currency Code
PayPalPAYPALAUTH or PREFER_AUTHYesDelayedGlobalAUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, NOK, NZD, PLN, SEK, SGD, and USD
PayPalPAYPALCAPTURENoImmediateGlobalAUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, NOK, NZD, PLN, SEK, SGD, and USD

PayPal

PayPal is a secure and convenient payment service that your customers can use to make payments without directly using their bank accounts or credit cards. PayPal gives your customers the option to pay in installments over time with PayPal Pay Later while giving you the full payment immediately. These installments are available:

  • Pay in 3: pay in three installments. Available in the UK.
  • Pay in 4: pay in four installments. Available in the US.
  • Pay Monthly: pay in monthly recurring installments.

Board Merchants with PayPal

Before you can accept PayPal payments, your account must be boarded for PayPal. Portfolio users can board and enable their merchants for PayPal using the API or the Business Center:

Opt in to PayPal on Unified Checkout

Follow these steps to opt in to the PayPal payment method in Unified Checkout:

  1. Add PayPal to your integration by adding PAYPAL to the allowedPaymentTypes field within the capture context request.

  2. Set the completeMandate.type field value to AUTH, CAPTURE, or PREFER_AUTH.

    You can perform a sale and capture the funds immediately if you include the completeMandate.type field in the capture context request and set the value to CAPTURE.

    You can capture the funds later if you include the completeMandate.type field in the capture context request and set the value to AUTH. When you capture the funds later, you must perform a capture using the payments API. See Captures.

    If you accept more than one payment type and must perform an authorization where funds are collected at a later time, set the completeMandate.type field to PREFER_AUTH. You must perform a capture using the payments API when an authorization is performed. A capture is performed automatically if an authorization is not allowed by the payment type.

  3. Include these required fields in the capture context request:

    • data.orderInformation.amountDetails.currency
    • data.orderInformation.amountDetails.totalAmount
    • data.orderInformation.lineItems[].productName
    • data.orderInformation.lineItems[].quantity
    • data.orderInformation.lineItems[].unitPrice
  4. Include these optional fields in the capture context request:

    • buyerInformation.dateOfBirth
    • buyerInformation.language
    • buyerInformation.personalIdentification[].id
    • buyerInformation.personalIdentification[].type
    • clientReferenceInformation.reconciliationId
    • merchantInformation.merchantDescriptor.name: this field affects the name that customers see on their card statement. If the merchant is Candy Shop and passes this as their name, the customer sees PAYPAL * Candy Shop on their bank statement.
    • data.orderInformation.amountDetails.taxAmount
    • data.orderInformation.amountDetails.taxDetails.taxId
    • data.orderInformation.amountDetails.taxDetails.type
    • data.orderInformation.billTo.address1
    • data.orderInformation.billTo.company.name
    • data.orderInformation.billTo.country
    • data.orderInformation.billTo.email
    • data.orderInformation.billTo.firstName
    • data.orderInformation.billTo.lastName
    • data.orderInformation.billTo.locality
    • data.orderInformation.billTo.phoneNumber
    • data.orderInformation.invoiceDetails.invoiceNumber
    • data.orderInformation.invoiceDetails.productDescription
    • data.orderInformation.lineItems[].productDescription
    • data.orderInformation.lineItems[].productSKU
    • data.orderInformation.lineItems[].taxAmount
    • data.orderInformation.lineItems[].totalAmount
    • data.orderInformation.lineItems[].typeOfSupply
    • data.orderInformation.shipTo.country
    • data.orderInformation.shipTo.locality
    • data.orderInformation.shipTo.postalCode
    • paymentInformation.customer.customerId
    • processingInformation.processingInstruction: set this field to ORDER_SAVED_EXPLICITLY to save the customer's payment credentials using the save-an-order follow-on request.

Verify Status

When the status of your payment request is PENDING, you can verify the status by sending a POST request to the URL that is included in the transactionStatus.url field in the webhook response:

{  "transactionStatus": {    "url": "/pts/v2/refresh-payment-status/76406322771491323955899488",    "method": "POST",    "payload": {      "clientReferenceInformation": {        "applicationName": "unifiedCheckout"      },      "processingInformation": {        "actionList": ["AP_STATUS"]      },      "paymentInformation": {        "paymentType": {          "method": {            "name": "payPal"          },          "name": "eWallet"        }      }    }  },  "transactionResult": {    "details": {      "submitTimeUtc": "2025-11-25T09:31:14Z",      "processorInformation": {        "sellerProtection": {          "eligibility": "ELIGIBLE",          "disputeCategories": ["ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION"]        },        "transactionId": "14815899TN877504A",        "orderStatus": "COMPLETED",        "orderId": "74902340T07048209",        "updateTimeUtc": "2025-11-25T09:33:48Z",        "expirationTimeUtc": "2025-12-24T09:33:48Z"      },      "orderInformation": {        "amountDetails": {          "totalAmount": "0.11",          "currency": "USD"        },        "billTo": {          "email": "[email protected]",          "lastName": "Doe",          "firstName": "Jane"        }      },      "updateTimeUtc": "2025-11-25T09:33:48Z",      "buyerInformation": {        "merchantCustomerId": "JS4EXZRT68ED8"      },      "message": "Successful",      "createTimeUtc": "2025-11-25T09:33:48Z",      "clientReferenceInformation": {        "code": "default"      },      "reconciliationId": "76406307371191323955899488",      "status": "COMPLETED",      "id": "76406322771491323955899488"    },    "id": "76406322771491323955899488",    "message": "Successful",    "outcome": "COMPLETED",    "status": "COMPLETED"  }}

You can also send a request to this endpoint to verify the status:

POST /pts/v2/refresh-payment-status/{id}

POST /pts/v2/refresh-payment-status/{id}

The {id} is the ID that is returned in the webhook response. For more information, see Webhooks.


Handle Responses

When Unified Checkout automatically processes a payment with autoProcessing set to true, or you have set autoProcessing to false and are using checkout.Complete(), you must handle both successful responses and various errors. After the payment is complete, the completeResponse field object contains information about the transaction outcome.

When a payment is processed successfully, you must parse the response to confirm the payment status, update your order records, and trigger any post-payment workflows. Post-payment workflows include sending confirmation emails or updating inventory. See Integration Examples.

Your error handling should account for specific cases such as COMPLETE_TRANSACTION_CANCELED and COMPLETE_TRANSACTION_FAILED. COMPLETE_TRANSACTION_CANCELED occurs when the user cancels the transaction, and COMPLETE_TRANSACTION_FAILED indicates that the consumer's transaction failed.

For wallet-based payments, only cancellation errors are returned. For information about possible errors that can occur when calling the complete API, see Error Handling.


Captures

When you set the completeMandate.type field value to AUTH or PREFER_AUTH, you must send a request to capture an authorized payment. Full and partial captures are supported. For capture endpoint details, see JavaScript Reference.

Example: Authorization Response from Unified Checkout

{  "details": {    "clientReferenceInformation": {      "code": "1753351101383"    },    "orderInformation": {      "amountDetails": {        "currency": "USD",        "totalAmount": "21.00"      }    },    "processorInformation": {      "approvalCode": "AUTH456789",      "responseCode": "00003",      "responseDetails": "00003",      "transactionId": "2016011808153910011808153AUTH"    },    "reconciliationId": "04RYADD29YRO",    "submitTimeUtc": "2025-07-24T09:58:21Z"  },  "id": "7533511014286971803092",  "message": "Request processed successfully.",  "outcome": "AUTHORIZED",  "status": "AUTHORIZED"}

Response Status

responds to your capture request with one of these statuses:

  • FAILED: the capture request failed.
  • PENDING: the capture request is accepted but not captured. Send a request to the check status service to retrieve status updates.
  • SETTLED: the capture request is settled for the amount requested.

Last published: November 18, 2026

Not available for your audience

This page isn't available for your current audience selection.