Authorize and Capture Payments Integration Guide

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

An authorization places a hold on the funds and is valid for 29 days. After a successful authorization, PayPal recommends that you capture the funds within the three-day honor period. Success of the capture is subject to risk and availability of funds on the authorized funding instrument. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires. A re-authorization generates a new Authorization ID and restarts the honor period, and any subsequent capture should be performed on the new Authorization ID. If you do a re-authorization on the 27th day of the authorization, you get only two days of honor period.

Within a 29-day authorization period, you can issue multiple reauthorizations after the initial three-day honor period expires.

Day Action Authorization period Honor period
1 Authorization-1 Begins 29-day authorization period Days 1 through 3
4 Reauthorization-1 on Authorization-1 Within 29-day authorization period Days 4 through 7
8 Reauthorization-2 on Authorization-1 Within 29-day authorization period Days 8 through 11

For any payment type, you can capture less than 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.

Note:

  • Customers 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.

Integration steps

1. Required Set up your development environment.
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.

Set up your development environment

Before you can integrate Payments, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get Started.

Then, return to this page to integrate Payments.

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://example.com/return",
    "cancel_url": "https://example.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://api.sandbox.paypal.com/v1/payments/payment/PAY-1BP41925BA069714SK6SKIAY",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-511429312Y0182227",
    "rel": "approval_url",
    "method": "REDIRECT"
  },
  {
    "href": "https://api.sandbox.paypal.com/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

Feedback