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.
1val uiniqueReference = UUID.randomUUID().toString()
Then you need to start PayPalQrcPaymentActivity
and use the IntentBuilder
to inject the desired configuration for this payment.
1val intent = PayPalQrcPaymentActivity.IntentBuilder(this)2// MANDATORY: Transaction amount in account currency3.amount(20000L)4// MANDATORY, Reference object created in previous step5.reference(uiniqueReference)6// OPTIONAL, Payment flow appearance - valid only for US market7.appearance(PayPalQrcType.PayPal)8.build()910// Start activity with the intent11startActivityForResult(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:
Name | Type | Description |
---|---|---|
PayPalQrcPaymentActivity.RESULT_EXTRA_REQUEST | Bundle | The extras bundle from request intent. |
PayPalQrcPaymentActivity.RESULT_EXTRA_PAYLOAD | PayPalQrcPaymentResult | The payment result. |
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.
Name | Description |
---|---|
PayPalQrcPaymentResult.Canceled | Payment was canceled by merchant or customer. Doesn't contain any additional data. |
PayPalQrcPaymentResult.Failed | Payment failed. The failure reason is defined by the reason field. |
PayPalQrcPaymentResult.Completed | PayPal QRC payment was successfully completed. Contains transaction info in the payload field. |
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.
Name | Description |
---|---|
PayPalQrcPaymentFailureReason.Timeout | Payment took too long to be completed |
PayPalQrcPaymentFailureReason.TechnicalError | Payment failed because of technical issues such as problems in the communication protocol. |
PayPalQrcPaymentFailureReason.NetworkError | Communication with Zettle servers failed |
PayPalQrcPaymentFailureReason.ActivationNotCompleted | User was not yet onborded to this payment method. |
PayPalQrcPaymentFailureReason.SellerDataError | Found some problems in the merchant information. |
PayPalQrcPaymentFailureReason.FeatureNotEnabled | Currently logged-in user is not allowed to use this payment method, could be the case when merchant is not from one of the supported countries. |
PayPalQrcPaymentFailureReason.AboveMaximum | Requested amount is greater than account limit |
PayPalQrcPaymentFailureReason.BellowMinimum | Requested amount is smaller than allowed minimum |
Extracting the success payload
A successful payment contains a payload of type PayPalQrcPayment
with fields describing the payment as listed in the following.
Name | Type | Description |
---|---|---|
amount | Long | Total transaction amount |
type | PayPalQrcType | The QRC flavor used to perform the payment - PayPal or Venmo (USA only) |
reference | String | The unique reference string provided when payment was started |
referenceNumber | String? | Zettles reference to the payment |
transactionId | String? | The ID for the transaction in the Zettle system. The ID is automatically generated by the Zettle system. |
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.
1IZettleSDK.refundsManager.retrievePayPalQrc(activity, uniqueReference, object : RefundsManager.Callback<PayPalQrcPayment, RetrievePayPalQrcFailureReason> {2override fun onFailure(reason: RetrievePayPalQrcFailureReason) {/*...*/}3override 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.
1val 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.
1val intent = PayPalQrcRefundActivity.IntentBuilder(context)2// OPTIONAL: Refund amount in account currency3// This amount must be less or equal to the original card payment.4// If not provided it will use original card payment amount5// NOTE: if not provided, then it will perform a full refund.6.amount(20000L)7// Reference object created in previous step8.reference(uniqueRefundReference)9// Unique reference for the payment that you want to perform refund.10.paymentReference(paymentUniqueRerence)11.build()1213// Start activity with the intent14startActivityForResult(intent, 0)
You will receive the refund result as an Activity result. The result Bundle
contains two values:
Name | Type | Description |
---|---|---|
PayPalQrcRefundActivity.RESULT_EXTRA_REQUEST | Bundle | The extras bundle from request intent. |
PayPalQrcRefundActivity.RESULT_EXTRA_PAYLOAD | PayPalQrcRefundResult | The refund result. |
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.
Name | Description |
---|---|
PayPalQrcRefundResult.Canceled | Refund was canceled by merchant or customer. Doesn't contain any additional data. |
PayPalQrcRefundResult.Failed | Refund failed. The failure reason is defined by the reason field. |
PayPalQrcRefundResult.Completed | Refund was successfully completed. Contains transaction info in the payload field. |
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.
Name | Description |
---|---|
PayPalQrcPaymentFailureReason.NotAuthenticated | Authentication flow was cancelled or interrupted |
PayPalQrcPaymentFailureReason.NotAuthorized | There is no authorised user to process payment request |
PayPalQrcPaymentFailureReason.AlreadyRefunded | Payment was already refunded |
PayPalQrcPaymentFailureReason.NotFound | Payment with given reference ID was not found |
PayPalQrcPaymentFailureReason.AmountTooHigh | Trying to perform refund with amount higher than original payment |
PayPalQrcPaymentFailureReason.PartialRefundNotSupported | Partial refund is not allowed for this payment |
PayPalQrcPaymentFailureReason.InsufficientFunds | Account does not have sufficient funds to perform refund |
PayPalQrcPaymentFailureReason.RefundExpired | Payment refund is too old to be refunded |
PayPalQrcPaymentFailureReason.TechnicalError | Payment failed because of technical issues |
PayPalQrcPaymentFailureReason.NetworkError | Communication with Zettle servers failed |
PayPalQrcPaymentFailureReason.Failed | Failure due to unknown reasons |
Extracting the success payload
A successful refund contains a payload of type PayPalQrcRefund
with fields describing the refund as listed in the following.
Name | Type | Description |
---|---|---|
amount | Long | Total refund amount |
originalAmount | Long? | Contains the original payment amount |
reference | String | The unique reference string provided when refund was started |
referenceNumber | String? | Zettles reference to the payment. |
transactionId | String? | The ID for the transaction in the Zettle system. The ID is automatically generated by the Zettle system. |
To start taking PayPal QRC payments, users must first read and promptly accept the terms and conditions from the settings screen.
1val intent = PayPalQrcActivationActivity.IntentBuilder(context).build()2startActivity(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.
If developer mode is not enabled, enable it by calling the following function in your integration project:
1IZettleSDK.init(2...,3isDevMode = true4)Launch the payment flow.
Check the responses.
The example shows test case "Successfully paid with PayPal".
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}Launch the refund flow.
Check the responses.
The example shows test case "Successful PayPal refund".
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}