iOS SDK - Transaction Module

Use the endpoints of this module to exchange data necessary to complete a transaction through the wallet, such as a purchase, refund, ATM withdrawal or deposit, etc.

Initialize Transaction Facade

Prior to invoking any transaction module endpoints:

  1. Create a new request object for the relevant coordinator.
  2. Implement the delegate for the coordinator to handle responses.
self.transactionCoordinator = [[PDTransactionCoordinator alloc] init];
self.transasctionCoordinator setDelegate:self];

obtainCheckoutTokenFor

Gets a checkout token value from the platform so the mobile device can generate and display a QR code to initiate the transaction in lieu the POS.

Element Value
Method Signature -(void) obtainCheckoutTokenFor:(PDTransactionType)aTransactionType;

aTransactionType - An enum value thatspecifies the type of transaction that the checkout token will initiate. Valid values are:
kPDTransactionTypePurchase
kPDTransactionTypeReturn
kPDTransactionTypeCashAccess
kPDTransactionTypeUnknown
Success (^ObtainCheckoutTokenCompletionBlock;(NSString *checkoutToken, PDTransactionType *type);

checkoutToken - Paydiant's unique identifier for a transaction instance which can be used to generate a QR code for scanning by the other party in a transaction.
type - An enum value that identifies the type of transaction for which the checkout token is valid.
Failure (^ObtainCheckoutTokenFailureBlock(PDPaydiantError*transactionError);

Configure user error messages for this call with the key kUserErrorObtainCheckoutTokenDomain.

Error Description
400 The transaction was declined.
403 The user must be logged in to make this call.
500 An unknown error occurred internally in the server.

releaseCheckoutToken

Cancels a generated checkout token that has not yet been scanned. This action is typically invoked when the user switches to a different screen in the app (such as the location finder) or puts the app in the background (such as to answer a call or text). Once a checkout token is released, it is not longer valid for a transaction, so when the app focus returns to the payment screen, a new token must be requested using obtainCheckoutTokenFor.

Element Value
Method Signature -(void) releaseCheckoutToken:(NSString *)aCheckoutToken;

aCheckoutToken - The value of the checkout token that is no longer needed.
Success (^ReleaseCheckoutTokenCompletionBlock)();
Failure (^ReleaseCheckoutTokenFailureBlock(PDPaydiantError*transactionError);

Configure user error messages for this call with the key kUserErrorReleaseCheckoutTokenDomain.

Error Description
400 One or more parameters in the request is invalid.
403 The user must be logged in to make this call.
419 The checkout token provided is invalid.
500 An unknown error occurred internally in the server.

retrieveTransctionMetadata

Gets information about a transaction relevant to the specified flow rule (a particular stage of the transaction) in order to complete necessary action to move the transaction forward. For example, after successfully decoding a QR Code, invoke this call for the DISCOVERY flow rule to get the amount due and the supported tender types so the app can present relevant payment options to the user.

Element Value
Method Signature -(void) retrieveTransactionMetaData:(PDRetrieveTransactionMetaDataRequest*)retrieveTransactionMetaDataRequest;

retrieveTransactionMetaDataRequest - Identifies the transaction and the current flow rule in order to obtain data and requirements related to the next obligation on the wallet side of the transaction.
Success (^RetriveTransactionMetaDataCompletionBlock;(PDRetriveTransactionMetaDataResponse *response);

response - The details of the transaction relevant to the current flow rule.
Failure (^RetriveTransactionMetaDataFailureBlock(PDPaydiantError*transactionError);

Configure user error messages for this call with the key kUserErrorRetriveTransactionMetaDataDomain.

Note: Top-level status codes returned are only relevant to the success or failure of the retrieval call. For status codes related to payment authorization, refer to the paymentStatusCode (Paydiant’s) or the externalStatusCode (processor’s) property of each PDTransactionAccount instance included in the PDTransactionDetail object returned in the completion block response. Multi-tender transactions will have multiple TransactionAccount instances per transaction.

Error Description
400 The transaction was declined.
403 The user must be logged in to make this call.
406 The checkout token is blocked.
409 The checkout token is already in use by a processing transaction.
416 The transaction has been canceled by the POS terminal.
417 The transaction has timed out due to unresponsiveness from the server.
500 An unknown error occurred internally in the server.
503 The scanned code is not valid for this transaction.
508 Split tender payments are not supported for this merchant.

updateTransaction

Submits data related to the current flow rule (a particular stage of the transaction) in order to move the transaction forward. For example, the transaction may need input regarding whether the user wants to add a tip in order to recalculate the total charge.

Element Value
Method Signature -(void) updateTransaction:(PDUpdateTransactionRequest*)updateTransactionRequest;

updateTransactionRequest - Identifies the transaction and the current flow rule and passes data values to complete the requirements for that flow rule.
Success (^UpdateTransactionCompletionBlock: (PDUpdateTransactionResponse*response);

response - returns the status of the outcome of the update and any data relevant to completing the next flow rule.

ATM SPECIAL SUCCESS CASES:

Partial Withdrawal: In the event that an ATM has insufficient funds to fulfill the entire amount of a withdrawal but some portion of the cash has already been dispensed, the response object will return a transactionStatus value of kPDTransactionStatusPartialPayment and an update amount value. Mobile wallet apps that support ATM withdrawals must be configured to support this variable success case.
Forced Deposit: If a user submits a deposit but then attempts to cancel the transaction at an irreversible point, the ATM submits a FORCED_DEPOSIT_SUCCSS response, which Paydiant will pass as a paymentStatus value in this response.
Failure (^UpdateTransactionFailureBlock(PDPaydiantError*TransactionError);

Configure user error messages for this call with the key kUserErrorUpdateTransactionDomain.

Status Code Description
400 The transaction was declined.
402 Suspected fraud.
403 The user must be logged in to make this call.
405 The payment account has insufficient funds.
406 The checkout token is blocked.
409 The checkout token is already in use by a processing transaction.
410 The amount specified is not valid.
414 The offer specified is not redeemable for the current transaction.
416 The transaction has been canceled by the POS terminal.
417 The transaction has timed out due to unresponsiveness from the server.
419 The checkout token is not valid.
420 Tipping is not supported at the current location.
421 An error occurred during the tipping calculation.
422 An error occurred on the POS terminal.
423 The account specified has been removed from the wallet.
500 An unknown error occurred internally in the server.
501 A processing error has occurred.
502 The transaction is being reviewed.
503 The scanned code is not valid for this transaction.
504 The card number specified is not valid.
505 The card specified has expired.
506 This wallet is not supported at this merchant location.
507 The billing address specified is not valid.
508 Split tender payments are not supported for this merchant.
510 The transaction type is not valid at this location.

retrieveTransactionInformation (Legacy)

For non-flow rule driven transactions (not typical), invoke this method immediately following the scanning of a QR code to get the transaction information submitted by the POS, such as the amount due, supported payment tenders, eligible offers, etc.

Element Value
Method Signature -(void) retrieveTransactionInformation:(PDRetrieveTransactionInformationRequest*)request;

request - Passes the checkout token in order to connect to the transaction and request the relevant data for a payment.
Success (^RetrieveTransactionInformationCompletionBlock: (PDTransactionInformation*transactionInformation, PDTransactionType *transactionType,PDRetrieveTransactionInformationResponse*response);

transactionInformation - The details about the transaction, such as the merchant, amount due, store location, etc.
transactionType - An enum value that distinguishes whether the transaction is a purchase, refund, fuel sale, ATM interaction, etc.
response - The details about the transaction plus status information related to the outcome of the call.
Failure (^RetrieveTransactionInformationFailureBlock(PDPaydiantError*TransactionError);

Configure user error messages for this call with the key kUserErrorRetrieveTransactionInformationDomain.

Error Description
400 The transaction was declined.
403 The user must be logged in to make this call.
406 The checkout token is blocked.
409 The checkout token is already in use by a processing transaction.
416 The transaction has been canceled by the POS terminal.
417 The transaction has timed out due to unresponsiveness from the server.
419 The checkout token is not valid.
500 An unknown error occurred internally in the server.
503 The scanned code is not valid for this transaction.
508 Split tender payments are not supported for this merchant.

paymentWith (Legacy)

Submits payment data for a non-flow-rule driven transaction. If the payment is less than the amount owed, the response will return the outstanding balance and request another payment.

Element Value
Method Signature -(void) paymentWith:(PDSplitTenderPaymentTransactionRequest*)request;

request - Passes the payment account selection and amount.
Success (^SplitTenderPaymentCompletionBlock: (PDPaymentTransaction*paymentTransaction, PDPaymentStatusType *paymentStatusType,PDSplitTenderPaymentTransactionResponse*splitTenderPaymentResponse);

paymentTransaction - The details about the payment result, such as the tender, the amount, what offers were applied, etc.
paymentStatusType - An enum value that indicates if the payment completed the transaction (kPDPaymentStatusTypeCompleted) or if the payment is a partial payment with some balance outstanding.(kPDPaymentStatusTypePartiallyCompleted).
splitTenderPaymentResponse - The details about the transaction plus status information related to the outcome of the call.
Failure (^SplitTenderPaymentTransactionFailureBlock(PDPaydiantError*TransactionError);

Configure user error messages for this call with the key kUserErrorPaymentProcessorDomain.

Error Description
400 The transaction was declined.
402 Suspected fraud.
403 The user must be logged in to make this call.
404 The transaction amount could not be found.
405 The payment account has insufficient funds.
406 The checkout token is blocked.
409 The checkout token is already in use by a processing transaction.
410 The amount specified is not valid.
414 The offer specified is not redeemable for the current transaction.
416 The transaction has been canceled by the POS terminal.
417 The transaction has timed out due to unresponsiveness from the server.
419 The checkout token is not valid.
420 Tipping is not supported at the current location.
421 An error occurred during the tipping calculation.
422 An error occurred on the POS terminal.
423 The account specified has been removed from the wallet.
500 An unknown error occurred internally in the server.
501 A processing error has occurred.
502 The transaction is being reviewed.
503 The scanned code is not valid for this transaction.
504 The card number specified is not valid.
505 The card specified has expired.
506 This wallet is not supported at this merchant location.
507 The billing address specified is not valid.
508 Split tender payments are not supported for this merchant.
510 The transaction type is not valid at this location.

submitATMCashAccessAmount (Legacy)

Submits withdrawal details for a non-flow-rule-driven ATM transaction.

Note: This method does not support deposit transactions or service fee consent, which can only be implemented using flow-rule-driven cash access processing.

Element Value
Method Signature -(void) submitATMCashAccessAmount:(NSString *)paydiantTransactionRefId cashAccessType:(PDCashAccessTransactionType)cashAccessType cashAmount:(NSDecimalNumber *)cashAmount accountUri:(NSString *)accountUri;

paydiantTransactionRefId - Paydiant's unique identifier for the transaction.
cashAccessType - An enum value that indicates the specific banking operation. Valid values are:
kPDCashAccessTransactionTypeWithdrawal
kPDCashAccessTransactionTypeUnknown

cashAmount - The dollar amount being withdrawn.
accountUri - Paydiant's unique identifier for the payment account from which the cash is being withdrawn.
Success (^SubmitCashAccessAmountCompletionBlock: (PDCashAccessTransaction*cashAccessTransaction);

cashAccessTransaction - The details about the withdrawal result.
Failure (^SubmitCashAccessAmountFailureBlock(PDPaydiantError*cashAccessError);

Configure user error messages for this call with the key kUserErrorCashAccessProcessorDomain.

Error Description
400 The transaction was declined.
403 The user must be logged in to make this call.
405 The payment account has insufficient funds.
423 The account specified has been removed from the wallet.
500 An unknown error occurred internally in the server.
501 A processing error has occurred.
510 The transaction type is not valid at this location.

generateAccessCode

Generates a non-leading-zero numerical access code of a specified length to submit as a secondary identifier for transactions that require pre-authorization of a payment tender, such as pay-at-the-pump fuel transactions.

Element Value
Method Signature -(NSString *) generateAccessCode:(NSInteger)length;

length - The number of digits that should make up the length of the generated code.
Success A randomly generated numerical string of the length specified in the request. This value will never include a leading zero.
Failure There is no failure response for this call. If the length value in the request is invalid, the string returned will be null.

There is no applicable user error domain key for this call.

cancelTransactionUsingToken

Cancels a transaction that is in process.

Element Value
Method Signature -(void) cancelTransactionUsingToken:(NSString *)checkoutToken paydiantTransactionRefId:(NSString *)transRefId;

checkoutToken - The value of the checkout token that was used to initiate the transaction.
transRefId - Paydiant's unique identifier for the transaction.
Success (^CancelTransactionCompletionBlock)();.
Failure (^CancelTransactionFailureBlock(PDPaydiantError*transactionError);

Configure user error messages for this call with the key kUserErrorCancelTransactionDomain.

Error Description
400 One or more parameters in the request is invalid.
403 The user must be logged in to make this call.
419 The checkout token provided is invalid.
500 An unknown error occurred internally in the server.