Working with the SDK

This section describes how to set up an app and how an app processes a payment.

Setting up an app

To set up an app:

  1. Initialize the SDK (each time the app starts).
  2. Authenticate the merchant and pass the merchant's credentials to the SDK (the first time the merchant uses the app).
  3. Start monitoring the card reader for events (for card present transactions).

Initialize the SDK

To initialize the SDK, send a selectEnvironmentWithType message to PayPalHereSDK:

[PayPalHereSDK selectEnvironmentWithType:environment_type]
  • environment_type. The environment type. A valid value is:
    • ePPHSDKServiceType_Sandbox for the Sandbox environment.
    • ePPHSDKServiceType_Live for the live environment.

The SDK logging facility logs various messages to a remote logging facility. You can choose the types of messages to log and add your own decorations to the messages by defining a class that implements the PPHLoggingDelegate protocol and passing an instance of it to PayPalHereSDK.setLoggingDelegate.

[PayPalHereSDK setLoggingDelegate:instance]

In SDKSampleApp, STAppDelegate.m implements the protocol methods and sets the logging delegate to self.

Authenticate the merchant

Authenticating SDK operations describes authentication. Most steps involve calls to OAuth (How PayPal uses OAuth 2.0) or to the sample mid-tier server.

Set the active merchant

After the app authenticates the server, it calls PayPalHereSDK.setActiveMerchant to set the merchant for which transactions are run.

[PayPalHereSDK setActiveMerchant:merchant with MerchantId:merchantId completionHander: handler ]
  • merchant. An id for the merchant information, including the OAuth credentials.
  • merchantId. An id for the merchant. It is defined by agreement between the mid-tier server and the app (not by the SDK), and must be unique among the merchants that use the mid-tier server and the app.
  • handler. An id for a completion handler to be called when merchant setup is completed.

Authorization and capture

Authorization and capture (auth/cap for short) allows you authorize a transaction and then capture the payment at a later time. This enables you to authorize a transaction before its exact amount is known.

In one common use case a merchant accepts a credit card from a customer, authorizes a transaction, and presents a receipt to the customer who adds a gratuity. The merchant can then compute the total amount and capture payment.

Setting up a payment authorization

All auth/cap requests use an access token for authentication, the same as the rest of the PayPal Here SDK. For an outline of PayPal Here authentication procedures and references to more detailed information, see Authenticating SDK operations.

To set up a payment authorization for a transaction:

  1. Initialize the SDK, start a transaction, set an amount, and define an invoice in the usual way.

  2. Instead of taking payment in the usual way, call the transaction manager's authorizePaymentWithPaymentType method:

    [tm authorizePaymentWithPaymentType:ePPHPaymentMethodKey
      withCompletionHandler:^(PPHTransactionResponse *response) {
        if (!response.error) { self.auth = response.record }
      };
    ];  
    
    • ePPHPaymentMethodKey. The type of payment.
    • The second parameter. A standard completion handler.
  3. If the completion handler receives a ;no error response, the response's record property contains a pointer to a PPHTransactionRecord. Save the pointer for later use.

Working with authorized payments

After you authorize a payment, you can:

  • Capture the authorized payment
  • Void the authorization (before payment is captured)
  • Refund part or all of the payment (after payment is captured)
Capturing payment

To capture payment for an authorized transaction, call capturePaymentForAuthorization:

[tm capturePaymentForAuthorization:transactionRecord
  withCompletionHandler:^(PPHTransactionResponse *response) {
  }
];
  • transactionRecord. The transaction record returned from the authorization call.
  • The second parameter. A standard completion handler.

The amount captured is determined by the invoice (the PPHInvoice object) associated with the transactionRecord. The amount may exceed the original authorized amount by a percentage to allow for adding a typical gratuity. The percentage is determined by the type and characteristics of the merchant, and cannot be changed through the SDK.

Note that you can also include an amount alongside the transactionRecord to capture more or less than the authorized amount.

Voiding an authorization

To void an authorization before the payment has been captured, call the transaction manager's voidAuthorization method:

[tm voidAuthorization:transactionRecord
  withCompletionHandler:^(PPHTransactionResponse *response) {
  }
];
  • transactionRecord. The transaction record returned from the authorization call.
  • The second parameter. A standard completion handler.
Refunding a captured payment

To refund part of a captured payment, call the transaction manager's beginRefund method:

[tm beginRefund:transactionID
    forAmount:amount
    completionHandler:^(PPHTransactionResponse *response) {
    }
];
  • transactionID. The transaction ID of the transaction to be refunded.
  • amount. The amount to refund, as a string. For example, specify 1.00 to refund one dollar. To refund the entire amount, specify nil.
  • The third parameter. A standard completion handler.

Additional capabilities

This section describes several additional capabilities of the SDK which you can use with transactions.

Refunding a payment

This section describes the ways to refund a payment.

Refunding Mag stripe transactions (SDKSampleApp)

To refund a payment, call the PPHTransactionManager class beginRefund method.

[tm beginRefund:transactionID forAmount:amount completionHandler:handler];
  • transactionID. The transaction ID of the transaction to be refunded.
  • amount. A PPHAmount that specifies the amount to be refunded. To refund the entire amount of the transaction, specify nil.
  • handler. A completion handler.

Refunding EMV transactions (EMVAccreditationSampleApp)

To refund a payment, call the PPHTransactionManager class beginRefundUsingSDKUI_WithPaymentType method.

[tm beginRefundUsingSDKUI_WithPaymentType:ePPHPaymentMethodChipCard
  withViewController:viewController record:transactionRecord
  amount:amount completionHandler:handler];
  • ePPHPaymentMethodChipCard. The type of payment being refunded (a payment with an EMV card).
  • viewController. A class that implements how the refund is displayed.
  • transactionRecord. The transaction record returned by the transaction to be refunded.
  • amount. A PPHAmount that specifies the amount to be refunded. To refund the entire amount of the transaction, specify nil.
  • handler. A completion handler.

The method returns a new transaction record that represents the refund.

Authorized captured payments

Refunding a payment describes how to refund an authorized, captured payment.

Adding a referrer code (BN code or attribution code)

A developer partner's integration with PayPal can be identified with a referrer code (also known as a build notation code, BN code, or attribution code). If your app sets a referrer code when it initializes the PayPal Here SDK, the SDK will include the referrer code in each call that it makes to a PayPal API.

A referrer code can help you capture information about how your clients use your software. This information is essential if your organization charges use-based fees, and it can also help you analyze how your software is being used.

You can obtain a referrer code from your account manager. To set it during SDK setup, call the setReferrerCode method of the PayPalHereSDK class.

[PayPalHereSDK setReferrerCode withCode:referrerCode]
  • referrerCode. Pointer to your referrer code, which is ordinarily an NSString.

Adding a cashier ID

You can identify a merchant sub-user in an invoice by specifying a cashier ID. The sub-user is typically the person immediately responsible for the transaction, such as a cashier who takes a payment.

To include a cashier ID in an invoice, store it as an NSString in the PPHInvoice object cashierId property:

Invoice.cashierId = 'cashierID';
  • Invoice.cashierId. A PPHInvoice object.
  • cashierID. A cashier ID.