Payment Methods
StartTransaction
Parameters startTransaction(Parameters)
Call startTransaction() to initiate a transaction. This can be used to start a Sale, Refund or Account Verification transaction. The request accepts various parameters including amount, transaction type, unique reference, whether to enable/disable gratuity and currency.
When the startTransaction() method is successful, asynchronous updates are provided in the following callbacks; transactionUpdate, userNotification, applicationSelection, signatureVerification, and transactionFinished.
Auto Confirm
The AutoConfirm parameter with the value TRUE should be passed into startTransaction() in order to request that an auto confirm transaction is started.
During an auto confirm transaction the SDK makes an attempt to complete the second stage of a transaction before the transactionFinished callback has been fired. This means that a subsequent call to confirmTransaction() or voidTransaction() is not required. Attempting to confirm a transaction which has already been completed will result in an error.
If the SDK fails to complete the second stage of the transaction for whatever reason the TransactionState returned in the transactionFinished event will be either Uncommitted or UncommittedVoid along with an appropriate error. The integrating application must then take responsibility for ensuring the second stage of a transaction is performed by calling either confirmTransaction() or voidTransaction().
PAN Key Entry
The PANKeyEntry requests a PAN key entry transaction is started. The card details are keyed into the PIN pad and are used for Card Not Present transactions. If the terminal is configured to require AVS during PANKeyEntry the numerics found in the first line of the customers address and their zip code will also need to be keyed into the PIN pad. The PANKeyEntry value should be set to TRUE or FALSE.
It's important to ensure that the acquirer is expecting to accept Card Not Present transactions on the associated merchant account.
Account Verification
An Account Verification transaction is a transaction that does not result in any transfer of funds, but is used to validate that the card is associated with an active account.
The TransactionType value should be set to AccountVerification to enable the Account Verification transaction. The transaction only requires a currency and user reference. The amount should not be included as part of the parameters.
Delay Online Processing
In Android it is possible to run a transaction with delayed online processing and process the request later via a different integration. To run a transaction with delayed online processing the DelayOnlineProcessing parameter key should be supplied with the value set to TRUE. No amount should be supplied when calling startTransaction. A delayed online processing transaction will complete to the point of going online at which point the transaction will finish and an encoded request will be returned in the transaction finished event.
Customer Vault
The Customer Vault stores a customer's card on the payment gateway so that it can be charged later without the card being present. To store the card used in a transaction, include these parameters in startTransaction():
| Parameter | Value | Description |
|---|---|---|
CustomerVaultCommand | add-customer, update-customer | Creates a new vault record, or replaces the card on an existing record. |
CustomerVaultId | Vault record ID | The vault record to use, for example the record to update with update-customer. |
On iOS, the parameter keys are prefixed CCParam, for example CCParamCustomerVaultCommand.
Each value can be up to 199 characters. A longer value returns CustomerVaultCommandInvalid or CustomerVaultIdInvalid.
The vault record's identifier is returned as CustomerVaultId in the transactionFinished callback. Later charges against a vault record are made through the payment gateway, not the SDK.
Customer Vault is supported on the VP3350 on both Android and iOS.
Credential on File
Credential on File marks a Sale as the first time a card is stored for future charges, such as recurring billing, installments or unscheduled charges, and records the reason. Include these parameters in startTransaction():
| Parameter | Value | Description |
|---|---|---|
CredentialOnFileFirstStore | TRUE | Marks the Sale as a first store. Without it, the reason is ignored. |
CredentialOnFileReason | One of the reasons below | Optional - The reason the card is stored. |
The reason can be one of:
ReasonUnscheduledReasonInstallmentReasonIncrementalReasonResubmissionReasonDelayedChargeReasonReAuthReasonNoShow
Any other value returns CredentialOnFileReasonInvalid. The parameters are only sent for a Sale; on other transaction types they are ignored.
On iOS, the parameter keys are prefixed CCParam and the values CCValue, for example CCParamCredentialOnFileReason and CCValueReasonUnscheduled.
The first store is recorded as initiated by the cardholder. Later charges using the stored credential are made through the payment gateway, not the SDK.
Credential on File is supported on the VP3350 on both Android and iOS.
Incremental Authorization
An incremental authorization lets the authorized amount grow before the transaction is captured, for example for hotel stays, car rental or EV charging. The merchant's processor must support incremental authorization.
The SDK performs the initial authorization. Call startTransaction() for a Sale with:
CredentialOnFileFirstStoreset toTRUE.CredentialOnFileReasonset toReasonIncremental(CCValueReasonIncrementalon iOS).
Do not use Auto Confirm. The transactionFinished callback reports the approved initial authorization with a TransactionState of Uncommitted. Unlike other uncommitted transactions, do not confirm it with confirmTransaction(). Store its CardEaseReference and TransactionId, and capture it through the payment gateway.
Increasing the authorization, capturing it and voiding it are done through the payment gateway, not the SDK. Every increase and the capture refer to the initial authorization's references. For the payment gateway's incremental authorization guide, contact the support team.
For example, an initial authorization of 10.00 followed by increases of 15.00 and 20.00 gives an authorized total of 45.00, which is then captured in a single request.
- Each increase is for the additional amount only, and refers to the initial authorization, not the previous increase.
- The capture can be for any amount up to the total of the approved authorizations. Capturing less is allowed.
- If an increase is declined, the rest of the chain stays valid, and only the approved amounts can be captured.
- To cancel before capture, void the authorization. Once the initial authorization is voided, no more increases can be added.
- The authorization must be captured before it can settle.
Incremental authorization is supported on the VP3350 on both Android and iOS.
ContinueSignatureVerification
Parameters continueSignatureVerification(Parameters)
Call continueSignatureVerification() with the result of the signature verification. If a digital signature has been captured it should be sent to the Payment Device SDK in this request.
continueSignatureVerification() method may only be called during a transaction after a onSignatureVerification callback has been triggered.
ContinueSignatureCapture
Parameters continueSignatureCapture(Parameters)
Call continueSignatureCapture() when the merchant has completed the signature capture process and the digital signature data can be provided.
continueSignatureCapture() method may only be called during a transaction after a onSignatureCapture() callback has been triggered.
ConfirmTransaction
Parameters confirmTransaction(Parameters)
To finalize an approved transaction which is not using the auto confirm feature or has failed to be auto confirmed you must call confirmTransaction() so that the transaction will be settled.
You do not have to call confirmTransaction() immediately after the transaction has been approved. For example, you may want to authorize multiple cards for a single purchase, in which case you would call confirmTransaction() for each approval after all transactions have been authorized.
ConfirmTransaction() requires the unique reference that was provided in StartTransaction() to identify and confirm an authorized transaction.
This method is synchronous, when successful the response will contain the result Approved or Declined and receipt data otherwise the response will contain the errors reported while attempting to confirm the transaction.
Completion requests are processed online and in real-time. If the transaction result is declined it is the responsibility of the integrating application to retry until it is approved.
VoidTransaction
Parameters voidTransaction(Parameters)
To void a transaction before settlement, but after it has been approved or confirmed so that funding does not take place, call voidTransaction().
voidTransaction() requires the unique reference that was provided in startTransaction() to identify and void a previously authorized transaction.
This method is synchronous, when successful the response will contain the result Approved or Declined and receipt data otherwise the response will contain the errors reported while attempting to void the transaction.
The Payment Device SDK may be configured to provide offline support so it continues to process confirms and voids when connection to the payment gateway has been lost. This provides storage capability of transaction data and processes completion requests once communications are restored.
By default, the SDK is configured to be online only so void requests are processed online and in real-time. If the transaction result is declined it is the responsibility of the integrating application to retry until it is approved.
LinkedRefundTransaction
Parameters linkedRefundTransaction(Parameters)
The Client can call linkedRefundTransaction() to refund all or part of a previously approved and confirmed transaction. The method returns a Parameters object instance containing a parameter list that includes the transaction result, receipt data, and errors if they exist. When performing a Cash or Cheque Linked Refund, PaymentMethod ParameterKey should be supplied with the value of ParameterValue of Cash or Cheque respectively, if the PaymentMethod has not been supplied the PaymentMethod` will default to ParameterValue Card.
This method is synchronous, when successful the response will contain the result Approved or Declined and the transaction information otherwise the response will contain the errors reported while attempting to refund the transaction.
TerminateTransaction
Parameters terminateTransaction(Parameters)
To cancel a transaction in progress call terminateTransaction(). If the transaction has finished before terminateTransaction() is called and the result is Approved then voidTransaction() can be used to cancel the transaction.
ProcessReceipt
Parameters processReceipt(Parameters)
Call processReceipt() to send a receipt. The request parameters are used to specify properties for processing receipt (e.g., email, SMS or printer) and also specifying the destination.
Updated 11 days ago
