Complete checkout

Completes the checkout process after customer has approved payment via PayPal. This endpoint receives the payment method with payer_id and finalizes the order. **Called when:** Customer completes PayPal payment approval **Required:** payment_method with valid token and payer_id

Authorization

PayPalJWT

AuthorizationBearer <token>

PayPal-supplied JWT token for authenticating merchant API requests.

Important: These JWT tokens are issued and managed by PayPal, not generated by merchants. PayPal provides these tokens to authenticate calls to your merchant API endpoints.

Usage:

Include in Authorization header as "Bearer "
Token is supplied by PayPal Shopping Cart service
Verify token signature using PayPal's public keys
Extract merchant identification from token claims

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

In: header

Path Parameters

cartId*string

The cart identifier

Header Parameters

Authorization*string

PayPal-supplied JWT token for authentication

Content-Type*string

Request content type

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://your-domain.com/api/paypal/v1/merchant-cart/CART-123/checkout" \  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \  -H "Content-Type: application/json" \  -H "Content-Type: application/json" \  -d '{    "payment_method": {      "type": "paypal",      "token": "EC-7U8939823K567",      "payer_id": "PAYER123456789"    },    "items": [      {        "variant_id": "JEANS-SLIM-32",        "parent_id": "JEANS-SLIM-COLLECTION",        "quantity": 2      }    ],    "customer": {      "name": {        "given_name": "John",        "surname": "Smith"      },      "email_address": "john.smith@example.com",      "phone": {        "country_code": "1",        "national_number": "5551234567"      }    },    "shipping_address": {      "address_line_1": "123 Main Street",      "address_line_2": "Apt 4B",      "admin_area_2": "San Jose",      "admin_area_1": "CA",      "postal_code": "95131",      "country_code": "US"    },    "billing_address": {      "address_line_1": "456 Payment Boulevard",      "address_line_2": "Suite 789",      "admin_area_2": "New York",      "admin_area_1": "NY",      "postal_code": "10001",      "country_code": "US"    }  }'

{
  "id": "CART-123",
  "status": "COMPLETED",
  "validation_status": "VALID",
  "validation_issues": [],
  "payment_confirmation": {
    "merchant_order_number": "ORDER-789",
    "order_review_page": "https://yourstore.com/orders/789"
  },
  "totals": {
    "total": {
      "currency_code": "USD",
      "value": "37.19"
    }
  }
}

{
  "name": "INVALID_REQUEST",
  "message": "Payment method is required for checkout",
  "debug_id": "ERROR-400-CHECKOUT-001",
  "details": [
    {
      "field": "payment_method",
      "issue": "MISSING_REQUIRED_FIELD",
      "description": "Payment method with token and payer_id is required"
    }
  ]
}

