Initiate future transactions

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

DocsCurrentLast updated: August 26th 2021, @ 3:16:53 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 Orders REST API.

• Use Postman to explore and test PayPal APIs.

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

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders
2-H "Content-Type: application/json"
3-H "Authorization: Bearer Access-Token"
4-d '{
5  "intent": "CAPTURE",
6  "purchase_units": [
7    {
8      "amount": {
9        "currency_code": "USD",
10        "value": "100.00"
11      }
12    }
13  ]
14}'

Modify the code

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

• Access-Token- Your access token.
• The intent in this sample is capture, which captures the payment immediately. You can choose to separate the authorize and capture actions by changing the intent to authorize.

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:
  1{
  2  "id": "5O190127TN364715T",
  3  "status": "CREATED",
  4  "links": [
  5    {
  6      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
  7      "rel": "self",
  8      "method": "GET"
  9    },
  10    {
  11      "href": "https://www.paypal.com/checkoutnow?token=5O190127TN364715T",
  12      "rel": "approve",
  13      "method": "GET"
  14    },
  15    {
  16      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
  17      "rel": "update",
  18      "method": "PATCH"
  19    },
  20    {
  21      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
  22      "rel": "capture",
  23      "method": "POST"
  24    }
  25  ]
  26  }

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

1curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize
2 -H 'Content-Type: application/json'
3 -H 'Authorization: Bearer Access-Token'
4 -H 'Accept-Language: en_US'
5 -d '{
6     "payment_source": {
7       "token": {
8         "id": "67N9717781765035V",
9         "type": "PAYPAL_TRANSACTION_ID"
10         }
11       }
12     }'

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

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

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.