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:

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

  1. PayPal transaction ID
  2. PNREF
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

  1. PayPal transaction ID
  2. PNREF
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.