{
  "name": "CART_NOT_FOUND",
  "message": "Cart with ID does not exist",
  "debug_id": "ERROR-404-67890"
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "Payment was declined",
  "details": [
    {
      "field": "payment_method",
      "issue": "PAYMENT_DECLINED",
      "description": "Payment was declined by the payment processor"
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "A temporary system error occurred. Please try again later.",
  "debug_id": "ERROR-500-33445"
}

Header Parameters

Authorization*string

PayPal-supplied JWT token for authentication

Content-Type*string

Request content type

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

available_shipping_options?array<>

Available shipping methods with selection state

items?array<>

Products in the cart

Items1 <= items

customer?

Represents customer information for the shopping cart.

shipping_address?

International shipping address for cart delivery.

billing_address?

Billing address for merchant business purposes, obtained from customer's PayPal profile. Similar to shipping addresses, billing addresses can be retrieved from customer's default address information stored in their PayPal account.

When Billing Address is Available:

Customer has a default billing address in their PayPal profile
PayPal Credit and Buy Now Pay Later transactions
Guest checkout with credit/debit cards
User explicitly consents to address sharing
Required for tax compliance and regulatory reporting

Primary Use Cases:

Tax calculation: Sales tax/VAT rates determined by billing jurisdiction
Export compliance: Product restrictions based on customer's billing country
Financial reporting: Accounting systems requiring customer billing location
Address verification: Comparing billing vs shipping addresses for fraud prevention

Secondary Use Cases:

Business intelligence: Customer demographics and market analysis
B2B invoicing: Legal invoices requiring customer billing details
Compliance reporting: Regulatory requirements based on customer location

Note: Payment verification (AVS) and chargeback protection are handled by PayPal internally.

Implementation Notes:

Billing address is typically available from customer profile data
Can be populated during cart creation if customer provides it
Falls back to shipping address when billing address is not specified
Merchants should handle graceful fallback scenarios

payment_method?

Payment method information for PayPal Cart API. This API is specifically designed for PayPal's shopping cart service, so only PayPal payment methods are supported.

Payment Flow:

Cart creation generates a payment token (in payment_method.token)
Customer completes PayPal approval (Smart Wallet)
PayPal provides token and payer_id for checkout
Merchant receives PayPal payment confirmation

Billing Address Behavior:

PayPal handles all billing address collection internally for payment processing
Merchants can optionally collect billing addresses for tax calculation and business purposes
Billing address in cart is for merchant use cases, not payment requirements
Billing addresses are typically available from customer profile data

Note: Other payment methods (credit cards, Apple Pay, etc.) would be handled by separate merchant payment systems outside of this PayPal Cart API.

checkout_fields?array<>

Custom checkout fields (age verification, etc.)

coupons?array<>

Discount coupons to apply or remove from cart

geo_coordinates?

Optional precise location coordinates for enhanced delivery services

curl -X POST "https://your-domain.com/api/paypal/v1/merchant-cart/CART-123/checkout" \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -H "Content-Type: application/json" \ -d '{ "payment_method": { "type": "paypal", "token": "EC-7U8939823K567", "payer_id": "PAYER123456789" }, "items": [ { "variant_id": "JEANS-SLIM-32", "parent_id": "JEANS-SLIM-COLLECTION", "quantity": 2 } ], "customer": { "name": { "given_name": "John", "surname": "Smith" }, "email_address": "john.smith@example.com", "phone": { "country_code": "1", "national_number": "5551234567" } }, "shipping_address": { "address_line_1": "123 Main Street", "address_line_2": "Apt 4B", "admin_area_2": "San Jose", "admin_area_1": "CA", "postal_code": "95131", "country_code": "US" }, "billing_address": { "address_line_1": "456 Payment Boulevard", "address_line_2": "Suite 789", "admin_area_2": "New York", "admin_area_1": "NY", "postal_code": "10001", "country_code": "US" } }'

{ "id": "CART-123", "status": "COMPLETED", "validation_status": "VALID", "validation_issues": [], "payment_confirmation": { "merchant_order_number": "ORDER-789", "order_review_page": "https://yourstore.com/orders/789" }, "totals": { "total": { "currency_code": "USD", "value": "37.19" } } }

{ "name": "INVALID_REQUEST", "message": "Payment method is required for checkout", "debug_id": "ERROR-400-CHECKOUT-001", "details": [ { "field": "payment_method", "issue": "MISSING_REQUIRED_FIELD", "description": "Payment method with token and payer_id is required" } ] }

{ "name": "UNPROCESSABLE_ENTITY", "message": "Payment was declined", "details": [ { "field": "payment_method", "issue": "PAYMENT_DECLINED", "description": "Payment was declined by the payment processor" } ] }

Complete checkout

200application/json

400application/json

404application/json

422application/json

500application/json

Missing payment method information

Invalid PayPal token format

Missing payer ID after payment approval

Payment declined during checkout

Inventory became unavailable during checkout

Database connection failure

Payment processor failure

Payment capture failure

Unable to reserve inventory during checkout

Order creation system failure

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Complete checkout

200application/json

400application/json

404application/json

422application/json

500application/json

Missing payment method information

Invalid PayPal token format

Missing payer ID after payment approval

Payment declined during checkout

Inventory became unavailable during checkout

Database connection failure

Payment processor failure

Payment capture failure

Unable to reserve inventory during checkout

Order creation system failure

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`