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

The time periods for authorization and capture are:

Period Duration Description
Authorization

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

Note: A day is defined as the start of the calendar day when an authorization or reauthorization is made, from 00:00 to 23:50 Pacific Time.

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

Honor

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

Note: A day is defined as the start of the calendar day when an authorization or reauthorization is made, from 00:00 to 23:50 Pacific Time.

After a successful authorization or reauthorization, PayPal honors the authorized funds for three days. However, PayPal cannot ensure that 100% of the funds will be available.

You can only reauthorize 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 from days four to 29, after the three-day honor period for the original authorization expires. A re-authorized payment has a new, three-day honor period and there should be only one re-authorization within the honor period. If 30 days have passed from the original authorization, you must create a new authorization. You can re-authorize a transaction once for up to 115% of the original authorization or $75 USD more, whichever is less.

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

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