We additionally need to create a test user<\/a> to use with the PayPal sandbox. When testing in the sandbox<\/strong> environment, you can use this test account, which doesn\u2019t require adding a credit card or funding the account.<\/p>\n The following steps assume you have Node.js, npm, and a Bot Framework Emulator installed on your computer. To install Node and npm, visit the Node download page<\/a> and select \u2018Current.\u2019 At the time of writing, the current iteration of Node is version 6.7.0, but any version that is 4.x or above should work. We do not recommend lower versions as the semantics of some keywords have changed between versions.<\/p>\n The cross platform Bot Framework Emulator is available to download here<\/a>.<\/p>\n From here on, we\u2019ll reference and discuss the code available on Github<\/a>. Using PayPal offers many APIs and products for creating and executing payments between users and businesses. To keep our integration straightforward, we\u2019ll focus on one relatively simple flow, which involves user approval of payment before we\u2019re able to execute and receive a payment. The full flow is described in PayPal\u2019s documentation<\/a> in detail, but we\u2019ll be using PayPal\u2019s Node SDK<\/a> to remove some of the boilerplate in creating and executing the payments.<\/p>\n To use the PayPal Node SDK, we must require it as a module, and configure it with the Client ID<\/strong> and Client Secret<\/strong> variables we generated from the PayPal dashboard earlier. PayPal also provides a sandbox environment for testing transactions. We\u2019ll use this environment here to test payments. In practice, when deploying to a production service, you\u2019ll likely want to use different credentials. One popular way to achieve this bucketed approach to deployment is through the underlying system\u2019s environment variables. This way, your code can be environment-agnostic, and you won\u2019t need to keep your Client ID<\/strong> and Client Secret<\/strong> variables in your code. When configured, the To set up our bot, we\u2019ll need to create an instance of a This setup is great, but our bot doesn\u2019t do anything yet; we haven\u2019t defined any logic for it. Let\u2019s step back and define a use case for this bot: a city government charges a resident for their parking fine and the resident logs on to complete that payment. This example is straightforward enough that we can build it using a single dialog combined with a waterfalled conversation. For more background on dialogs and conversation, please read the related section of the Bot Framework documentation<\/a>. A stubbed out example is as follows:<\/p>\n Now, our bot will be able to respond to conversation. Let\u2019s test it in the bot framework emulator:<\/p>\n Our bot can now recognize that we want to pay our fine, but it does not yet know how to process that fine. Line 24<\/a> of the above gist describes a \u201cTODO\u201d: creating a payment and asking the user to approve it. This point is the first step in our two-step approval\/execution flow for collecting payment from a user. Let\u2019s create a function, The callback (starting at Line 44<\/a>) passed as the second parameter looks through the With the user having visited the URL and approved a payment, we must now execute the payment. To do that, we must create a To execute an approved payment, we use the We now have the full payment flow, except the very last step which involves informing the user (via the bot, and on the user\u2019s native messaging channel) that their payment has been successfully processed. Since we\u2019re no longer operating within the context of the bot, but rather within the context of the HTTP server, we\u2019ll have to get creative.<\/p>\n We\u2019ll need to modify our code a bit and build up an Line 8<\/a> identifies the Setup Node and grab the sample<\/h2>\n
git<\/code>, clone the repository onto your computer in your terminal of choice: git clone https:\/\/github.com\/bnookala\/node-paymentbot<\/code>, cd<\/code> into this directory and run npm install<\/code> to download the module dependencies.<\/p>\nRunning the sample<\/h2>\n
\n
cd<\/code> into the node-paymentbot<\/code> directory<\/li>\nnpm install<\/code> to install the module dependencies<\/li>\nPAYPAL_CLIENT_ID<\/code>, PAYPAL_CLIENT_SECRET<\/code>, and PAYPAL_CLIENT_MODE<\/code> environment variables in your terminal to the copied Client ID<\/strong> from PayPal, the copied Client Secret<\/strong> from PayPal, and \u201csandbox\u201d<\/strong> respectively. You can optionally set the PORT<\/code> environment variable to customize which port the application is bound to, but it will default to 3978.<\/li>\nnode app.js<\/code>, note the URL that it writes the console, i.e., restify listening to http:\/\/[::]:3978<\/code><\/li>\nhttp:\/\/localhost:3978\/api\/messages<\/code><\/li>\nBuilding a payment flow from scratch<\/h2>\n
Integrating PayPal into a Bot<\/h2>\n
paypal<\/code> module will be able to create and execute payments and transactions:<\/p>\n\r\nFile: paypal_ex.js\r\n------------------\r\n\r\nconst paypal = require('paypal-rest-sdk');\r\n\r\npaypal.configure({\r\n 'mode': process.env.PAYPAL_CLIENT_MODE,\r\n 'client_id': process.env.PAYPAL_CLIENT_ID,\r\n 'client_secret': process.env.PAYPAL_CLIENT_SECRET\r\n});\r\n<\/code><\/pre>\nChatConnector<\/code> and an instance of a UniversalBot<\/code>. We\u2019ll also need to create an HTTP server, for the ChatConnector<\/code> instance to listen on. A ChatConnector<\/code> allows our Bot to listen and respond on multiple types of messaging channels. Bot Framework currently supports numerous popular messaging channels<\/a>, and is consistently adding more. We\u2019ll use the UniversalBot<\/code> instance to define our bot\u2019s logic (i.e. how it should respond and react when a user performs an action):<\/p>\n\r\nFile: bot_ex.js\r\n---------------\r\n\r\nconst restify = require('restify');\r\nconst builder = require('botbuilder');\r\n\r\n\/\/ A connector connects a bot on bot framework to various messaging services that a bot\r\n\/\/ can talk to.\r\nlet connector = new builder.ChatConnector({\r\n appId: undefined,\r\n appPassword: undefined\r\n});\r\n\r\n\/\/ A bot listens and reacts to messages that the connector picks up on.\r\nlet bot = new builder.UniversalBot(connector);\r\n\r\n\/\/ We're using restify here to set up an HTTP server, and then adding the queryParser middleware,\r\n\/\/ which will parse the query string into on object on any requests.\r\nlet server = restify.createServer();\r\nserver.use(restify.queryParser());\r\n\r\n\/\/ The server will start listening on this port defined in the environment.\r\nserver.listen(process.env.PORT, function () {\r\n console.log('%s listening to %s', server.name, server.url);\r\n});\r\n\r\n\/\/ Messages are posted to this endpoint. We ask the connector to listen at this endpoint for new messages.\r\nserver.post('\/api\/messages', connector.listen());\r\n<\/code><\/pre>\n\r\nFile: bot_dialog_stubbing.js\r\n----------------------------\r\n\r\n\/\/ The root dialog of our bot simply just jumps straight into the\r\n\/\/ business logic of paying a fine.\r\nbot.dialog('\/', function (session, args) {\r\n session.beginDialog('listFines');\r\n});\r\n\r\n\/\/ Simple three step dialog to list 'fines' that a user has received, and allow\r\n\/\/ a user to 'pay' them.\r\nbot.dialog('listFines', [\r\n function (session, args) {\r\n console.log('List Fines Dialog');\r\n session.send('You have 1 outstanding fine:');\r\n\r\n session.send('Parking Fine Violation');\r\n builder.Prompts.choice(session, "What would you like to do?", ["Pay fine", "Cancel"]);\r\n },\r\n function (session, results, next) {\r\n let choice = results.response;\r\n\r\n if (choice.entity === 'Cancel') {\r\n return;\r\n }\r\n\r\n \/\/ TODO: Create a payment, and ask the user to act on it.\r\n },\r\n function (session, results) {\r\n session.send('Thanks for your payment!')\r\n },\r\n]);\r\n<\/code><\/pre>\n![\"Image](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2016\/10\/emulator.png\")
<\/p>\ncreateAndSendPayment<\/code>, that can create the payment using the PayPal Node SDK, and provide a link that the user can go to the approve the payment. We\u2019ll use the function paypal.payment.create<\/code> that the Paypal Node SDK offers to create this payment. The first argument to this function is a JSON object, and the second is a callback that is executed upon success or failure. The schema of the JSON object defines the payment that the user will approve, and includes the name, description, amount, and URLs that PayPal will redirect to on approval or cancellation. The full schema of the JSON object that PayPal requires for payment creation is described in their documentation<\/a>. The code as follows describes a function that builds our payment JSON, and one that takes this built JSON, creates a payment and asks the user to approve it:<\/p>\n\r\nFile: payment_json_ex.js\r\n------------------------\r\n\r\n\r\n\/**\r\n * This function creates and returns an object that is passed through to the PayPal Node SDK\r\n * to create a payment that a user must manually approve.\r\n *\r\n * See https:\/\/developer.paypal.com\/docs\/api\/payments\/#payment_create_request for a description of the fields.\r\n *\/\r\nfunction createPaymentJson (returnUrl, cancelUrl) {\r\n return {\r\n "intent": "sale",\r\n "payer": {\r\n "payment_method": "paypal"\r\n },\r\n "redirect_urls": {\r\n "return_url": returnUrl,\r\n "cancel_url": cancelUrl\r\n },\r\n "transactions": [{\r\n "item_list": {\r\n "items": [{\r\n "name": "Fine",\r\n "sku": "ParkingFine",\r\n "price": "1.00",\r\n "currency": "USD",\r\n "quantity": 1\r\n }]\r\n },\r\n "amount": {\r\n "currency": "USD",\r\n "total": "1.00"\r\n },\r\n "description": "This is your fine. Please pay it :3"\r\n }]\r\n };\r\n}\r\n\/**\r\n * Creates a payment on paypal that a user must approve.\r\n *\/\r\nfunction createAndSendPayment (session) {\r\n console.log('Creating Payment');\r\n\r\n let paymentJson = createPaymentJson('http:\/\/localhost', 'http:\/\/localhost');\r\n\r\n paypal.payment.create(paymentJson, function (error, payment) {\r\n if (error) {\r\n throw error;\r\n } else {\r\n \/\/ The SDK returns a payment object when the payment is successfully created.\r\n \/\/ This object has a few properties, described at length here:\r\n \/\/ https:\/\/developer.paypal.com\/docs\/api\/payments\/#payment_create_response\r\n \/\/ We're looking for the 'approval_url' property, which the user must go to\r\n \/\/ to approve the transaction before we can actively execute the transaction.\r\n for (var index = 0; index < payment.links.length; index++) {\r\n if (payment.links[index].rel === 'approval_url') {\r\n session.send("Please pay your fine: " + payment.links[index].href);\r\n }\r\n }\r\n }\r\n });\r\n};\r\n<\/code><\/pre>\npayment<\/code> object received as an argument and searches for an approval_url<\/code> property, which can be presented to the user. The user must visit this URL and approve the payment before we can continue and execute the payment. We use a Bot Framework built-in, builder.Prompts.text<\/code>, to display the approval URL to the user.<\/p>\nredirect_url<\/code> and provide that in the JSON object for payment creation. PayPal will then redirect our user to this endpoint, which will be hosted by us on the HTTP server we had set up earlier. Soon, we\u2019ll use this endpoint to perform the payment execution. Our code now has a endpoint (lines 3 through 6<\/a>) that PayPal will redirect to:<\/p>\n\r\nFile: redirect_ex.js\r\n--------------------\r\n\r\n\/\/ This endpoint describes the approval redirect endpoint that you can provide in the JSON blob passed to PayPal.\r\n\/\/ When a user approves a payment, PayPal will redirect the user to this.\r\nserver.get('approvalComplete', function (req, res, next) {\r\n console.log('User approved payment!');\r\n res.send(200);\r\n});\r\n\r\nfunction createReturnUrl () {\r\n let url = require('url');\r\n \/\/ This object encodes the endpoint that PayPal redirects to when.\r\n \/\/ a user approves the payment\r\n let urlObject = {\r\n protocol: 'http',\r\n hostname: 'localhost',\r\n port: configuration.PORT,\r\n pathname: 'approvalComplete',\r\n }\r\n\r\n return url.format(urlObject);\r\n};\r\n\r\nfunction createAndSendPayment (session) {\r\n let returnUrl = createReturnUrl();\r\n let paymentJson = createPaymentJson(returnUrl);\r\n\r\n \/\/ create payment, etc\u00e2\u20ac\u00a6\r\n};\r\n<\/code><\/pre>\npaypal.payment.execute<\/code> function provided by PayPal\u2019s Node SDK. This function takes three arguments: a payment ID, a JSON blob with a few fields describing the payment to be executed<\/a>, and a callback that is run on success or fail. When PayPal redirects to our endpoint, it modifies the query parameters of the redirect URL, adding a paymentId<\/code> and a PayerID<\/code>. These parameters must be used to execute the payment, with paymentId<\/code> corresponding to the first argument of paypal.payment.execute<\/code>, and PayerID<\/code> corresponding to a field within the JSON blob:<\/p>\n\r\nFile: payment_execution_ex.js\r\n-----------------------------\r\n\r\nserver.get('approvalComplete', function (req, res, next) {\r\n console.log('User approved transaction');\r\n executePayment(req.params);\r\n res.send(200);\r\n});\r\n\r\nfunction executePaymentJson (payerId) {\r\n return {\r\n "payer_id": payerId,\r\n "transactions": [{\r\n "amount": {\r\n "currency": "USD",\r\n "total": "1.00"\r\n }\r\n }]\r\n };\r\n}\r\n\r\nfunction executePayment(params) {\r\n console.log('Executing an Approved Payment');\r\n\r\n \/\/ Appended to the URL by PayPal during the approval step.\r\n let paymentId = parameters.paymentId;\r\n let payerId = parameters.PayerID;\r\n\r\n \/\/ Generate the sample payment execution JSON that paypal requires:\r\n let paymentJson = executePaymentJson(payerId)\r\n\r\n \/\/ Finally, execute the payment, and tell the user that we got their payment.\r\n paypal.payment.execute(paymentId, paymentJson, function (error, payment) {\r\n if (error) {\r\n console.log(error.response);\r\n throw error;\r\n } else {\r\n console.log('Payment Executed Successfully');\r\n \/\/ TODO: Inform the user on their bot channel.\r\n }\r\n });\r\n};\r\n<\/code><\/pre>\nAddress<\/code>, a Bot Framework model that identifies the channel and user with which a message is associated. These properties are all encoded on the session.message<\/code> object normally, and can thus be re-encoded as query arguments in the return_url<\/code> of the approval step. PayPal does not strip these parameters, so they get returned again when the user is redirected to the approvalComplete<\/code> endpoint. When the payment is executed, we can pass these parameters along and create a message to be sent to the user, even in the context of the HTTP Server, without an active session<\/code> object.<\/p>\n\r\nFile: redirect_bot_message_ex.js\r\n--------------------------------\r\n\r\nfunction createReturnUrl (address) {\r\n console.log('Creating Return Url');\r\n\r\n \/\/ The address passed in is an Object that defines the context\r\n \/\/ of the conversation - the user, the channel, the http endpoint the bot\r\n \/\/ exists on, and so on. We encode this information into the return URL\r\n \/\/ to be parsed out by our approval completion endpoint.\r\n let addressEncoded = encodeURIComponent(JSON.stringify(address));\r\n\r\n \/\/ This object encodes the endpoint that PayPal redirects to when.\r\n \/\/ a user approves the transaction.\r\n let urlObject = {\r\n protocol: 'http',\r\n hostname: 'localhost',\r\n port: configuration.PORT,\r\n pathname: 'approvalComplete',\r\n query: addressEncoded\r\n }\r\n\r\n return url.format(urlObject);\r\n}\r\n\r\nfunction executePayment (parameters) {\r\n console.log('Executing an Approved Payment');\r\n\r\n \/\/ Appended to the URL by PayPal during the approval step.\r\n let paymentId = parameters.paymentId;\r\n let payerId = parameters.PayerID;\r\n\r\n \/\/ Generate the sample payment execution JSON that paypal requires:\r\n let paymentJson = executePaymentJson(payerId)\r\n\r\n \/\/ Grab the encoded address object, URL decode it, and parse it back into a JSON object.\r\n let addressEncoded = decodeURIComponent(parameters.addressEncoded);\r\n let address = JSON.parse(addressEncoded);\r\n\r\n \/\/ Finally, execute the payment, and tell the user that we got their payment.\r\n paypal.payment.execute(paymentId, paymentJson, function (error, payment) {\r\n if (error) {\r\n console.log(error.response);\r\n throw error;\r\n } else {\r\n console.log('Payment Executed Successfully');\r\n respondToUser(payment, address);\r\n }\r\n });\r\n}\r\n\r\nfunction respondToUser (payment, address) {\r\n let message = new builder.Message().address(address).text('Thanks for your payment!');\r\n\r\n \/\/ Asks the bot to send the message we built up above to the user.\r\n bot.send(message.toMessage());\r\n}\r\n\r\nbot.dialog('listFines', [\r\n function (session, args) {\r\n console.log('List Fines Dialog');\r\n session.send('You have 1 outstanding fine:');\r\n\r\n session.send('Parking Fine Violation');\r\n builder.Prompts.choice(session, "What would you like to do?", ["Pay fine", "Cancel"]);\r\n },\r\n function (session, results, next) {\r\n let choice = results.response;\r\n\r\n if (choice.entity === 'Cancel') {\r\n return;\r\n }\r\n\r\n \/\/ Starts the payment flow.\r\n createAndSendPayment(session);\r\n },\r\n]);\r\n\r\n\r\n<\/code><\/pre>\nAddress<\/code> of the message to be encoded into the return_url<\/code>. When the payment is executed, lines 34-35<\/a> pull these same encoded parameters out of the query string, and pass it along to a new function, respondToUser<\/code>, which uses the address to build up a builder.Message<\/code>. All messages that pass through the Bot Framework are represented internally through this model. Thus, we can create a response here, and send it along to our bot at line 53<\/a>. Our complete interaction now looks like this:<\/p>\n![\"Image](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2016\/10\/complete_flow.gif\")
<\/p>\nConclusion<\/h2>\n