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