iOS SDK - Transaction Module
Last updated: Sept 18th, 9:03pm
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:
- Create a new request object for the relevant coordinator.
- Implement the delegate for the coordinator to handle responses.
1self.transactionCoordinator = [[PDTransactionCoordinator alloc] init];2self.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:kPDTransactionTypePurchasekPDTransactionTypeReturnkPDTransactionTypeCashAccesskPDTransactionTypeUnknown |
| 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 request 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 request 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 request 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 request 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:kPDCashAccessTransactionTypeWithdrawalkPDCashAccessTransactionTypeUnknowncashAmount - 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. |