Manage card payments with the Android SDK

The following describes how to work with card payments with the Android SDK. Operations include starting, processing, retrieving,and refunding. Examples are provided in Kotlin.

Start by creating a TransactionReference object using the builder provided.

Important: The transaction reference object must contain at least one unique field.

Copy
1
val internalTraceId = UUID.randomUUID().toString()
2
val reference = TransactionReference.Builder(internalTraceId)
3
    .put("PAYMENT_EXTRA_INFO", "Started from home screen")
4
    .build()

In the constructor of the builder you can provide your own ID with a maximum of 128 characters to identify the payment. This ID can be used to perform payment refunds.

Using the put method you can add any value you want to this object. However, keep in mind that the total data size (including key names) in this object can't be bigger than 4 kilobytes.

Next step is to start the CardPaymentActivity. To do this you can use our helper which creates configured Intent object.

Copy
1
val intent = CardPaymentActivity.IntentBuilder(this)
2
    // MANDATORY: Transaction amount in account currency
3
    .amount(20000L)
4
    // MANDATORY, Reference object created in previous step
5
    .reference(reference)
6
    // MANDATORY, enable login prompt in the payment flow if user is not yet logged-in
7
    .enableLogin(enableLogin)
8
    // OPTIONAL, you can enable tipping (disabled by default)
9
    // This option will only work for markets with tipping support
10
    .enableTipping(true)
11
    // OPTIONAL, you can enable installments (enabled by default)
12
    // This option will only work for markets with installments support
13
    .enableInstalments(enableInstallments)
14
    .build()
15

16
// Start activity with the intent
17
startActivityForResult(intent, 0)

Note: If setting enableLogin to true you need to setup auth for provided UI. Otherwise the user will be asked to login, but the app will never receive the result of the authentication.

Setting enableTipping to true does not guarantee that tipping flow will be displayed. This is because tipping is not supported by all accounts and all card readers. Tipping is only supported with the Zettle Card Reader. The function is introduced market by market. If card reader software doesn’t support tipping, users will be prompted to either skip tipping or update card reader software.

Total tip amount is presented in CardPaymentResult.Completed completion with gratuityAmount property. See Tipping support.

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 these classes, described in the following:

• CardPaymentResult.Canceled
• CardPaymentResult.Failed
• CardPaymentResult.Completed

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

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

Extracting the failure reason

The CardPaymentResult.Failed contains an instance of FailureReason describing the failure, and can contain any of the following reasons.

Extracting the success payload

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

To retrieve a card payment you need to provide the same unique reference ID provided to create the TransactionReference for the payment itself. See Starting card payments.

Copy
1
IZettleSDK.refundsManager.retrieveCardPayment(internalTraceId, object : RefundsManager.Callback<CardPaymentPayload, RetrieveCardPaymentFailureReason> {
2
    override fun onFailure(reason: RetrieveCardPaymentFailureReason) { /*...*/ }
3
    override fun onSuccess(cardPaymentPayload: CardPaymentPayload) { /*...*/ }
4
})

A refund works similar to a payment with the biggest exception that you will need to provide the same unique reference ID provided to create the TransactionReference for the payment. See Retrieving card payments.

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

Important: The transaction reference object must contain at least one unique field.

Copy
1
val internalTraceId = UUID.randomUUID().toString()
2
val reference = TransactionReference.Builder(internalTraceId)
3
    .put("REFUND_EXTRA_INFO", "Started from home screen")
4
    .build()

In the constructor builder you must provide the CardPayment retrieved from previous step.

Using the put method you can add any value to this object. However, keep in mind that the total data size (including key names) in this object can not be bigger than 4 kilobytes. You will get this reference back with transaction data and can always request it back from our servers.

Next step is to start RefundsActivity. Use the IntenBuilder to create create the configured Intent for the refund.

Copy
1
val intent = RefundsActivity.IntentBuilder(cardPaymentPayload)
2
    // 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
    .refundAmount(20000L)
6
    // Reference object created in previous step
7
    .reference(reference)
8
    // Optional, you can provide tax amount of this card payment to be displayed in the UI
9
    .taxAmount(100L)
10
    // Optional, you can provide the receipt number of this card payment to be displayed in the UI
11
    .receiptNumber("#12345")
12
    .build()
13

14
// Start activity with the intent
15
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 these classes, described in the following:

• RefundResult.Canceled.
• RefundResult.Failed.
• RefundResult.Completed.

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

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

Extracting the failure reason

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

Extracting the success payload

A successfull refund contains a payload of type RefundPayload which has fields describing the refund. They are listed in the table below.

To provide a way to access card reader settings from outside the payment flow, you can use the following static method to get the intent.

Copy
1
val intent = CardReadersActivity.newIntent(context)
2
startActivity(intent)

When integrating with the SDK, you can test your integration in developer mode for card 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".

   Copy
   1
   "payload": {
   2
       "amount": <the payment amount you passed to SDK>, // If `enableTipping` set to `true`, a gratuity amount `300` will be added
   3
       "applicationIdentifier": "A0000000031010",
   4
       "applicationName": "Visa Credit",
   5
       "authorizationCode": "123456",
   6
       "cardIssuingBank": null,
   7
       "cardPaymentEntryMode": "CONTACTLESS_EMV",
   8
       "cardType": "VISA",
   9
       "cardholderVerificationMethod": "None",
   10
       "gratuityAmount": null, // If `enableTipping` set to `true`, the returned gratuity amount is `300`
   11
       "installmentAmount": 0,
   12
       "maskedPan": "************0119",
   13
       "mxCardType": null,
   14
       "mxFiid": null,
   15
       "mxPaymentMethodCode": null,
   16
       "nrOfInstallments": 0,
   17
       "panHash": "01086BED527FDA321CC8718F44839CD909378B4C",
   18
       "referenceNumber": "G5363OXS4K",
   19
       "transactionId": "bdcf72bc-6037-11ed-a055-e2294a8ade3d",
   20
       "tsi": null,
   21
       "tvr": "0000000000",
   22
       "reference": {
   23
           "id": "<the reference passed to the flow>"
   24
       }
   25
   }

4. Launch the refund flow.

5. Check the responses.

   Copy
   1
   "payload": {
   2
     "cardType": "VISA",
   3
     "maskedPan": "************0119",
   4
     "originalAmount": 1000,
   5
     "refundAmount": <the refund amount you passed to the SDK>,
   6
     "transactionId": "2420db84-6041-11ed-a687-0fe1acbcd38a"
   7
   }

• Tipping support
• Manage PayPal QRC payments
• Developer mode