Initiate future transactions

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.

1. The payer generates a transaction ID when they purchase an item on your site.
2. The payer agrees to a reference transaction.
3. Use the transaction ID in future reference transactions using the same payment method.

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.

1. 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}'

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.

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 previous 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     }'

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.

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

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.

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.