If the transaction was interrupted, for example if a credit card was declined, the value is `UNKNOWN`. Note: If a credit card is declined, the merchant can enter an alternative payment method.
If the merchant cancels, the order-entry’s return URL is called, appended with `Type=UNKNOWN`.
Due to legacy issues, the values for "Type" currently differ based on the version being used.
On PayPal Here versions 2.x on all platforms, these values can be: `UNKNOWN`, `KEY`, `SCAN`, `SWIPE`, `PAYPAL`, `CHECK`, `CASH`, `CHIP`, `EMV_SWIPE`.
On iPad 1.x, these values can be: `Unknown`, `CreditCard`, `Check`, `Cash`, `PayPal`, `DebitCard`, `Other`, `ChipCard`.
You should code your integrations to handle new values being returned in this field.| 222 | | `InvoiceId` | The ID of the new invoice for which payment was accepted. | 223 | | `Tip` | The monetary value tip, if applicable. | 224 | | `Number` | The merchant reference number for the invoice, which you can optionally pass in when opening PayPal Here with the `number` parameter. Mind the difference in capitalization. For more information about the input value that corresponds to this ID, see __Invoice as a JSON object.__ | 225 | | `GrandTotal` | The final total amount of the invoice. | 226 | 227 | 228 | ## Order and Payment Flow 229 | 230 | This section uses an example of charging a credit card to outline steps for: 231 | 232 | * Using an order-entry app to send an invoice to the PayPal Here app 233 | * Accepting a payment in the PayPal Here app 234 | 235 | After the merchant accepts the payment, your order-entry app is re-launched so the merchant can 236 | confirm that the payment was successfully recorded in the order-entry app. 237 | 238 | The following steps describe a version of an order and payment flow. 239 | 240 | 1. Merchant starts the order-entry app and brings up an order. 241 | 2. Merchant chooses **Pay** in the order-entry app. 242 | 3. The order-entry app uses the following URL and fields to launch the PayPal Here app: 243 | `paypalhere://takePayment?[URL-encoded input fields]&invoice=[invoice as a base64-encoded JSON object]` 244 | 4. Merchant logs into Merchant’s PayPal account. On the Charge screen, the PayPal Here app displays the items and amounts of the order. 245 | *
246 | 5. In the PayPal Here app, Merchant chooses **Charge**.
247 | 6. . On the Payment Options screen, the Merchant can choose Card, or swipe the card. If the Merchant chooses a different option on the following screen, subsequent steps would differ from those below.
248 | * 
249 | 7. On the Card Info screen, Merchant can swipe the credit card, as in this example. If Merchant keys in the card or uses a different payment method, the screens are different.
250 | 8. Merchant gives the phone to the customer so the customer can sign for the payment. The customer signs and hands back the phone.
251 | 9. Merchant asks the customer if the customer wants a receipt, and Merchant can choose to send the receipt.
252 | * 
253 | 10. A confirmation is displayed, and when Merchant chooses **Done**, the following occurs: PayPal Here re-launches the order-entry app by calling the URL that was passed in as the return URL in the original call to the PayPal Here app. In that URL, PayPal Here includes the status of the transaction, so the order-entry app can display the status (see the Type output field in the _Call Reference_). If the payment was unsuccessful, the order-entry app records the lack of success and restarts at an appropriate step above.
254 |
255 |
256 | ## Appendix A: Sample HTML and Javascript Code
257 |
258 | The following code is an example of a call to the PayPal Here mobile app URL (`paypalhere://takePayment?`). The input fields include an invoice, as a Base64-encoded JSON object. **Note:** This code has references to standard javascript libraries.
259 |
260 | * [sample.html](./sample.html)
261 |
262 |
263 | ## Appendix B: Function for URL-Encoding in Objective-C
264 |
265 | For apps written in Objective-C, the following function shows how to URL-encode data (for the data of your input fields).
266 |
267 | ```Objective-c
268 |
269 | - (NSString *)urlEncode:(NSString *)rawStr {
270 | NSString *encodedStr = (NSString *)CFBridgingRelease(
271 | CFURLCreateStringByAddingPercentEscapes(
272 | NULL,
273 | (__bridge CFStringRef)rawStr,
274 | NULL,
275 | (CFStringRef)@"!*'();:@&=+$,/?%#[]",
276 | kCFStringEncodingUTF8));
277 | return encodedStr;
278 | }
279 |
280 |
281 | ```
282 |
283 | ## Appendix C: Sample Code in Objective-C
284 | The following is sample code in Objective-C that works with the PayPal Here mobile apps API.
285 |
286 | **Important:** Also see the complete sample app provided in this repository.
287 |
288 | For an example of how to do correct URL-encoding, see _Appendix B: Function for URL Encoding in Objective-C_.
289 |
290 | This sample code uses the JSONKit parser, but your app may use a different JSON parser instead.
291 |
292 | ```Objective-c
293 |
294 | // Step 1: Create Invoice JSON Object
295 | // Invoice contains an array of items
296 | NSMutableDictionary *itemListDictionary = [NSMutableDictionary dictionary];
297 | NSMutableArray *itemListArray = [NSMutableArray arrayWithCapacity:1];
298 | NSMutableDictionary *item = [NSMutableDictionary dictionary];
299 | // Create an item
300 | [item setObject:@"8.50" forKey:@"taxRate"];
301 | [item setObject:@"T-shirt" forKey:@"name"];
302 | [item setObject:@"Blue T-shirt" forKey:@"description"];
303 | [item setObject:@"15.99" forKey:@"unitPrice"];
304 | [item setObject:@"Tax" forKey:@"taxName"];
305 | [item setObject:@"1" forKey:@"quantity"];
306 | // Add the item to the dictionary
307 | [itemListArray addObject:item];
308 | // TODO: More items can be added as needed
309 | [itemListDictionary setObject:itemListArray forKey:@"item"];
310 | // Create invoice
311 | NSMutableDictionary *invoiceObj = [NSMutableDictionary dictionary];
312 | // Add invoice details including items from above
313 | [invoiceObj setObject:@"DueOnReceipt" forKey:@"paymentTerms"];
314 | [invoiceObj setObject:@"0" forKey:@"discountPercent"];
315 | [invoiceObj setObject:@"USD" forKey:@"currencyCode"];
316 | [invoiceObj setObject:@"9876" forKey:@"number"];
317 | [invoiceObj setObject:@"foo@bar.com" forKey:@"payerEmail"];
318 | [invoiceObj setObject:itemListDictionary forKey:@"itemList"];
319 |
320 | // Step 2:Prepare request data
321 | // Convert the Invoice object into JSON - this sample uses NSJSONSerialization but any JSON parser (JSONKit) can be used
322 | NSError *e = nil;
323 | NSData *jsonData = [NSJSONSerialization dataWithJSONObject:invoiceObj options:0 error:&e];
324 | NSString *jsonDataStr = [[NSString alloc]initWithData:jsonData encoding:NSUTF8StringEncoding];
325 | // url encode the invoice object
326 | NSString *encodedInvoiceJsonString = [self urlEncode:jsonDataStr];
327 | // urlencode the accepted payment types
328 | NSString *encodedAcceptedPaymentTypes = [self urlEncode:@"cash,card,paypal"];
329 | // TODO: Update URL below to match with your application URL Scheme
330 | // This is how PayPalHere will launch your application
331 | NSString *returnUrl = @"myapp://my-return-handler?{result}Type={Type}&InvoiceId={InvoiceId}&Tip={Tip}&Email={Email}&TxId={TxId}";
332 | NSString *encodedReturnUrl = [self urlEncode:returnUrl];
333 | // Create PayPal Here launch URL
334 | NSString *pphUrlString = [NSString stringWithFormat:@"paypalhere://takePayment?accepted=%@&returnUrl=%@&invoice=%@&step=choosePayment",
335 | encodedAcceptedPaymentTypes, encodedReturnUrl, encodedInvoiceJsonString];
336 | NSLog(@"PayPal Here URL = %@", pphUrlString);
337 | // Create URL object from string
338 | NSURL * pphUrl = [NSURL URLWithString:pphUrlString];
339 |
340 | // Step 3: Launch PayPal Here application
341 | UIApplication * ourApplication = [UIApplication sharedApplication];
342 | // Check if PayPal Here app is installed
343 | if ([ourApplication canOpenURL:pphUrl]){
344 | // Launch PayPal Here app
345 | [ourApplication openURL:pphUrl];
346 | } else {
347 | // Handle case when PayPal Here app is not installed
348 | // or launch PayPal Here app page in appstore:
349 | // http://itunes.apple.com/us/app/paypal-here/id505911015
350 | }
351 |
352 | ```
353 |
354 | ### Appendix D: Confirming the PayPal Here App Is Installed on a Device
355 |
356 | * If your app uses HTML and JavaScript, and the launch of the PayPal Here app fails, your app should direct users to the app store.
357 | * If your app is written for Android, and the Paypal Here app cannot be launched, your app should direct users to the Play Store.
358 |
359 | If your app is written in Objective-C or Swift, you can use the `canOpenURL` function in the [UIApplication class](https://developer.apple.com/library/ios/DOCUMENTATION/UIKit/Reference/UIApplication_Class/Reference/Reference.html) to confirm that the PayPal Here app is installed and then launch it, and if necessary direct users to the app store. For example:
360 |
361 | ```Objective-c
362 |
363 | UIApplication *ourApplication = [UIApplication sharedApplication];
364 | NSString *ourPath = [@"paypalhere://" stringByAppendingString:urlInfo];
365 | NSURL *ourURL = [NSURL URLWithString:ourPath];
366 | if ([ourApplication canOpenURL:ourURL]) {
367 | [ourApplication openURL:ourURL];
368 | } else {
369 | //Display error
370 | UIAlertView *alertView = [[UIAlertView alloc] initWithTitle:@"PayPal Here Not Found"
371 | message:@"The PayPal Here App is not installed. It must be installed to take payment."
372 | delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
373 | [alertView show];
374 | [alertView release];
375 | }
376 | ```
377 |
378 |
379 | ## Order and Payment Flow
380 |
381 | **Important:** For a more detailed explanation of the order and payment flow, see the following user-experience document:
382 |
383 | * PayPal Here Mobile Apps API: Payment Flow Example (Filename: _PayPal Here Mobile Apps API - Payment flow Example.pdf_)
384 |
385 | This section uses an example of charging a credit card to outline steps for:
386 |
387 | * Using an order-entry app to send an invoice to the PayPal Here app
388 | * Accepting a payment in the PayPal Here app
389 |
390 | After the merchant accepts the payment, your order-entry app is re-launched so the merchant can
391 | confirm that the payment was successfully recorded in the order-entry app.
392 |
393 | The following steps describe a version of an order and payment flow.
394 |
395 | 1. Merchant starts the order-entry app and brings up an order.
396 | 2. Merchant chooses **Pay** in the order-entry app.
397 | 3. The order-entry app uses the following URL and fields to launch the PayPal Here app:
398 | `paypalhere://takePayment?[URL-encoded input fields]&invoice=[invoice as a base64-encoded JSON object]`
399 | 4. Merchant logs into Merchant’s PayPal account. On the Charge screen, the PayPal Here app displays the items and amounts of the order.
400 | *
401 | 5. In the PayPal Here app, Merchant chooses **Charge**.
402 | 6. . On the Payment Options screen, the Merchant can choose Card, or swipe the card. If the Merchant chooses a different option on the following screen, subsequent steps would differ from those below.
403 | *
404 | 7. On the Card Info screen, Merchant can swipe the credit card, as in this example. If Merchant keys in the card or uses a different payment method, the screens are different.
405 | 8. Merchant gives the phone to the customer so the customer can sign for the payment. The customer signs and hands back the phone.
406 | 9. Merchant asks the customer if the customer wants a receipt, and Merchant can choose to send the receipt.
407 | *
408 | 10. A confirmation is displayed, and when Merchant chooses **Done**, the following occurs: PayPal Here re-launches the order-entry app by calling the URL that was passed in as the return URL in the original call to the PayPal Here app. In that URL, PayPal Here includes the status of the transaction, so the order-entry app can display the status (see the Type output field in the _Call Reference_). If the payment was unsuccessful, the order-entry app records the lack of success and restarts at an appropriate step above.
409 |
410 |
411 |
412 | ## Call Reference
413 |
414 | Your order-entry app can send an invoice to the PayPal Here app. For a description of this process, in this document, see Send an Invoice to the PayPal Here Mobile App.
415 |
416 |
417 | ### Input Fields
418 |
419 | | Input field name | Description | Comment |
420 | | ------------- | ----------- | ------- |
421 | | accepted | The payment methods to be offered in the PayPal Here app (i.e., the values that you specify will determine the payment methods offered). Acceptable values are `cash`, `card`, `invoice`, `check`, and `paypal`. | Individual countries may not allow certain payment methods. This field is optional. |
422 | | returnUrl | The URL of your app (or mobile web page, email, short URL, SMS, or anywhere a URL can be used). This value must be a well-formatted URL. The user is sent to this URL after the payment is completed (or the transaction is cancelled). **See _“Structuring the returnUrl Input Field,”_ below.** The URL can include placeholders (using curly braces), which will be replaced with desired transaction information. | This field is optional. |
423 | | as | Set the optional `as` input field to `b64` if you will Base64-encode the JSON invoice object. If you won’t Base64-encode the JSON invoice object, omit the as parameter. Base-64 encoding (used if you specify `as=b64`) is recommended for the JSON invoice object (as an alternative to URL-encoding) because Base-64 encoding is more likely to result in correct encoding. | For information about the JSON invoice object, see `invoice`, below. |
424 | | step | Stage within the PayPal Here app at which the merchant will begin. Specify `step=choosePayment` | |
425 | | invoice | A JSON object that contains the invoice data. | See the following section of this document: _Invoice as a JSON object_ |
426 | | payerPhone | If the buyer email address is known ahead of time, this can be specified in the invoice directly. However, if the buyer's phone number is known and your app desires an SMS receipt to be offered to them, the `payerPhone` field will be used to pre-fill that field in US format. | |
427 |
428 |
429 | ### Structuring the `returnUrl` Input Field
430 |
431 | The data for the `returnUrl` input field is a URL that can include placeholders for the desired transaction information. That is, you can use curly braces in the URL for the PayPal Here app to return specific data about the transaction. The following table provides information about this data. For an example, see _URL-Encoded Input Fields_.
432 |
433 | | Field of the `returnUrl` input field | Description |
434 | | ------------- | ----------- |
435 | | Root URL of your app, including the call that was invoked by your app. Example: `my_registered_location://takePayment` | The PayPal Here app uses this value to return the merchant to your app, after payment |
436 | | `{result}?` | The fields whose values you want returned by the PayPal Here app |
437 | | `Type` | The type of payment made, e.g. `card`. Specify `Type={Type}` |
438 | | `InvoiceId` | The invoice ID. Specify `InvoiceId={InvoiceId}` |
439 | | `Tip` | The tip, if applicable. `Specify Tip={Tip}` |
440 | | `TxId` | The tax ID of the merchant. Specify `TxId={TxId}` |
441 | | `Email` | Email of buyer, if available. Specifiy `Email={Email}` |
442 |
443 |
444 | ### Output Fields
445 |
446 | | Input field name | Description |
447 | | ---------------- | ----------- |
448 | | `Type` | The payment method, for example `SWIPE`. Returned values are listed below, but your code should be able to handle new values as they get introduced. If the transaction was interrupted, for example if a credit card was declined, the value is `UNKNOWN`. Note: If a credit card is declined, the merchant can enter an alternative payment method.
If the merchant cancels, the order-entry’s return URL is called, appended with `Type=Unknown`.
Due to legacy issues, the values for "Type" currently differ based on the version being used.
On PayPal Here versions 2.x, these values can be: `UNKNOWN`, `KEY`, `SCAN`, `SWIPE`, `PAYPAL`, `CHECK`, `CASH`, `CHIP`, `EMV_SWIPE`.
On iPad 1.x, these values can be: `Unknown`, `CreditCard`, `Check`, `Cash`, `PayPal`, `DebitCard`, `Other`, `ChipCard`.
For iPad versions 2.3 and later, the values are consistent with iPhone.
You should code your integrations to handle new values being returned in this field.| 449 | | `InvoiceId` | The ID of the new invoice for which payment was accepted. For information about the input value that corresponds to this ID, see __Invoice as a JSON object. | 450 | | `Tip` | The monetary value tip, if applicable. | 451 | | `Email` | Buyer email, if available. | 452 | 453 | 454 | ## Appendix A: Sample HTML and Javascript Code 455 | 456 | The following code is an example of a call to the PayPal Here mobile app URL (`paypalhere://takePayment?`). The input fields include an invoice, as a Base64-encoded JSON object. **Note:** This code has references to standard javascript libraries. 457 | 458 | * [sample.html](./sample.html) 459 | 460 | 461 | 462 | ## Appendix B: Function for URL-Encoding in Objective-C 463 | 464 | For apps written in Objective-C, the following function shows how to URL-encode data (for the data of your input fields). 465 | 466 | ```Objective-c 467 | 468 | - (NSString *)urlEncode:(NSString *)rawStr { 469 | NSString *encodedStr = (NSString *)CFBridgingRelease( 470 | CFURLCreateStringByAddingPercentEscapes( 471 | NULL, 472 | (__bridge CFStringRef)rawStr, 473 | NULL, 474 | (CFStringRef)@"!*'();:@&=+$,/?%#[]", 475 | kCFStringEncodingUTF8)); 476 | return encodedStr; 477 | } 478 | 479 | 480 | ``` 481 | -------------------------------------------------------------------------------- /docs/sample.html: -------------------------------------------------------------------------------- 1 | 2 | 3 |
15 |
17 |
18 |
32 |
33 |
34 |
35 | Your cart
16 || 20 | | Name | 21 |Price | 22 |Quantity | 23 |
|---|---|---|---|
| {{item.name}} | 28 |{{item.price}} | 29 |{{item.quantity}} | 30 |
',trigger:"hover focus",title:"",delay:0,html:!1,container:!1},e.fn.tooltip.noConflict=function(){return e.fn.tooltip=n,this}}(window.jQuery),!function(e){"use strict";var t=function(e,t){this.init("popover",e,t)};t.prototype=e.extend({},e.fn.tooltip.Constructor.prototype,{constructor:t,setContent:function(){var e=this.tip(),t=this.getTitle(),n=this.getContent();e.find(".popover-title")[this.options.html?"html":"text"](t),e.find(".popover-content")[this.options.html?"html":"text"](n),e.removeClass("fade top bottom left right in")},hasContent:function(){return this.getTitle()||this.getContent()},getContent:function(){var e,t=this.$element,n=this.options;return e=(typeof n.content=="function"?n.content.call(t[0]):n.content)||t.attr("data-content"),e},tip:function(){return this.$tip||(this.$tip=e(this.options.template)),this.$tip},destroy:function(){this.hide().$element.off("."+this.type).removeData(this.type)}});var n=e.fn.popover;e.fn.popover=function(n){return this.each(function(){var r=e(this),i=r.data("popover"),s=typeof n=="object"&&n;i||r.data("popover",i=new t(this,s)),typeof n=="string"&&i[n]()})},e.fn.popover.Constructor=t,e.fn.popover.defaults=e.extend({},e.fn.tooltip.defaults,{placement:"right",trigger:"click",content:"",template:'
'}),e.fn.popover.noConflict=function(){return e.fn.popover=n,this}}(window.jQuery),!function(e){"use strict";function t(t,n){var r=e.proxy(this.process,this),i=e(t).is("body")?e(window):e(t),s;this.options=e.extend({},e.fn.scrollspy.defaults,n),this.$scrollElement=i.on("scroll.scroll-spy.data-api",r),this.selector=(this.options.target||(s=e(t).attr("href"))&&s.replace(/.*(?=#[^\s]+$)/,"")||"")+" .nav li > a",this.$body=e("body"),this.refresh(),this.process()}t.prototype={constructor:t,refresh:function(){var t=this,n;this.offsets=e([]),this.targets=e([]),n=this.$body.find(this.selector).map(function(){var n=e(this),r=n.data("target")||n.attr("href"),i=/^#\w/.test(r)&&e(r);return i&&i.length&&[[i.position().top+(!e.isWindow(t.$scrollElement.get(0))&&t.$scrollElement.scrollTop()),r]]||null}).sort(function(e,t){return e[0]-t[0]}).each(function(){t.offsets.push(this[0]),t.targets.push(this[1])})},process:function(){var e=this.$scrollElement.scrollTop()+this.options.offset,t=this.$scrollElement[0].scrollHeight||this.$body[0].scrollHeight,n=t-this.$scrollElement.height(),r=this.offsets,i=this.targets,s=this.activeTarget,o;if(e>=n)return s!=(o=i.last()[0])&&this.activate(o);for(o=r.length;o--;)s!=i[o]&&e>=r[o]&&(!r[o+1]||e<=r[o+1])&&this.activate(i[o])},activate:function(t){var n,r;this.activeTarget=t,e(this.selector).parent(".active").removeClass("active"),r=this.selector+'[data-target="'+t+'"],'+this.selector+'[href="'+t+'"]',n=e(r).parent("li").addClass("active"),n.parent(".dropdown-menu").length&&(n=n.closest("li.dropdown").addClass("active")),n.trigger("activate")}};var n=e.fn.scrollspy;e.fn.scrollspy=function(n){return this.each(function(){var r=e(this),i=r.data("scrollspy"),s=typeof n=="object"&&n;i||r.data("scrollspy",i=new t(this,s)),typeof n=="string"&&i[n]()})},e.fn.scrollspy.Constructor=t,e.fn.scrollspy.defaults={offset:10},e.fn.scrollspy.noConflict=function(){return e.fn.scrollspy=n,this},e(window).on("load",function(){e('[data-spy="scroll"]').each(function(){var t=e(this);t.scrollspy(t.data())})})}(window.jQuery),!function(e){"use strict";var t=function(t){this.element=e(t)};t.prototype={constructor:t,show:function(){var t=this.element,n=t.closest("ul:not(.dropdown-menu)"),r=t.attr("data-target"),i,s,o;r||(r=t.attr("href"),r=r&&r.replace(/.*(?=#[^\s]*$)/,""));if(t.parent("li").hasClass("active"))return;i=n.find(".active:last a")[0],o=e.Event("show",{relatedTarget:i}),t.trigger(o);if(o.isDefaultPrevented())return;s=e(r),this.activate(t.parent("li"),n),this.activate(s,s.parent(),function(){t.trigger({type:"shown",relatedTarget:i})})},activate:function(t,n,r){function o(){i.removeClass("active").find("> .dropdown-menu > .active").removeClass("active"),t.addClass("active"),s?(t[0].offsetWidth,t.addClass("in")):t.removeClass("fade"),t.parent(".dropdown-menu")&&t.closest("li.dropdown").addClass("active"),r&&r()}var i=n.find("> .active"),s=r&&e.support.transition&&i.hasClass("fade");s?i.one(e.support.transition.end,o):o(),i.removeClass("in")}};var n=e.fn.tab;e.fn.tab=function(n){return this.each(function(){var r=e(this),i=r.data("tab");i||r.data("tab",i=new t(this)),typeof n=="string"&&i[n]()})},e.fn.tab.Constructor=t,e.fn.tab.noConflict=function(){return e.fn.tab=n,this},e(document).on("click.tab.data-api",'[data-toggle="tab"], [data-toggle="pill"]',function(t){t.preventDefault(),e(this).tab("show")})}(window.jQuery),!function(e){"use strict";var t=function(t,n){this.$element=e(t),this.options=e.extend({},e.fn.typeahead.defaults,n),this.matcher=this.options.matcher||this.matcher,this.sorter=this.options.sorter||this.sorter,this.highlighter=this.options.highlighter||this.highlighter,this.updater=this.options.updater||this.updater,this.source=this.options.source,this.$menu=e(this.options.menu),this.shown=!1,this.listen()};t.prototype={constructor:t,select:function(){var e=this.$menu.find(".active").attr("data-value");return this.$element.val(this.updater(e)).change(),this.hide()},updater:function(e){return e},show:function(){var t=e.extend({},this.$element.position(),{height:this.$element[0].offsetHeight});return this.$menu.insertAfter(this.$element).css({top:t.top+t.height,left:t.left}).show(),this.shown=!0,this},hide:function(){return this.$menu.hide(),this.shown=!1,this},lookup:function(t){var n;return this.query=this.$element.val(),!this.query||this.query.length