Manage Manual Card Entry payments

The following describes how to work with the iOS SDK Manual Card Entry payment operations for charging, refunding, and fetching payment information.

Note:

The Manual Card Entry Payment method is available only in the US market.
Your merchants need a PayPal business account to manage manual card entry payments. Your merchants need to log in to PayPal back office to refund manual card entry payments.
Manual card entry payment transactions do not appear in the Zettle back office. You can see these only in the PayPal back office. These transactions also are not reflected in Zettle's Purchase and Finance APIs.

Prerequisites

You have completed the SDK initialisation. See Initialisation.
You have implemented the appropriate Zettle Settings view. See Present Settings view.

Enabling Manual Card Entry Payments

To accept Manual Card Entry payments with the SDK integration, use the following code samples to enable the payment method after initialising the SDK.

1
[[iZettleSDK shared] setEnabledAlternativePaymentMethod:@[@(IZSDKAlternativePaymentMethodManualCardEntry)]];

1
let enabledAPMs = [NSNumber(value: IZSDKAlternativePaymentMethod.ManualCardEntry.rawValue)]
2
iZettleSDK.shared().setEnabledAlternativePaymentMethods(enabledAPMs)

When this payment method is enabled, the merchant can acquire payments by manually entering the customer's card details.

Using Manual Card Entry

After you enable the Manual Card Entry Payment method, you will find an option in the SDK Settings view for Manual Card Entry which lets your merchants activate the payment method

By default it's not activated for your integration users. Make sure that you remind them to activate Manual Card Entry payment in the Manual Card Entry screen before they use it.

Charging a manual card entry

Use the following code samples to execute a payment with an amount and a reference.

amount: The payable amount specified in the logged-in merchant's currency.
reference: Non-nullable payment reference. Used to identify a Zettle payment when retrieving payment information or performing a refund later. Max length 128.

Note: Make sure that you securely store the reference. If the reference is lost, you will not be able to make a refund or retrieve payment information.

1
- (void)chargeManualCardEntryWithAmount:(NSDecimalNumber *)amount
2
                              reference:(NSUUID *)reference
3
              presentFromViewController:(UIViewController *)viewController
4
                             completion:(IZSDKManualCardEntryCompletion)completion

1
func chargeManualCardEntry(amount: NSDecimalNumber,
2
                        reference: UUID,
3
        presentFrom viewController: UIViewController,
4
                        completion: IZSDKManualCardEntryCompletion)

See IZSDKManualCardEntryCompletion.

Refunding

Use the following code samples to refund an amount from a Manual Card Entry payment with a given reference.

1
- (void)refundManualCardEntryAmount:(nullable NSDecimalNumber *)amount
2
             ofPaymentWithReference:(NSUUID *)paymentReference
3
                    refundReference:(NSUUID *)refundReference
4
          presentFromViewController:(UIViewController *)viewController
5
                         completion:(IZSDKManualCardEntryCompletion)completion

1
func refundManualCardEntry(amount: NSDecimalNumber?,
2
                           ofPayment paymentReference: UUID,
3
                           withRefundReference refundReference: UUID,
4
                           presentFrom viewController: UIViewController,
5
                           completion: IZSDKManualCardEntryCompletion)

amount (optional): The refund amount (passing nil will refund the full amount of the original payment)).
paymentReference: The payment reference corresponding to the original payment. Max length 128.
refundReference: The reference of the refund. Max length 128.

Retrieving payment information

Use the following code samples to query Zettle SDK to retrieve payment information for a Manual Card Entry payment with a given reference.

1
- (void)retrieveManualCardEntryInfoForReference:(NSUUID *)reference
2
                      presentFromViewController:(UIViewController *)viewController
3
                                     completion:(IZSDKManualCardEntryCompletion)completion

1
func retrieveManualCardEntryInfo(for reference: UUID,
2
                                 presentFrom viewController: UIViewController,
3
                                 completion: IZSDKManualCardEntryCompletion)

IZSDKManualCardEntryCompletion callback

IZSDKManualCardEntryCompletion is the completion callback and it's called when an operation is completed, cancelled, or failed.

Success payload

If the payment is successful, the callback will provide IZSDKManualCardEntryPaymentInfo with the following details about the transaction.

Name	Type	Description
`amount`	`NSDecimalNumber`	Total transaction amount
`referenceNumber`	`NSString`	Zettle's reference to the payment (This is not the reference provided by you during a charge or refund operation)
`transactionId`	`NSString`	The ID for the transaction in the Zettle system. The Zettle system automatically generates the ID.

Handling failure

If the payment completion fails, the SDK will generate an NSError. The error message describes the failure, and can contain any of the reasons listed in the following table.The NSError-object returned in the operation completion block is only intended for developers. The object provides more detailed information useful for debugging, diagnostics and logging. You should never present errors returned in this format to the end-user.

Name	Description
IZSDKManualCardEntryNetworkError	This occurs due to a network error. For example, the request timed out, the network was switched off or the connection was lost due to poor network.
IZSDKManualCardEntryFeatureNotEnabled	Payment method was not available for the user.
IZSDKManualCardEntrySellerDataError	Something was wrong with the user's information. The user was not authenticated, or there were some missing/incorrect request parameters. If the issue persists, contact support.
IZSDKManualCardEntryPaymentCancelledByMerchant	Payment was canceled by the seller.
IZSDKManualCardEntryInvalidAmount	Provided amount was invalid.
IZSDKManualCardEntryAmountBelowMinimum	Provided amount was below the minimum amount.
IZSDKManualCardEntryAmountAboveMaximum	Provided amount was above the maximum amount.
IZSDKManualCardEntryNotFound	No payment was found for the reference specified in the request.
IZSDKManualCardEntryNotAuthorized	User was not authorised for this action.
IZSDKManualCardEntryRetrievalCancelled	The retrieval of payment information was cancelled by the seller.
IZSDKManualCardEntryRefundAmountTooHigh	Requested amount couldn't be refunded for the payment.
IZSDKManualCardEntryRefundInsufficientFunds	There were not enough funds to complete a refund to the seller's account.
IZSDKManualCardEntryRefundFailed	The payment was not refundable. The refund amount was not valid, or there were some missing/incorrect request parameters.
IZSDKManualCardEntryRefundCancelled	The payment refund was canceled by the seller.
IZSDKManualCardEntryTechnicalError	There was an unexpected technical error. If the issue persists, contact support.