Initiate future transactions

Website Payments Pro merchants can initiate future transactions using a transaction ID

DocsCurrentAdvancedLast updated: September 30th 2021, @ 5:56:39 pm


Use your buyer's original transaction ID to charge them at a later time with reference transactions. A reference transaction is a transaction that you initiate through an established contract with the buyer and from which you can derive subsequent payments.

Important: Reference transactions are available to Website Payments Pro merchants only who have migrated to an advanced credit and debit card integration.

Know before you code

  • You have completed an advanced credit and debit card payments integration.
  • Reference transactions are available for merchants who have previously integrated with the DoReferenceTransaction API operation (NVP, SOAP).
  • You must provide the original transaction ID for the buyer and amount of the transaction.
  • You will need a previous order ID.
  • This server-side integration uses the following:

How it works

When a buyer purchases an item on your site, a transaction ID is generated. You can use this ID later to initiate a subsequent transaction, called a reference transaction, that uses the same payment method. The buyer must agree to this type of transaction.

Use cases

Use reference transactions to:

  • Save customers' card details for a future customer-initiated transaction.
  • Use merchant-initiated transactions to charge the payment method based on a previously-agreed contract.

1. Create an order

You need an order ID from a previous transaction. If you don't already have an order ID, you can create it.

API endpoint used: Create order

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "intent": "CAPTURE",
  "purchase_units": [
    {
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ]
}'

Modify the code

After you copy the code in the sample request, modify the following:

Step result

A successful request results in the following:

  • A return status code of HTTP 201 Created.
  • A JSON response body that contains an order ID, for example, 5O190127TN364715T:

    {
    "id": "5O190127TN364715T",
    "status": "CREATED",
    "links": [
      {
        "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
        "rel": "self",
        "method": "GET"
      },
      {
        "href": "https://www.paypal.com/checkoutnow?token=5O190127TN364715T",
        "rel": "approve",
        "method": "GET"
      },
      {
        "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
        "rel": "update",
        "method": "PATCH"
      },
      {
        "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
        "rel": "capture",
        "method": "POST"
      }
    ]
    }
    

2. Authorize payment

Authorize payment for an order using a previous transaction ID and order ID. You must have an original transaction ID from a prior transaction made by the same buyer.

API endpoint used: Authorize payment for order

curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer Access-Token' \
 -H 'Accept-Language: en_US' \
 -d '{
     "payment_source": {
       "token": {
         "id": "67N9717781765035V",
         "type": "PAYPAL_TRANSACTION_ID"
         }
       }
     }'
curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer Access-Token' \
 -H 'Accept-Language: en_US' \
 -d '{
     "payment_source": {
       "token": {
         "id": "67N9717781765035V",
         "type": "PNREF"
         }
       }
     }'

Modify the code

After you copy the code in the sample request, modify the following:

  • Access-Token- Your access token.
  • Order ID - In the URI for the API call, replace the sample ID with your order ID. In the sample, the order ID is 5O190127TN364715T.
  • Payment source - Replace the payment_source sample ID with your transaction ID. In the sample, the transaction ID is 67N9717781765035V.

Step result

A successful request results in the following:

  • A return status code of HTTP 201 Created.
  • A JSON response body that contains the order ID and a status of COMPLETED.

3. Capture payment

Capture payment for an order using a previous transaction ID and an order ID.

API endpoint used: Capture payment for order

curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \
 -H 'Content-Type: application/json' \
 -H 'PayPal-Request-ID: 7b92603e-77ed-4896-8e78-5dea2050476a' \
 -H 'Authorization: Bearer Access-Token' \
 -H 'Accept-Language: en_US' \
 -d '{
   "payment_source": {
      "token": {
        "id": "67N9717781765035V",
        "type": "PAYPAL_TRANSACTION_ID"
         }
       }
     }'
curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \
 -H 'Content-Type: application/json' \
 -H 'PayPal-Request-ID: 7b92603e-77ed-4896-8e78-5dea2050476a' \
 -H 'Authorization: Bearer Access-Token' \
 -H 'Accept-Language: en_US' \
 -d '{
   "payment_source": {
      "token": {
        "id": "67N9717781765035V",
        "type": "PNREF"
         }
       }
     }'

Modify the code

After you copy the code in the sample request, modify the following:

  • Access-Token - Your access token.
  • Order ID - In the URI for the API call, replace the sample ID with your order ID. In the sample, the order ID is 5O190127TN364715T.
  • PayPal-RequestId - Replace the sample ID with a unique ID you generate. This ID helps prevent duplicate authorizations in the event that the API call is disrupted. See also: API idempotency.
  • Payment source - Replace the payment_source sample ID with your transaction ID. In the sample, the transaction ID is 67N9717781765035V.

Step result

A successful request results in the following:

  • A return status code of HTTP 201 Created.
  • A JSON response body that contains the order ID and a status of COMPLETED.