Capture payments later

To collect payment at a later time, first authorize a payment using the /payment resource. You can then capture the payment to complete the sale and collect payment as described in the following sections.

  1. Authorize the payment
  2. Capture the payment

Note: Before you read this guide, register and learn how to make your first call.

Authorize the payment

Authorizing a payment is as simple as accepting a credit card or PayPal payment.

Important: Authorizations are guaranteed for up to three days, though capture of authorizations can be attempted for up to 29 days.

Set the intent to authorize to request an authorization for any payment type, including a credit card or PayPal payment.

This example requests 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": "http://www.amazon.com",
    "cancel_url": "http://www.hawaii.com"
  }
}'

A successful request returns a payment object with the state of the payment authorization:

{
  "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,
      "skip_fmf": 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"
  }]
}

In addition to payment details, the response includes these fields:

  • id. The PayPal-generated ID for the authorization.
  • state. The state of the authorization. The value is:
    • created. The authorization was successfully created.
    • approved. The buyer approved the authorization.
    • failed. The payment, authorization, or order request failed.
  • create_time. The date and time when the payment was created.
  • links. The HATEOAS link for capturing the authorized payment.

Credit card authorizations

Note: Direct credit card payment and related features are restricted in some countries.

A successful call returns an authorization object:

{
  "id": "PAY-0R831151JU007784NKGSU2SA",
  "create_time": "2013-05-29T00:35:20Z",
  "update_time": "2013-05-29T00:35:24Z",
  "state": "approved",
  "intent": "authorize",
  "payer":
  {
    "payment_method": "credit_card",
    "funding_instruments": [
    {
      "credit_card":
      {
        "type": "mastercard",
        "number": "xxxxxxxxxxxx2972",
        "expire_month": "12",
        "expire_year": "2018",
        "first_name": "Betsy",
        "last_name": "Buyer",
        "billing_address":
        {
          "line1": "111 First Street",
          "city": "Saratoga",
          "state": "CA",
          "postal_code": "95070",
          "country_code": "US"
        }
      }
    }]
  },
  "transactions": [
  {
    "amount":
    {
      "total": "7.47",
      "currency": "USD",
      "details":
      {
        "subtotal": "7.37",
        "tax": "0.04",
        "shipping": "0.06"
      }
    },
    "related_resources": [
    {
      "authorization":
      {
        "id": "9T287484DP554682S",
        "create_time": "2013-05-29T00:35:20Z",
        "update_time": "2013-05-29T00:35:24Z",
        "state": "authorized",
        "amount":
        {
          "total": "7.47",
          "currency": "USD",
          "details":
          {
            "subtotal": "7.37",
            "tax": "0.04",
            "shipping": "0.06"
          }
        },
        "parent_payment": "PAY-0R831151JU007784NKGSU2SA",
        "valid_until": "2013-06-27T00:35:20Z",
        "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/authorization/9T287484DP554682S",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/authorization/9T287484DP554682S/capture",
          "rel": "capture",
          "method": "POST"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/authorization/9T287484DP554682S/void",
          "rel": "void",
          "method": "POST"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-0R831151JU007784NKGSU2SA",
          "rel": "parent_payment",
          "method": "GET"
        }]
      }
    }]
  }],
  "links": [
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-0R831151JU007784NKGSU2SA",
    "rel": "self",
    "method": "GET"
  }]
}

PayPal authorizations

With PayPal payments authorizations, PayPal initially provides HATEOAS links that are specific to PayPal payments including an approval_url and execute link. First, get payment approval and execute the payment. After you successfully execute on the payment authorization, PayPal responds with a new set of HATEOAS links, including a capture link that you use to capture the payment.

Capture the payment

To capture payment, make a call to /v1/payments/authorization/[authorization_id]/capture with the authorization ID in the URI along with an amount object. For a partial capture, you can provide a lower amount. Additionally, you can explicitly indicate a final capture (prevent future captures) by setting the is_final_capture value to true.

curl -v 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
}'

Additional information

Learn about these operations in the API reference: