Required Methods

To implement payment processing, the VOVoucherCreationFlowCoordinator delegate needs to implement the following methods:

- (void)collectPaymentInfoOnViewController:(UIViewController *)viewController forVoucher:(VOVoucher *)voucher onCompletion:(void (^)(NSDictionary<NSString *, id> * _Nullable, NSError * _Nullable))completion;

- (void)approvePaymentInfoOnViewController:(UIViewController *)viewController forVoucher:(VOVoucher *)voucher onCompletion:(void (^)(NSDictionary<NSString *, id> * _Nullable, NSError * _Nullable))completion;

func collectPaymentInfo(on viewController: UIViewController?, for voucher: VOVoucher?, onCompletion completion: @escaping ([String : Any?]?, Error?) -> Void)
    
func approvePaymentInfo(on viewController: UIViewController?, for voucher: VOVoucher?, onCompletion completion: @escaping ([String : Any?]?, Error?) -> Void)

The collectPaymentInfoOnViewController:forVoucher:onCompletion method is used to provide the SDK with the payment information that will be sent to the server via the paymentInfo Dictionary in the onCompletion block. See Payments Summary for details on what information needs to be set in the paymentInfo Dictionary.

The approvePaymentInfoOnViewController:forVoucher:onCompletion method is used to provide the SDK with the approved payment information that will be sent to the server via the paymentInfo Dictionary in the onCompletion block. See Payments Summary for details on what information needs to be set in the paymentInfo Dictionary.

Example implementation

- (void)collectPaymentInfoOnViewController:(UIViewController *)viewController
                                forVoucher:(VOVoucher *)voucher
                              onCompletion:(void (^)(NSDictionary<NSString *, id> * _Nullable, NSError * _Nullable))completion {
    // optionally present a view controller here that collects payment information
    NSDictionary<NSString *, id> *paymentInfo = @{
        @"type": @"CREDIT_CARD",
        @"userInfo": @{
                @"billingCardNumber": [self encryptString:@"4111111111111111"],
                @"billingCVV": [self encryptString:@"111"],
                @"billingCardHolderName": @"Jane Doe",
                @"billingAddress1": @"123 Main Street",
                @"billingCity": @"San Fransisco",
                @"billingRegion": @"CA",
                @"billingCountry": @"US"
        },
        @"approved": @YES
    };
    completion(paymentInfo, nil);
}

- (void)approvePaymentInfoOnViewController:(UIViewController *)viewController
                                forVoucher:(VOVoucher *)voucher
                              onCompletion:(void (^)(NSDictionary<NSString *, id> * _Nullable, NSError * _Nullable))completion {
    // optionally present a view controller here that collects payment information needed for approval
    NSDictionary<NSString *, id> *paymentInfo = @{
        @"type": @"CREDIT_CARD",
        @"userInfo": @{
            @"billingCVV": [self encryptString:@"111"],
        },
        @"approved": @YES
    };
    completion(paymentInfo, nil);
}

func collectPaymentInfo(on viewController: UIViewController, for voucher: Voucher, onCompletion completion: @escaping ([String : Any]?, Error?) -> Void) {
    let paymentInfo: [String: Any] = [
        "type": "CREDIT_CARD",
        "userInfo": [
            "billingCardNumber": encryptString("4111111111111111"),
            "billingCVV": encryptString("111"),
            "billingCardHolderName": "Jane Doe",
            "billingAddress1": "123 Main Street",
            "billingCity": "San Fransisco",
            "billingRegion": "CA",
            "billingCountry": "US"
        ],
        "approved": true
    ]
    completion(paymentInfo, nil)
}

func approvePaymentInfo(on viewController: UIViewController?, for voucher: VOVoucher?, onCompletion completion: @escaping ([String : Any?]?, Error?) -> Void) {
    // optionally present a view controller here that collects payment information needed for approval
    let paymentInfo: [String: Any] = [
        "type": "CREDIT_CARD",
        "userInfo": [
            "billingCVV": encryptString("111")
        ],
        "approved": true
    ]
    completion(paymentInfo, nil)
}

Optional Methods

The showDisclaimerForPaymentMerchantInfo: method is called when a merchant is required to present a disclaimer to the user.

Example Implementation

- (void)productDetailsViewController:(UIViewController *)viewController
showDisclaimerForPaymentMerchantInfo:(VOPaymentMerchantInfo *)paymentMerchantInfo
                      withCompletion:(void(^)(void))onCompletion;
  	// some merchants require accepting a disclaimer / UELA before choosing this payment option
  	if (paymentMerchantInfo.type == VOPaymentMerchantInfoTypeVanillaVisa) {
  		[self showDisclaimerForVanillaVisaWithCompletion:onCompletion];
  	} else {
  		onCompletion();
  	}
}

func productDetailsViewController(_ viewController: UIViewController?, showDisclaimerFor paymentMerchantInfo: VOPaymentMerchantInfo?, withCompletion onCompletion: @escaping () -> Void) {
    // some merchants require accepting a disclaimer / UELA before choosing this payment option
    if paymentMerchantInfo?.type == VOPaymentMerchantInfoTypeVanillaVisa {
        showDisclaimerForVanillaVisa(withCompletion: onCompletion)
    } else {
        onCompletion()
    }
}

Handling Errors

To view any errors related to the payment information, the VOVoucherCreationFlowCoordinator’s delegate needs to implement the voucherCreationVoucherActivationFailedWithError method. The method will be called during the activation of the voucher.

Any payment information related errors will have a domain of VOVoucherManagerErrorDomain. The error code will have one of the following values:

  • VOVoucherActivationUserSetupRequired: userInfo in the payment source hasn’t been configured

  • VOVoucherActivationVoucherSetupRequired: Voucher payment info hasn’t been configured, this may sugggest something went wrong during the setup of the voucher

  • VOVoucherActivationApprovalRequired: Everything is setup it just needs to be approved. The paymentInfo in the approvePaymentInfoOnViewController:forVoucher:onCompletion completion handler needs to have approved set to true (YES)

  • VOVoucherActivationValidationError: The payment validation failed. Information about the failure is in the error’s userInfo with the following keys:

    • VOVoucherActivationValidationErrorMessageKey: The validation error message

    • VOVoucherActivationValidationErrorFieldsKey: A Dictionary containing the field names and the associated error message for the field

  • VOVoucherActivationUnknownError: An unknown error occured