iOS/Android SDK

Important: PayPal Here is deprecated. PayPal doesn't accept new integrations but continues to support existing integrations.

Work with the SDK

To prepare to process transactions with the SDK for the first time, an app must complete these setup operations:

1. Initialize the SDK each time the app starts.
2. Initialize the merchant by passing their credentials into the SDK.
3. Find and Connect to a card reader (for card-present transactions).

After setup is complete, an app must complete these steps to process a basic card-present transaction:

1. Create an invoice.
2. Add items to the invoice.
3. Take a payment using a credit card reader.
4. Capture the customer's signature, if required for the transaction.
5. Send a receipt.

Note: The SDK provides the UI to capture the signature and display the receipt options.

Note: These are samples only. You should review the sample apps to see how they are used in an actual application.

Initialize the SDK, merchant, and device

1. Initialize the SDK.

1PayPalRetailSDK.initializeSDK()

2. Initialize the merchant. You pass an SdkCredential object, which includes the access token, refresh URL, and the environment. For details, see Token Management.

   Note: For iOS, initializeMerchant also initializes the SDK if it is not already initialized. For iOS, you can call initializeMerchant directly without calling initializeSDK.

1let sdkCreds = SdkCredential.init(accessToken: "access token of merchant", refreshUrl: "refresh URL to use to refresh access token after expiry", environment: "either live or sandbox")
2PayPalRetailSDK.initializeMerchant(withCredentials: sdkCreds) { (error, merchant) in
3    // Code to handle success or failure
4    // To continue, this must succeed
5}

3. Device discovery. After you initialize the SDK and merchant, connect to a card reader. The following code demonstrates how to connect:

   • You can look for the last known reader.
   • You can search for a reader.
   • You can auto-connect to the last known reader.

   Note: When you use the auto connect method, no SDK UI appears to select a reader because it tries to connect in the background. If you cannot connect to the last known reader, you must use one of the other methods.

1// previous declaration of deviceManager
2let deviceManager = PayPalRetailSDK.deviceManager()
3// code to connect to last known reader or find another
4deviceManager.connect(toLastActiveReader: { (error, paymentDevice) -> Void in
5    // Code to handle success or failure
6    // On error, check the error and retry
7    // On success for a Bluetooth reader, check for software update
8})
9// code to search and connect
10deviceManager.searchAndConnect({ (error, paymentDevice) -> Void in
11    // Code to handle success or failure
12    // On error, check the error and retry
13    // On success for a Bluetooth reader, check for software update
14})
15// code to auto-connect to the last known reader
16let lastActiveReader = deviceManager?.getLastActiveBluetoothReader()
17deviceManager.scanAndAutoConnect(toBluetoothReader: lastActiveReader, callback: { (error, paymentDevice) in
18    // Code to handle success or failure
19    // On error, check error and connect by another method
20    // On success for a Bluetooth reader, check for software update
21})

4. Reader firmware update. If the connected card reader is a Bluetooth reader, you must check for and start the firmware update.

1reader.pendingUpdate.offer({ (error, updateComplete) in
2    // Code to handle success or failure
3    // On error, check the error and retry
4    // On success, continue with the payment flow
5})

SDK capabilities

Payment

1. Create an invoice. Be sure to provide a unique invoice number to protect against duplicate transactions.

1var invoice: PPRetailInvoice?
2invoice = PPRetailInvoice.init(currencyCode: "USD")
3invoice.addItem("My Order", quantity: 1, unitPrice: 1.00, itemId: 123, detailId: nil)
4invoice.number = "unique_invoice_number"

2. Create a TransactionContext using the previously created invoice.

1var tc: PPRetailTransactionContext?
2PayPalRetailSDK.transactionManager().createTransaction(invoice, callback: { (error, context) in
3    // On error, handle error. Else, set transaction context to call beginPayment in next step
4    self.tc = context
5})

3. Accept a transaction. This part activates the reader so that the customer can select their payment method and then also adds the listeners that will fire when the payment method is chosen.

1// Listener called once the transaction is completed
2tc.setCompletedHandler { (error, txnRecord) -> Void in
3    // if error, handle accordingly, else pop back to view controller and handle success
4    self.navigationController?.popToViewController(self, animated: false)
5    // txnRecord would have any info needed to record the successful transaction
6}
7// Setting up the options for the transaction.
8let options = PPRetailTransactionBeginOptions()
9options.showPromptInCardReader = true
10options.showPromptInApp = true
11options.preferredFormFactors = []
12options.tippingOnReaderEnabled = false
13options.amountBasedTipping = false
14options.isAuthCapture = false
15options.quickChipEnabled = false
16// Activates the reader to show the payment options
17tc.beginPayment(options)

Offline payment

This feature is currently only available to US merchants.

Important: To use offline payments, you must enable it on your PayPal account. To enable it, send your account email address and a business case to use offline payments to pph-sdk@paypal.com.

Offline mode is only available with EMV-capable card readers. Also, offline mode forces the supported card readers to only accept swipe transactions.

