Manage PayPal QRC payments

The following describes how to work with QRC payments with the Android SDK. Operations include starting, processing, retrieving, and refunding.

Start by creating a unique transaction reference string for each payment, which can be used to trace this payment in our system. Examples are provided in Kotlin.

Important: This unique reference string must be UTF-8 and up to 128 characters, otherwise payment will be denied.

Copy
1
val uiniqueReference = UUID.randomUUID().toString()

Then you need to start PayPalQrcPaymentActivity and use the IntentBuilder to inject the desired configuration for this payment.

Copy
1
val intent = PayPalQrcPaymentActivity.IntentBuilder(this)
2
    // MANDATORY: Transaction amount in account currency
3
    .amount(20000L)
4
    // MANDATORY, Reference object created in previous step
5
    .reference(uiniqueReference)
6
    // OPTIONAL, Payment flow appearance - valid only for US market
7
    .appearance(PayPalQrcType.PayPal)
8
    .build()
9

10
// Start activity with the intent
11
startActivityForResult(intent, 0)

When using PayPal QRC payments, merchants located in the US will have an option to start the payment using PayPal or Venmo UI appearances. This is because consumers can scan the QR code using either the Venmo or PayPal applications. In the payment result, you will be able to extract which payment method was used by the consumer.

You will receive the payment result as an Activity result. The result Bundle contains two values:

The payment result is an instance of one of the following classes described in the following:

• PayPalQrcPaymentResult.Canceled
• PayPalQrcPaymentResult.Failed
• PayPalQrcPaymentResult.Completed

The PayPalQrcPaymentResult is a Kotlin sealed class, meaning it's always one of the following implementations.

The failed and completed results contain more detailed information regarding the failure reason, or the payload of the successful payment.

Extracting the failure reason

The PayPalQrcPaymentResult.Failed contains an instance of PayPalQrcPaymentFailureReason that describes the failure and can contain any of the following reasons.

Extracting the success payload

A successful payment contains a payload of type PayPalQrcPayment with fields describing the payment as listed in the following.

To retrieve a PayPal QRC payment you need to provide the same unique reference ID provided with the payment itself. See Starting PayPal QRC payments.

Copy
1
IZettleSDK.refundsManager.retrievePayPalQrc(activity, uniqueReference, object : RefundsManager.Callback<PayPalQrcPayment, RetrievePayPalQrcFailureReason> {
2
    override fun onFailure(reason: RetrievePayPalQrcFailureReason) {/*...*/}
3
    override fun onSuccess(payment: PayPalQrcPayment) {/*...*/}
4
})

A refund works similar to a payment with the exception that you need to provide the original payment when starting the refund. See Retrieving PayPal QRC payments.

When you have your payment object, you need to create a new unique transaction reference string for each refund. This reference string can be used to trace the refund in our system if needed.

Copy
1
val uniqueRefundReference = UUID.randomUUID().toString()

Important: This unique reference string must be UTF-8 and up to 128 characters, otherwise payment will be denied.

Next step is to start PayPalQrcPaymentActivity. Use the IntentBuilder to inject the desired configuration for this refund.

Copy
1
val intent = PayPalQrcRefundActivity.IntentBuilder(context)
2
    // OPTIONAL: Refund amount in account currency
3
    // This amount must be less or equal to the original card payment.
4
    // If not provided it will use original card payment amount
5
    // NOTE: if not provided, then it will perform a full refund.
6
    .amount(20000L)
7
    // Reference object created in previous step
8
    .reference(uniqueRefundReference)
9
    // Unique reference for the payment that you want to perform refund.
10
    .paymentReference(paymentUniqueRerence)
11
    .build()
12

13
// Start activity with the intent
14
startActivityForResult(intent, 0)

You will receive the refund result as an Activity result. The result Bundle contains two values:

The refund result is an instance of one of the following classes:

• PayPalQrcRefundResult.Canceled
• PayPalQrcRefundResult.Failed
• PayPalQrcRefundResult.Completed

The PayPalQrcRefundResult is a Kotlin sealed class, meaning it's always one of the following implementations.

The failed and completed results contain more detailed information regarding the failure reason, or the payload of a successful refund.

Extracting the failure reason

The PayPalQrcRefundResult.Failed contains an instance of PayPalQrcPaymentFailureReason that describes the failure and can contain any of the following reasons.

Extracting the success payload

A successful refund contains a payload of type PayPalQrcRefund with fields describing the refund as listed in the following.

To start taking PayPal QRC payments, users must first read and promptly accept the terms and conditions from the settings screen.

Copy
1
val intent = PayPalQrcActivationActivity.IntentBuilder(context).build()
2
startActivity(intent)

When integrating with the SDK, you can test your integration in developer mode for PayPal and Venmo QRC without a Zettle merchant account and real transactions.

1. If developer mode is not enabled, enable it by calling the following function in your integration project:

   Copy
   1
   IZettleSDK.init(
   2
       ...,
   3
       isDevMode = true
   4
   )

2. Launch the payment flow.

3. Check the responses.

   The example shows test case "Successfully paid with PayPal".

   Copy
   1
   "payment": {
   2
       "type": "PayPal",
   3
       "transactionId": "3702b69c-5b53-11ed-bb53-e32a574ae480",
   4
       "referenceNumber": "5RD45483J23141148",
   5
       "amount": <the payment amount passed to the SDK>,
   6
       "reference": "<the reference passed to the SDK>"
   7
   }

4. Launch the refund flow.

5. Check the responses.

   The example shows test case "Successful PayPal refund".

   Copy
   1
   "payload": {
   2
       "transactionId": "c1ee606d-5b54-11ed-8c7e-9873cea95625",
   3
       "referenceNumber": "6VE826082H938612A",
   4
       "amount": <the refund amount passed to the SDK>,
   5
       "originalAmount": 1000,
   6
       "type": "PayPal",
   7
       "reference": "<the reference passed to the SDK>"
   8
   }

• Manage card payments
• Developer mode