Authorize and capture payments

Use the Payments API to authorize a payment that you can capture later. For example, you might have a delayed shipment for which you do not want to collect funds right away.

Overview

You can authorize PayPal payments.

PayPal payment authorizations require buyer approval before you can capture these payments. For information, see PayPal Express Checkout Integration.

Authorization and capture includes these time periods:

Period Duration Description
Authorization period

A 29-day period that begins when the buyer authorizes the payment.

Note: A day starts at 12AM PST and ends at 11:59PM PST on the calendar day when the authorization occurs.

The authorization places the buyer's balance on hold to ensure that you can capture the funds.

Honor period

A three-day period from day one to day three of the authorization period.

PayPal honors 100% of authorized funds during this period. You can, however, attempt to capture an authorized payment any time during the entire 29-day authorization period but PayPal cannot guarantee that 100% of the funds are still available.

You can only re-authorize a payment after the honor period concludes.

To ensure that funds are still available, you can re-authorize a payment after the initial three-day honor period. You can re-authorize a payment only once from days four to 29 after the three-day honor period for the original authorization expires. If 30 days have passed from the original authorization, you must create a new authorization instead. A re-authorized payment itself has a new three-day honor period. You can re-authorize a transaction once for up to 115% of the original authorization or $75 USD more, whichever is less.

For any payment type, you can capture less than the or the full original authorized amount. You can also capture up to 115% of or $75 USD more than the original authorized amount, whichever is less.

You can also complete partial captures during a single authorization period. For PayPal payment authorizations, you must enable this feature on your PayPal account.

Notes:

  • Buyers and merchants cannot close accounts that have authorized but not yet captured payments.
  • You can also authorize payments for orders, which confirms the availability of funds but does not place the funds on hold. You can make multiple authorizations and captures against a single order. See authorize orders.

Integration steps

1. Required Meet the prerequisites.
2. Required Authorize the payment.
3. Required only for PayPal payments Get buyer approval and execute the payment authorization.
4. Required Capture the authorized payment.

Prerequisites

  1. Get an access token.

    When you create an app, PayPal generates a set of OAuth client ID and secret credentials for your app for both the sandbox and live environments. You pass these credentials in the Authorization header in a get access token request.

    In exchange for these credentials, the PayPal authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner.

    For more information, see make your first call. If you are a non-US developer, see International Developer Questions. You can use your sandbox access token to try any of the code in the REST API reference.

    Each API response includes HATEOAS links that enable you to construct a payment flow.

  2. To receive payments in a currency that you do not hold, first configure your Payment Receiving Preferences in your PayPal account. Otherwise, your payment status might be pending until you manually approve the payment in your PayPal account.

  3. To receive guest checkout payments, which allow credit cards, enable the PayPal Account Optional option in your account settings. The path to this option for US accounts is:

    Profile > My selling tools > Website preferences > PayPal Account Optional

  4. To test payments, create test buyer and merchant accounts in the PayPal sandbox. To create a test buyer account, select the Personal account type. To create a test merchant account, select the Business account type. See create sandbox accounts.

Authorize the payment

To authorize a payment to be captured later, create a payment and set the intent to authorize. You can authorize PayPal payments.

This example creates an authorization for a PayPal payment:

curl -v https://api.sandbox.paypal.com/v1/payments/payment \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "intent": "authorize",
  "payer":
  {
    "payment_method": "paypal"
  },
  "transactions": [
  {
    "amount":
    {
      "total": "30.11",
      "currency": "USD",
      "details":
      {
        "subtotal": "30.00",
        "tax": "0.07",
        "shipping": "0.03",
        "handling_fee": "1.00",
        "shipping_discount": "-1.00",
        "insurance": "0.01"
      }
    },
    "description": "This is the payment transaction description.",
    "custom": "EBAY_EMS_90048630024435",
    "invoice_number": "48787589673",
    "payment_options":
    {
      "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
    },
    "soft_descriptor": "ECHI5786786",
    "item_list":
    {
      "items": [
      {
        "name": "hat",
        "description": "Brown color hat",
        "quantity": "5",
        "price": "3",
        "tax": "0.01",
        "sku": "1",
        "currency": "USD"
      },
      {
        "name": "handbag",
        "description": "Black color hand bag",
        "quantity": "1",
        "price": "15",
        "tax": "0.02",
        "sku": "product34",
        "currency": "USD"
      }],
      "shipping_address":
      {
        "recipient_name": "Hello World",
        "line1": "4thFloor",
        "line2": "unit#34",
        "city": "SAn Jose",
        "country_code": "US",
        "postal_code": "95131",
        "phone": "011862212345678",
        "state": "CA"
      }
    }
  }],
  "note_to_payer": "Contact us for any questions on your order.",
  "redirect_urls":
  {
    "return_url": "https://www.paypal.com/return",
    "cancel_url": "https://www.paypal.com/cancel"
  }
}'

