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.

Prerequisites

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.
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)

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.
NameTypeDescription
amountNSDecimalNumberTotal transaction amount
referenceNumberNSStringZettle's reference to the payment (This is not the reference provided by you during a charge or refund operation)
transactionIdNSStringThe 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.
NameDescription
IZSDKManualCardEntryNetworkErrorThis 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.
IZSDKManualCardEntryFeatureNotEnabledPayment method was not available for the user.
IZSDKManualCardEntrySellerDataErrorSomething 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.
IZSDKManualCardEntryPaymentCancelledByMerchantPayment was canceled by the seller.
IZSDKManualCardEntryInvalidAmountProvided amount was invalid.
IZSDKManualCardEntryAmountBelowMinimumProvided amount was below the minimum amount.
IZSDKManualCardEntryAmountAboveMaximumProvided amount was above the maximum amount.
IZSDKManualCardEntryNotFoundNo payment was found for the reference specified in the request.
IZSDKManualCardEntryNotAuthorizedUser was not authorised for this action.
IZSDKManualCardEntryRetrievalCancelledThe retrieval of payment information was cancelled by the seller.
IZSDKManualCardEntryRefundAmountTooHighRequested amount couldn't be refunded for the payment.
IZSDKManualCardEntryRefundInsufficientFundsThere were not enough funds to complete a refund to the seller's account.
IZSDKManualCardEntryRefundFailedThe payment was not refundable. The refund amount was not valid, or there were some missing/incorrect request parameters.
IZSDKManualCardEntryRefundCancelledThe payment refund was canceled by the seller.
IZSDKManualCardEntryTechnicalErrorThere was an unexpected technical error. If the issue persists, contact support.