Contents
- Overview
- Requirements
- Installation and Configuration
- Checkout Using JSv4 Enabled Web Page
- Using Postman for Execute, Auth, Capture and other REST Calls
- Summary
This project provides an example checkout.js implementation (JSv4) for an 'AS2' transaction flow. A JSv4 enabled web page provides the customer checkout experience; Postman is used for execution, auth and capture.
- PayPal Sandbox "REST API App" setup and configured.
- Any standard JSv4 supported browser to view your JSv4 enabled webpage.
- Postman API client for making REST calls.
- Text editor or JavaScript tool. Examples:
- Webstorm is approved for reimbursement for LE EL's -- RECOMMENDED
- Notepad or Notpad++ for windows
- SublimeText
- BBEdit for Mac
We will need to get a local copy of this code in order to make some small changes. We will add our credentials to both the checkout-js.html file and Postman in order to authenticate with the PayPal Sandbox environment. You can either download a .zip and uncompress the files locally, or clone the repository using Git. More detailed instructions can be found here.
NOTE: Windows users may need to 'extract' the downloaded .zip file in your local filesystem if that is your chosen download method.
The PayPal Sandbox "Client ID" is used to identify the merchant and perform key security operations required by the JSv4 client. Edit the file chekout-js.html line 72 and add your Client ID into the 'client.sandbox' attribute of the code. Specifically, put your Client ID in place of <insert sandbox client id> :
env: 'sandbox', // sandbox | production
client: {
sandbox: '<insert sandbox client id>',
production: '<insert production client id>'
},
locale: 'en_US',More details on REST API Apps and the Client ID location in the developer.paypal.com console can be found here.
Launch Postman. Once in the application, you can "import" a new collection of API calls for our example. Specifically:
- Click the import button in the upper left of the Postman application.
- Once the import modal comes up, select the "Import File >> Choose Files" option and select the file in this project postman-paypal-rest-basic-collection.json
You should have an imported collection that looks like the following:
Next, create an 'environment' within Postman to hold oAuth tokens and other items behind the scenes. Select the 'gear' icon in the upper right and choose the option "Manage Environments". A modal appears where you can "Add" a new environment. Enter an appropriate name, and close the modal:
Add our credentials to the imported Postman collection above in order to authenticate against the PayPal oAuth system. Within the new Postman collection, open the "OAuth Token Request - Sandbox" operation. Select the 'Authorization' tab where you will be presented with a screen to enter credentials. These should already be selected, and we will be using:
- Type: 'Basic Auth'
- User: [REST API App 'Client ID']
- Password: [REST API App 'Secret']
Enter the the selections accordingly, and click "Send". You should see a response similar to the following:
Next, let's run the demo!!!
Open the checkout-js.html file in a supported browser (assuring our Client ID has been inserted into the appropriate attribute in checkout-js.html). This page has been configured to complete the REST equivalent of SetExpressCheckout" in classic nomenclature. We should see some JSON and the PayPal Checkout button:
Complete the checkout flow resulting in a page similar to the following. Note the ID (PAY-ID) and payer_id (PAYER-ID) fields in particular in the response:
Now, we are ready to complete the "execute" and "capture" calls of the flow. The API calls we make use REST URI and request body JSON as per the docs: Payments API reference documentation. Use these documents as your base reference moving forward.
NEXT: open up Postman and navigate to the imported collection.
Authentication for PayPal REST uses the oAuth authentication protocol. "Send" the "OAuth Token Request - Sandbox" operation as described in Setup and Configure Postman Collection.
You should see the access token in the response body as shown below. The 'access_token' is saved automatically to your environment as indicated in the documentation Setup and Configure Postman Collection:
{
"scope": "https://uri.paypal.com/services/subscriptions https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/payments/payouts https://api.paypal.com/v1/vault/credit-card/.*",
"nonce": "2017-11-13T19:37:55Z2av4hmyP3dQSIrlNf1PrCgXZW15M3CXxJVGD4ys-_pU",
"access_token": "A21AAHWgqKNpKLYkiUxjEIOcvJ2CR7MBlfd7QBYyoaim7vKFLc_DgnLC7gqzM6w9IddEiDyysfPhuOP7LVRYwNs4LAAiBx8TQ",
"token_type": "Bearer",
"app_id": "APP-80W284485P519543T",
"expires_in": 32384
}Use the 'Execute Payment' operation to complete the customer approval of the order. The PAY-ID and 'payer_id' from the checkout flow are used to execute the payment: See the corresponding highlighted areas in the image following:
- Open the 'Execute Payment' operation in the left hand navigation pane.
- Build the execute URI. Replace the {payment_id} URI parameter with your PAY-ID. (See depiction below)
- Build the JSON request body. In the Postman collection example, you can use the existing JSON and replace the 'payer_id' attribute with your PAYER-ID. (See depiction below)
Response
If successful, your response will contain a JSON payload similar to below. Use 'transactions.related_resources.order.id' to authorize your order in the next section. Additionally, you can use the HATEOS links provided in the response payload ('transactions.related_resources.order.links') to help build your authorization URI later:
{
"id": "PAY-3W249660WW2717409LIFDEQA",
"intent": "order",
"state": "approved",
"cart": "9S281710AK5473645",
"payer": {
"payment_method": "paypal",
"status": "VERIFIED",
"payer_info": {
"email": "[email protected]",
"first_name": "test",
"last_name": "buyer",
"payer_id": "VTW5PBHNTV24A",
"shipping_address": {
"recipient_name": "test buyer",
"line1": "400 Alabama Street",
"line2": "Suite 200",
"city": "San Francisco",
"state": "CA",
"postal_code": "94112",
"country_code": "US"
},
"country_code": "US"
}
},
"transactions": [
{
"amount": {
"total": "10.01",
"currency": "USD",
"details": {}
},
"payee": {
"merchant_id": "U3W86TPYJE8D6"
},
"item_list": {
"shipping_address": {
"recipient_name": "test buyer",
"line1": "400 Alabama Street",
"line2": "Suite 200",
"city": "San Francisco",
"state": "CA",
"postal_code": "94112",
"country_code": "US"
}
},
"related_resources": [
{
"order": {
"id": "O-81T919910A434173N",
"create_time": "2017-11-14T00:14:06Z",
"update_time": "2017-11-14T00:14:06Z",
"amount": {
"total": "10.01",
"currency": "USD",
"details": {}
},
"state": "PENDING",
"reason_code": "ORDER",
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/payments/orders/O-81T919910A434173N",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-3W249660WW2717409LIFDEQA",
"rel": "parent_payment",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/orders/O-81T919910A434173N/do-void",
"rel": "void",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/orders/O-81T919910A434173N/authorize",
"rel": "authorization",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/orders/O-81T919910A434173N/capture",
"rel": "capture",
"method": "POST"
}
],
"parent_payment": "PAY-3W249660WW2717409LIFDEQA"
}
}
]
}
],
...
}We next build our 'authorize order' call. Specifically:
- Use 'Auth Order' operation in the left hand navigation pane.
- Build the authorize order URI. Replace the {order_id} URI parameter with your order.id from the 'execute' call above. You can also use the HATEOS 'authorization' link provided in the execute response body above.
- Build the JSON request body. In the Postman collection example, you can use the existing JSON and replace the 'amount' related values as appropriate.
Response
If successful, your authorization response will contain a JSON payload similar to below:
{
"id": "2AU82319EU0433436",
"create_time": "2017-11-14T00:53:55Z",
"update_time": "2017-11-14T00:54:00Z",
"amount": {
"total": "3.00",
"currency": "USD"
},
"state": "authorized",
"protection_eligibility": "INELIGIBLE",
"parent_payment": "PAY-3W249660WW2717409LIFDEQA",
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/payments/orders/O-81T919910A434173N",
"rel": "order",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/authorization/2AU82319EU0433436/reauthorize",
"rel": "reauthorize",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/authorization/2AU82319EU0433436",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/authorization/2AU82319EU0433436/capture",
"rel": "capture",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/authorization/2AU82319EU0433436/void",
"rel": "void",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-3W249660WW2717409LIFDEQA",
"rel": "parent_payment",
"method": "GET"
}
]
}We are now ready to capture the authorized order. Using the authorization id or HATEOS capture link from the authorization call above, build our capture call. Specifically:
- Use the 'Capture Auth' operation in the left hand navigation pane.
- Build the capture URI. Replace {authorization_id} from the authorize order call above. You can also use the HATEOS 'capture' link provided in the 'authorization' response body above.
- Build the JSON request body. In the Postman collection example, you can use the existing JSON and replace the 'amount' and other values as appropriate.
Response
If successful, your capture response will contain a JSON payload similar to below:
{
"id": "13U262351W371525Y",
"create_time": "2017-11-14T01:14:29Z",
"update_time": "2017-11-14T01:14:34Z",
"amount": {
"total": "3.00",
"currency": "USD"
},
"is_final_capture": false,
"state": "completed",
"reason_code": "None",
"parent_payment": "PAY-3W249660WW2717409LIFDEQA",
"transaction_fee": {
"value": "0.39",
"currency": "USD"
},
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/payments/capture/13U262351W371525Y",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/capture/13U262351W371525Y/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/authorization/2AU82319EU0433436",
"rel": "authorization",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-3W249660WW2717409LIFDEQA",
"rel": "parent_payment",
"method": "GET"
}
]
}In this project, we should have gone through a simple JSv4 client checkout flow. Using Postman also operated a number of REST API calls to execute, authorize and capture the original order. The operations give us an insight into how a (straightforward) AS2 transaction flow moves data from the client and server side components.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent