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/orders2-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 toauthorize
.
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
- PayPal transaction ID
- PNREF
1curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize2 -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 is67N9717781765035V
.
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
- PayPal transaction ID
- PNREF
1curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture2 -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 is67N9717781765035V
.
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
.