PaymentEngineAPICom Class

captureSignature

-(void)captureSignature:(NSMutableDictionary *)signatureDict

Parameters

Type Parameter Description
NSMutableDictionary signatureDict NSMutableDictionary that holds all the necessary information to capture the signature. See below.

signatureDict Fields

Key Description
command Processing command, in this case it will be "capture".
amount Total amount of the transaction for which you are capturing the signature.
refNum The refNum of the transaction for which you are capturing the signature.
signature The base64Encoded string of the image.

Delegate Methods

The following delegates may be returned:

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse
  • captureSignatureComplete() method will be called for all errors, declines or approvals. It is called after all captureSignature operations have been completed.

Example


/**
* Use this method to capture customer signature after transaction is completed
*/
-(void)startCaptureSigEvent
{
    PaymentEngineAPICom *apiCom = [PaymentEngineAPICom getInstance];
    apiCom.delegate = self;

    UIImage *signatureImg = [UIImage imageNamed:@"signatureImg.png"];
    NSData *imgData = UIImageJPEGRepresentation(signatureImg, 0.5f);
    NSString *imgBase64 = [imgData base64EncodedStringWithOptions:0];

    NSMutableDictionary *transDict = [NSMutableDictionary new];

    [transDict setObject:imgBase64 forKey:@"signature"];
    [transDict setObject:@"1296965885" forKey:@"refNum"];
    [transDict setObject:@"12.01" forKey:@"amount"];
    [transDict setObject:@"capture" forKey:@"command"];

    [apiCom captureSignature:transDict];
}

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse
{

    NSLog(@"trans resposne: %@", transResponse.Result);
    NSLog(@"trans response status: %@", transResponse.Status);
    NSLog(@"trans response error: %@", transResponse.Error);

}

startTransaction

-(void)startTransaction :(NSMutableDictionary *)holdTransInfo 

Used to start a transaction request. holdTransInfo parameter holds all the necessary info to process a transaction. When the gateway response is received or an error occurs, the transactionComplete delegate method will get call. Developers will need to implement these two methods to properly handle the transaction flow.

Parameters

Type Parameter Description
NSMutableDictionary holdTransInfo NSMutableDictionary that holds information about the transaction. See below.

Exceptions

  • APIComException will be thrown if any of the parameters are passed in with a null value.

Supported Commands

cc:sale
This command is the default processing command. The 'cc:sale' command runs a standard credit/debit card sale. It will charge the customers credit/debit card for the amount specified. This command requires that the amount field be populated. Once called, the terminal will collect the payment method from the customer and then send the transaction for processing. If the charge is successful, the transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

cc:authonly
This command runs a credit/debit card authorization. This command requires that the amount field be populated. Once called, the terminal will collect the payment method from the customer and then send the transaction for processing. If approved, the funds will be held in the customers account. The funds will remain oh hold until either the transaction is captured and settled, or until the authorization code expires. The length of time before an authorization expires varies from bank to bank, but generally it is recommended that authorizations be captured within 24-48 hours. Merchants should consult their merchant service provider for information specific to their account. If a merchant does not capture the transaction, no funds will be received by the merchant.

cc:capture
This command moves 'cc:authonly' transactions into the batch for settlement. The original Transaction ID (refnum) must be passed in refNum field. Additionally, the amount of originally authorized may be adjusted by passing the amount field. The tolerances for the settle amount vary depending on the type of merchant account and the merchant service provider. The transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

cc:adjust This command allows you to make changes to an existing (unsettled) sale. The authorization amount can be increased (incremental authorization), decreased (partial reversal), or not changed. Additional data elements such as tax amount and PO number can also be added. The original Transaction ID (refnum) must be passed in refNum field. The tolerances for the settle amount vary depending on the type of Merchant Account and the merchant service provider. The adjust and capture commands function identically except that the adjust command does not place the transaction in the batch.

cc:credit
This command performs an open credit (refund) to a card. It requires the amount field be populated. The terminal will then prompt the customer for the payment method, and then send the transaction to the gateway for processing.

void:release
This command cancels a pending (sale, authonly, or credit) transaction. For credit card transactions, this command removes the transaction from the current batch. There is a limited amount of time that a void may be run. For credit cards, a transaction can no longer be voided once the batch has been closed. The void requires that the original Transaction ID number be passed in the refNum field. The terminal is not used, and the transaction is sent directly to the gateway.

holdTransInfo Fields

The majority of these are optional. The only required fields are amount and command.

Key Description
command Processing command, typically "cc:sale" or "cc:authonly", see above.
amount Total amount to authorize (including tax, shipping, etc). If prompTip parameter is set to "true", this amount will be added to the tip for the total authorization amount.
tax Tax amount
nontaxable Transaction is non taxable
tip If the prompTip parameter is not set, the tip may be passed in this field. The third option is to use the Tip Adjust terminal config which allows for the tip to be added post authorization.
shipping Shipping amount
duty Duty charge (Required only for level 3)
discount The amount of any discounts that were applied.
description Transaction Description
comments Internal transaction notes (not included on customer receipt). Optional.
custid Merchant assigned customer id.
invoice Invoice number, only first 11 characters are used
orderid Order identifier. This field can be used to reference the order to which this transaction corresponds. This field can contain up to 64 characters and should be used instead of invoice when orderid is longer that 10 digits.
ponum Purchase Order number. Only required for corporate purchasing cards.
clerk Indicates the clerk/person processing transaction, for reporting purposes. (optional)
tranterm Indiactes the terminal used to process transaction, for reporting purposes. (optional)
resttable Indicates the restaurant table, for reporting purposes. (optional)
enablePartialAuth Set to "true" to enable partial authorization.
refnum Gateway assigned transaction id number. Necessary for commands that modify an existing transaction, such as "cc:adjust" or "void:release".
timeout Max number of seconds to wait for a response from the gateway. This does not limit how long the customer has to swipe their card.
cashback The total amount for cashback (optional).

Address Fields:

Billing Key Shipping Key Description
billfname shipfname First Name
billlname shiplname Last Name
billcompany shipcompany Company Name
billstreet shipstreet Street Address
billstreet2 shipsreet2 Additional street information (if needed)
billcity shipcity City
billstate shipstate State
billzip shipzip Zip/Postal code
billcountry shipcountry Country
billphone shipphone Phone Number
email
fax
website

Line Item Details:

Replace * with the line number 1-99999.

Field Max Length Description
line*productrefnum 12 (optional) Gateway assigned product RefNum, used for inventory control.
line*sku 32 Product id, code or SKU
line*name 255 Item name or short description
line*description 64k Long description
line*cost 00000000.00 Cost of item per unit of measure (before tax or discount)
line*qty 00000000.0000 Quantity
line*taxable 1 Y = Taxable, N = Non-taxable
line*taxrate 00.000 Tax rate for line (only required for level 3 processing).
line*taxamount 00000000.00 Amount of tax charge for line (if left blank will be calculated from taxrate)
line*um 12 Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used.
line*commoditycode 12 Commodity code (only required for level 3 processing). See http://www.unspsc.org/ for valid list of codes.
line*discountrate 000.000 Discount percentage for line (only required for level 3 processing).
line*discountamount 00000000.00 Discount amount for line (if left blank will be calculated from discountrate).