If the request succeeds, the response includes the payment details. The response also includes:

  • id. The PayPal-generated ID for the authorization.
  • state. The state of the authorization, which is either created or failed.
  • create_time. The date and time when the payment authorization was created.
  • links. The approval_url and execute links that you use to get buyer approval and execute the payment authorization. After you successfully execute the payment authorization, PayPal responds with a capture link that you use to capture the payment.
{
  "id": "PAY-1BP41925BA069714SK6SKIAY",
  "intent": "authorize",
  "state": "created",
  "payer":
  {
    "payment_method": "paypal"
  },
  "transactions": [
  {
    "amount":
    {
      "total": "30.11",
      "currency": "USD",
      "details":
      {
        "subtotal": "30.00",
        "tax": "0.07",
        "shipping": "0.03",
        "insurance": "0.01",
        "handling_fee": "1.00",
        "shipping_discount": "-1.00"
      }
    },
    "description": "This is the payment transaction description.",
    "custom": "EBAY_EMS_90048630024435",
    "invoice_number": "48787589673",
    "soft_descriptor": "ECHI5786786",
    "payment_options":
    {
      "allowed_payment_method": "INSTANT_FUNDING_SOURCE",
      "recurring_flag": false
    },
    "item_list":
    {
      "items": [
      {
        "name": "hat",
        "sku": "1",
        "description": "Brown color hat",
        "price": "3.00",
        "currency": "USD",
        "tax": "0.01",
        "quantity": 5
      },
      {
        "name": "handbag",
        "sku": "product34",
        "description": "Black color hand bag",
        "price": "15.00",
        "currency": "USD",
        "tax": "0.02",
        "quantity": 1
      }],
      "shipping_address":
      {
        "recipient_name": "Hello World",
        "line1": "4thFloor",
        "line2": "unit#34",
        "city": "SAn Jose",
        "state": "CA",
        "postal_code": "95131",
        "country_code": "US",
        "phone": "011862212345678"
      }
    },
    "related_resources": []
  }],
  "note_to_payer": "Contact us for any questions on your order.",
  "create_time": "2016-08-05T14:34:42Z",
  "links": [
  {
    "href": "https://msmaster.qa.paypal.com:11881/v1/payments/payment/PAY-1BP41925BA069714SK6SKIAY",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://www.msmaster.qa.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-511429312Y0182227",
    "rel": "approval_url",
    "method": "REDIRECT"
  },
  {
    "href": "https://msmaster.qa.paypal.com:11881/v1/payments/payment/PAY-1BP41925BA069714SK6SKIAY/execute",
    "rel": "execute",
    "method": "POST"
  }]
}

Next, capture an authorized payment.

Capture an authorized payment

To capture an authorized payment, include the authorization ID in the URI of the call.

Include the amount that you want to capture in the amount object in the JSON request body. For a partial capture, you can provide a lower amount.

Optionally, set is_final_capture to true to prevent future captures.

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/authorization/9T287484DP554682S/capture \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
  "currency": "USD",
  "total": "4.54"
  },
  "is_final_capture": true
}

The response shows details for the captured payment including links that enable you to complete actions against the captured payment:

{
  "id": "6BA17599X0950293U",
  "create_time": "2017-05-06T22:32:24Z",
  "update_time": "2017-05-06T22:32:25Z",
  "amount": {
    "total": "4.54",
    "currency": "USD"
  },
  "is_final_capture": true,
  "state": "completed",
  "parent_payment": "PAY-44664305570317015KGEC5DI",
  "links": [{
    "href": "https://api.sandbox.paypal.com/v1/payments/capture/6BA17599X0950293U",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/capture/6BA17599X0950293U/refund",
    "rel": "refund",
    "method": "POST"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/authorization/5RA45624N3531924N",
    "rel": "authorization",
    "method": "GET"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-44664305570317015KGEC5DI",
    "rel": "parent_payment",
    "method": "GET"
  }]
}

Next

You can complete these authorization-related tasks:

Or, learn how to create orders.

Additional information