To use the offline payments feature, your app must check for Internet connectivity. If you have no connectivity, your app must request that the PayPal Here SDK store the transaction as offline on the mobile device. When the Internet connectivity is regained, your app must request that PayPal Here SDK process the pending offline transaction.

You are subject to the following limits on activity with the offline payments feature:

• You can only process transactions under USD $5,000.
• You can only process a total of USD $50,000.
• You must reconnect to the Internet within 24 hours or the offline transactions expire.

These limits are subject to change at PayPal's sole discretion. PayPal informs you of changes by email.

As a partner, your end-user merchants assume all liability for any offline transactions, including those that are subsequently declined, expired, or disputed. Your end-user merchants cannot dispute declined offline transactions. Your end-user merchants also assume all liability for offline transactions if the device is lost, stolen, damaged, or you delete your app before re-connecting to the Internet. Any refunds are processed in the normal course after your end user merchants are re-connected to the Internet.

Before you enable the offline payments feature, you agree to communicate these terms and conditions to your end users and secure their agreement to those terms and conditions before your end users can use the feature.

1. Merchant initialization If you have an Internet connection and can call initializeMerchant successfully, you can proceed to step 2 to enable offline mode. You do not need to call initializeMerchantOffline if you've already completed a successful online merchant initialization. However, if you do not have an Internet connection to call initializeMerchant, you can call intializeMerchantOffline to successfully initialize the merchant before processing offline transactions.

Notes:

• Call initializeMerchantOffline only if you cannot initially call initializeMerchant.

• You can complete an offline merchant initialization only after successfully completing at least one online merchant initialization on the device.

• If you cannot initially call initializeMerchant and instead called initializeMerchantOffline, you must call initializeMerchant before replaying offline transactions. Before you can process online transactions, online merchant initialization must succeed.

1PayPalRetailSDK.initializeMerchantOffline { (error, merchant) in
2    // Code to handle success or failure
3}

2. Enable offline payments to accept payments when you have no internet connection. This will start the offline processing of transactions and save them on the device.

1PayPalRetailSDK.transactionManager().startOfflinePayment(callback: { (error, offlinePaymentInfo) in
2    // Code to handle success or failure
3})

3. Create a TransactionContext using the previously created invoice in the same way as one would for a normal payment.

4. Accept a transaction in the same way as a normal payment. For offline payments the reader will only accept swipe transactions at this time. Transaction options are not available when processing offline payments and also there is a separate completed handler for offline payments.

1tc.setOfflineTransactionAdditionHandler({ (error, txnRecord) in
2     // if error, handle accordingly, else pop back to view controller and handle success
3    self.navigationController?.popToViewController(self, animated: false)
4    // txnRecord would have any info needed to record the successful offline saved transaction
5})

5. Check the status of the offline payment saved on the device.

1PayPalRetailSDK.transactionManager().getOfflinePaymentStatus(callback: { (error, offlinePaymentInfo) in
2    // Code to handle success or failure
3})

6. Start processing the offline payments.

1PayPalRetailSDK.transactionManager().startReplayOfflineTxns(callback: { (error, offlinePaymentInfo) in
2    // Code to handle success or failure of the offline replay
3})

7. Stop processing the offline payments at any time.

1PayPalRetailSDK.transactionManager().stopReplayOfflineTxns(callback: { (error, info) in
2    // Status of the remaining offline transactions
3})

8. Disable offline payments.

Note: The SDK is brought back into online mode once startReplayOfflineTxns is called. When this happens, the app does not need to call stopOfflinePayment to return to online mode.

1PayPalRetailSDK.transactionManager().stopOfflinePayment({ (error, info) in
2  // Status of the remaining offline transactions
3})

Refund

Refunds can either be done within your app or you can use our Refund API to incorporate refund functionality in your back-office. These steps outline how to complete a refund within your app:

1. Create a TransactionContext for the invoice you would like to refund. The createRefundTransaction method takes in the following parameters: PayPal invoice ID, transaction ID, payment method of the transaction, and a callback handler.

1PayPalRetailSDK.transactionManager().createRefundTransaction(paypalInvoiceId, transactionNumber: transactionNumber, paymentMethod: paymentMethod, callback: refundHandler)

The callback handler accepts an error object and transaction context. If the error object is not nil, then handle accordingly. Otherwise, use the transaction context to call beginRefund.

2. Call into beginRefund to determine whether the card is present for the refund, and to process the refund. This code would be used as part of the callbacks mentioned in the createRefundTransaction method.

1// Listener that gets called once the refund processes
2tc.setCompletedHandler { (error, txnRecord) -> Void in
3    // if error, handle accordingly, else pop back to view controller and handle success
4    self.navigationController?.popToViewController(self, animated: false)
5    // txnRecord would have any info needed to record the successful refund
6}
7// Begins refund process and asks if a card is present for the refund
8tc.beginRefund(true, amount: refundAmount)

Additional capabilities

The SDK also supports several additional capabilities:

• Adding a referrer code to a transaction
• Accepting keyed-in card payments
• Adding a unique invoice ID to a transaction

When your integration is complete, check the going live page to ensure that you have everything ready for activation. Once that is working, you can implement other customizations that are available with the SDK into your integration.