Initiate future transactions

DocsCurrentADVANCED

Last updated: Feb 27th, 7:41am

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

Important: Reference transactions are available to Website Payments Pro merchants only who have migrated to an Expanded Checkout integration.

How it works

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

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

You need a reference transaction to start a future transaction using the same payment method. Get the following information:

A previous order ID.

The payment amount.

The payer’s original transaction ID.

Process

The payer generates a transaction ID when they purchase an item on your site.

The payer agrees to a reference transaction.

Use the transaction ID in future reference transactions using the same payment method.

Use cases

Use reference transactions to:

Save payer's card details for a future payer-initiated transaction.

Initiate transactions to charge the payment method based on a previously-agreed contract.

Know before you code

Required

To complete this server-side integration, you will need:

An Expanded Checkout integration.
The Orders v2 REST API: Create, update, retrieve, authorize, and capture orders.

Use Postman to explore and test PayPal APIs.

Optional

NVP and SOAP integrations

You can get reference transactions from an existing NVP or SOAP integration of the DoReferenceTransactionAPI.

Create an order

Provide an order ID from a previous transaction or create a new one.

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:

Sample JSON response

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}

Authorize payment

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

API endpoint used: Authorize payment for order

PayPal transaction ID
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 example, the order ID is 5O190127TN364715T.
Payment source - Replace the payment_source sample ID with your transaction ID. In the example, 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.

Capture payment

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

API endpoint used: Capture payment for order

PayPal transaction ID
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 example, 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. For more information, see API idempotency.
Payment source - Replace the payment_source sample ID with your transaction ID. In the example, 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.

Next steps

Optional

Postman Collection

Test additional positive and 4xxerror conditions.

Optional

Simulate negative responses

Use API request headers to trigger negative responses.