B2B Mobile Transaction API - Use Cases

Cash withdrawal with surcharge

The following diagram shows the points of interaction in the transaction flow for:

  • A mobile wallet that withdraws cash from an ATM using Paydiant’s cardless cash access.
  • The ATM applies a surcharge fee to the withdrawal amount.
  • The user must consent to the surcharge application.

Cash Withdrawal with surcharge

  1. User taps mobile cash on the ATM screen and the ATM requests the checkout token from Paydiant, then displays the QR Code and requests the user’s profile.
  2. User scans the displayed QR Code and the app backend requests relevant transaction data.
  3. Paydiant returns relevant information to app backend.
  4. App backend submits the withdrawal ticket and Paydiant sends selection data to ATM.
  5. Optional: ATM submits the surcharge and Paydiant updates the ticket and sends to the app backend.
  6. The app backend updates the ticket with user consent and Paydiant notifies the ATM.
  7. ATM obtains bank authorization through its switch.
  8. Paydiant returns confirmation to app backend. Optional: Update surcharge if processed fee is reduced from default amount.

The following code samples show the configuration of each of the three calls in the transaction that originate from the mobile app service backend through the B2B Gateway:

  1. retrieveMobileTransactionMetadata (DISCOVERY) for withdrawal.
    executingFlowRule set to RETRIEVE_TRANSACTION_META_DATA_DISCOVERY
    discoveryType set to CASH_ACCESS
  2. updateMobileTransaction (SUBMIT_CASH_ACCESS_TICKET) for withdrawal.
    executingFlowRule set to SUBMIT_CASH_ACCESS_TICKET
    cashAccessDetail set cashAccessType to WITHDRAWAL
  3. updateMobileTransaction (CONFIRM_TRANSACTION) for withdrawal
    executingFlowRuleset to CONFIRM_TRANSACTION

retrieveMobileTransactionMetadataRequest (DISCOVERY) for withdrawal

{
  "retrieveMobileTransactionMetadataRequest":{
    "messageHeader":{
      "partnerId":"test-partner-id-0001",
      "messageId":"test-message-id",
      "versionId":"test-version-id-0.0.1",
      "environmentId":"sandbox"
    },
    "tenant":{
      "partnerUri":"paydiant:entity:partner#XXX",
      "tenantUri":"tnt001:entity:issuingpartner#XXX"
    },
    "customerUri":"tnt001:entity:customer#XXX",
    "deviceUri":"tnt001:entity:device#XXX",
    "deviceUniqueId":"XXX",
    "checkoutTokenValue":"XXX",
    "paydiantReferenceId":null,
    "receiptParameters":null,
    "offerParameters":null,
    "executingFlowRule":"RETRIEVE_TRANSACTION_META_DATA_DISCOVERY",
    "discoveryType":"CASH_ACCESS",
    "siteCheckInDetail":null,
    "invoiceId":null
  }
}

Response

{
  "retrieveMobileTransactionMetadataResponse":{
    "messageHeader":{
      "partnerId":"test-partner-id-0001",
      "messageId":"test-message-id",
      "versionId":"test-version-id-0.0.1",
      "environmentId":"sandbox"
    },
    "status":{
      "statusCode":"SUCCESS",
      "statusDescription":"SUCCESS",
      "statusDetails":[ ]
    },
    "configurationDetails":[
    ],
    "refundableReceipts":null,
    "eligibleOffers":null,
    "transactionMetaData":{
      "acceptanceLocation":{
        "uri":"apdev-1685:entity:acceptancelocation#XXX",
        "acceptancePartner":{
          "logoUrl":"https://localhost:8443/logo/abc/merchant_logo_abc.png",
          "modifiedTime":1479209408820,
          "name":"Acceptance Partner",
          "partnerUri":"paydiant:entity:partner#XXX",
          "uri":"apdev-1685:entity:acceptancepartner#XXX",
          "cardSurfaceDiscountLabel":""
        },
        "address1":"512 Commonwealth Avenue",
        "address2":"",
        "city":"boston",
        "country":"US",
        "currencyCode":"USD",
        "name":"MYBANK",
        "state":"MA",
        "storeCode":"ATM00100",
        "zipCode":"02110",
        "tippingEnable":false
      },
      "supportedPaymentTenders":[
        {
          "tenderType":{
            "accountTypeName":"Debit",
            "accountTypeUri":"paydiant:payment-account-management.accounttype#Debit",
            "networkTypeName":"NYCE",
            "networkTypeUri":"paydiant:payment-account-management.networktype#NYCE"
          },
          "splitPaymentEnabled":false
        },
        {
          "tenderType":{
            "accountTypeName":"PayPal",
            "accountTypeUri":"paydiant:payment-account-management.accounttype#PayPal",
            "networkTypeName":"CCA",
            "networkTypeUri":"paydiant:payment-account-management.networktype#CCA"
          },
          "splitPaymentEnabled":false
        }
      ],
      "siteLocation":null
    },
    "transactionStatus":"ACTIVE",
    "transactionDetail":{
      "transactionAmountSummary":{
        "totalTaxAmount":0.0,
        "transactionAmount":0.0,
        "transactionPointsAmount":0.0,
        "totalAmountDue":0.0,
        "totalAmountPaid":0.0,
        "totalPointsDue":0.0,
        "totalPointsPaid":0.0,
        "totalTipAmount":0.0,
        "totalOfferDiscountAmount":0.0
      },
      "ticket":null,
      "redeemedOffers":[
      ],
      "loyaltyAccrualActivities":[
      ],
      "posRequestedPayments":[
      ],
      "posUtilizedOffers":[
      ],
      "currentPaymentResult":null,
      "previousPaymentResults":[
      ],
      "posRequestMobileTender":null,
      "processedPreAuthPaymentResults":[ ]
    },
    "nextExecutingFlowRule":"SUBMIT_CASH_ACCESS_TICKET",
    "currentExecutingFlowRule":"RETRIEVE_TRANSACTION_META_DATA_DISCOVERY",
    "transactionFlowRuleSpecifications":[
      {
        "expectsCheckoutToken":false,
        "expectsPaydiantReferenceId":false,
        "stepNumber":2,
        "stepOptional":false,
        "transactionFlowRule":"RETRIEVE_TRANSACTION_META_DATA_DISCOVERY",
        "transactionType":"ATM_CASH_ACCESS",
        "addtionalRuleProcessingMetaData":[
          {
            "key":"KEY",
            "value":"VALUE"
          }
        ],
        "blockUntilEvents":[
          "TRANSACTION_COMPLETE",
          "DO_NOT_BLOCK"
        ],
        "eligibleOfferType":"NONE",
        "executeRuleAfterTimeoutForPreExecutionEvent":false,
        "executeRuleAndPollForResult":false,
        "expectsOffers":false,
        "expectsPaymentTenders":false,
        "expectsTransactionData":false,
        "numberOfTimesToRetryRequest":0,
        "pollUntilTransactionErrorStatuses":[  ],
        "pollUntilTransactionSuccessStatuses":[  ],
        "preExecutionEventWaitTime":0,
        "requestProcessingTimeInSeconds":30,
        "returnEligibleOffers":false,
        "returnNextProcessingRule":true,
        "returnTransactionDetails":true,
        "returnTransactionStatus":true,
        "transactionStatusesAfterRuleExecution":[
          "PROCESSING",
          "ACTIVE"
        ],
        "transactionStatusesBeforeRuleExecution":[  ],
        "waitForPreExecutionEvent":"DO_NOT_BLOCK",
        "waitTime":45000,
        "returnTransactionMetaData":true,
        "returnRefundableReceipts":false
      },
      {
        "expectsCheckoutToken":false,
        "expectsPaydiantReferenceId":true,
        "stepNumber":2,
        "stepOptional":false,
        "transactionFlowRule":"SUBMIT_CASH_ACCESS_TICKET",
        "transactionType":"ATM_CASH_ACCESS",
        "addtionalRuleProcessingMetaData":[
          {
            "key":"KEY",
            "value":"VALUE"
          }
        ],
        "blockUntilEvents":[
          "TRANSACTION_COMPLETE",
          "PAYMENT_FAILED"
        ],
        "eligibleOfferType":"NONE",
        "executeRuleAfterTimeoutForPreExecutionEvent":false,
        "executeRuleAndPollForResult":false,
        "expectsOffers":false,
        "expectsPaymentTenders":true,
        "expectsTransactionData":true,
        "numberOfTimesToRetryRequest":0,
        "pollUntilTransactionErrorStatuses":[ ],
        "pollUntilTransactionSuccessStatuses":[  ],
        "preExecutionEventWaitTime":0,
        "requestProcessingTimeInSeconds":0,
        "returnEligibleOffers":false,
        "returnNextProcessingRule":true,
        "returnTransactionDetails":true,
        "returnTransactionStatus":true,
        "transactionStatusesAfterRuleExecution":[
          "PROCESSING",
          "CLOSED",
          "FAILED"
        ],
        "transactionStatusesBeforeRuleExecution":[ ],
        "waitForPreExecutionEvent":"DO_NOT_BLOCK",
        "waitTime":45000,
        "returnTransactionMetaData":true,
        "returnRefundableReceipts":false
      },
      {
        "expectsCheckoutToken":false,
        "expectsPaydiantReferenceId":true,
        "stepNumber":3,
        "stepOptional":true,
        "transactionFlowRule":"CONFIRM_TRANSACTION",
        "transactionType":"ATM_CASH_ACCESS",
        "addtionalRuleProcessingMetaData":[
          {
            "key":"KEY",
            "value":"VALUE"
          }
        ],
        "blockUntilEvents":[
          "TRANSACTION_COMPLETE",
          "PAYMENT_FAILED"
        ],
        "eligibleOfferType":"NONE",
        "executeRuleAfterTimeoutForPreExecutionEvent":false,
        "executeRuleAndPollForResult":false,
        "expectsOffers":false,
        "expectsPaymentTenders":false,
        "expectsTransactionData":false,
        "numberOfTimesToRetryRequest":0,
        "pollUntilTransactionErrorStatuses":[ ],
        "pollUntilTransactionSuccessStatuses":[ ],
        "preExecutionEventWaitTime":0,
        "requestProcessingTimeInSeconds":0,
        "returnEligibleOffers":false,
        "returnNextProcessingRule":false,
        "returnTransactionDetails":true,
        "returnTransactionStatus":true,
        "transactionStatusesAfterRuleExecution":[
          "PROCESSING",
          "CLOSED",
          "FAILED"
        ],
        "transactionStatusesBeforeRuleExecution":[ ],
        "waitForPreExecutionEvent":"DO_NOT_BLOCK",
        "waitTime":45000,
        "returnTransactionMetaData":true,
        "returnRefundableReceipts":false
      }
    ],
    "checkoutToken":{
      "checkoutTokenValue":"XXX",
      "checkoutTokenType":"CASH_ACCESS"
    },
    "paydiantReferenceId":"XXX",
    "nextTransactionFlowRuleSpecification":{
      "expectsCheckoutToken":false,
      "expectsPaydiantReferenceId":true,
      "stepNumber":2,
      "stepOptional":false,
      "transactionFlowRule":"SUBMIT_CASH_ACCESS_TICKET",
      "transactionType":"ATM_CASH_ACCESS",
      "addtionalRuleProcessingMetaData":[ ],
      "blockUntilEvents":[
        "TRANSACTION_COMPLETE",
        "PAYMENT_FAILED"
      ],
      "eligibleOfferType":"NONE",
      "executeRuleAfterTimeoutForPreExecutionEvent":false,
      "executeRuleAndPollForResult":false,
      "expectsOffers":false,
      "expectsPaymentTenders":true,
      "expectsTransactionData":true,
      "numberOfTimesToRetryRequest":0,
      "pollUntilTransactionErrorStatuses":[  ],
      "pollUntilTransactionSuccessStatuses":[ ],
      "preExecutionEventWaitTime":0,
      "requestProcessingTimeInSeconds":0,
      "returnEligibleOffers":false,
      "returnNextProcessingRule":true,
      "returnTransactionDetails":true,
      "returnTransactionStatus":true,
      "transactionStatusesAfterRuleExecution":[
        "PROCESSING",
        "CLOSED",
        "FAILED"
      ],
      "transactionStatusesBeforeRuleExecution":[ ],
      "waitForPreExecutionEvent":"DO_NOT_BLOCK",
      "waitTime":45000,
      "returnTransactionMetaData":true,
      "returnRefundableReceipts":false
    },
    "discoveryType":null,
    "externalEvents":[ ]
  }
}

updateMobileTransactionRequest (SUBMIT_CASH_ACCESS_TICKET) for withdrawal

{
  "updateMobileTransactionRequest":{
    "messageHeader":{
      "partnerId":"test-partner-id-0001",
      "messageId":"test-message-id",
      "versionId":"test-version-id-0.0.1",
      "environmentId":"sandbox"
    },
    "tenant":{
      "partnerUri":"paydiant:entity:partner#XXX",
      "tenantUri":"tnt001:entity:issuingpartner#XXX"
    },
    "customerUri":"tnt001:entity:customer#XXX",
    "deviceUri":"tnt001:entity:device#XXX",
    "deviceUniqueId":"XXX",
    "checkoutTokenValue":"XXX",
    "paydiantReferenceId":"XXX",
    "selectedPaymentInstruments":[
      {
        "paymentAccountUri":"acc1:accountmenagement:cardaccount#XXX",
        "tenderType":null,
        "additionalData":[

        ],
        "extendedPaymentTenderData":[
          {
            "key":"MAGNES_ID",
            "value":"magnesId"
          }
        ]
      }
    ],
    "customerConfirmationForPOSRequestedPayments":null,
    "executingFlowRule":"SUBMIT_CASH_ACCESS_TICKET",
    "cashAccessDetail":{
      "cashAccessType":"WITHDRAWAL",
      "cashAmount":10.0
    },
    "tipAmount":null,
    "offers":[

    ],
    "refundDetail":null,
    "secondaryIdentifier":null,
    "fuelAccessDetail":null,
    "mobileRequestedPayments":[

    ],
    "transactionMetaData":[

    ]
  }
}

Response

{
    "updateMobileTransactionResponse": {
        "messageHeader": {
            "partnerId": "test-partner-id-0001",
            "messageId": "test-message-id",
            "versionId": "test-version-id-0.0.1",
            "environmentId": "sandbox"
        },
        "status": {
            "statusCode": "SUCCESS",
            "statusDescription": "Status Description",
            "statusDetails": []
        },
        "configurationDetails": [],
        "transactionStatus": "PROCESSING",
        "transactionMetaData": {
            "acceptanceLocation": {
                "uri": "apdev-1685:entity:acceptancelocation#XXX",
                "acceptancePartner": {
                    "logoUrl": "https://localhost:8443/logo/target/merchant_logo_Target.png",
                    "modifiedTime": 1479209408929,
                    "name": "Acceptance Partner",
                    "partnerUri": "paydiant:entity:partner#XXX",
                    "uri": "apdev-1685:entity:acceptancepartner#XXX",
                    "cardSurfaceDiscountLabel": ""
                },
                "address1": "512 Commonwealth Avenue",
                "address2": "",
                "city": "boston",
                "country": "US",
                "currencyCode": "USD",
                "name": "MYBANK",
                "state": "MA",
                "storeCode": "ATM00100",
                "zipCode": "02110",
                "tippingEnable": false
            },
            "supportedPaymentTenders": [
                {
                    "tenderType": {
                        "accountTypeName": "Debit",
                        "accountTypeUri": "paydiant:payment-account-management.accounttype#Debit",
                        "networkTypeName": "NYCE",
                        "networkTypeUri": "paydiant:payment-account-management.networktype#NYCE"
                    },
                    "splitPaymentEnabled": false
                },
                {
                    "tenderType": {
                        "accountTypeName": "PayPal",
                        "accountTypeUri": "paydiant:payment-account-management.accounttype#PayPal",
                        "networkTypeName": "CCA",
                        "networkTypeUri": "paydiant:payment-account-management.networktype#CCA"
                    },
                    "splitPaymentEnabled": false
                }
            ],
            "siteLocation": null
        },
        "transactionDetail": {
            "transactionAmountSummary": {
                "totalTaxAmount": 0.0,
                "transactionAmount": 30.0,
                "transactionPointsAmount": 0.0,
                "totalAmountDue": 12.0,
                "totalAmountPaid": 0.0,
                "totalPointsDue": 0.0,
                "totalPointsPaid": 0.0,
                "totalTipAmount": 0.0,
                "totalOfferDiscountAmount": 0.0
            },
            "ticket": {
                "lineItems": [],
                "ticketType": "CASH_DEPOSIT",
                "cashierId": "",
                "cashierName": "",
                "checkNumber": "",
                "tableNumber": "",
                "discountAmount": 0.0,
                "discountedAmount": 0.0,
                "merchantTransactionRefId": "XXX",
                "taxAmount": 0.0,
                "originalAmountLessTaxes": 0.0,
                "amount": 0.0,
                "subTotal": 0.0,
                "terminalId": "62001",
                "totalTicketTipAmount": 0.0,
                "otherTransactionTypeDescription": "CASH_ACCESS",
                "transactionSubType": "OTHER",
                "fuelTicketDetail": null,
                "surcharge": 2.0,
                "checkRevision": "",
                "amountPoints": 0.0,
                "calculateTipAmount": 0.0,
                "includedGratuity": 0.0
            },
            "redeemedOffers": [],
            "cashAccessDepositProperties": {
                "availableBlance"
                "availableNow"
                "cashDeposits"
                "checkDepsoits"
            "loyaltyAccrualActivities": [],
            "posRequestedPayments": [],
            "posUtilizedOffers": [],
            "currentPaymentResult": null,
            "previousPaymentResults": [],
            "posRequestMobileTender": null,
            "processedPreAuthPaymentResults": []
        },
        "nextExecutingFlowRule": "CONFIRM_TRANSACTION",
        "currentExecutingFlowRule": "SUBMIT_CASH_ACCESS_TICKET",
        "checkoutToken": {
            "checkoutTokenValue": "XXX",
            "checkoutTokenType": "CASH_ACCESS"
        },
        "paydiantReferenceId": "XXX",
        "nextTransactionFlowRuleSpecification": {
            "expectsCheckoutToken": false,
            "expectsPaydiantReferenceId": true,
            "stepNumber": 3,
            "stepOptional": true,
            "transactionFlowRule": "CONFIRM_TRANSACTION",
            "transactionType": "CASH_WITHDRAWAL",
            "addtionalRuleProcessingMetaData": []
            "blockUntilEvents": [
                "TRANSACTION_COMPLETE",
                "PAYMENT_FAILED"
            ],
            "eligibleOfferType": "NONE",
            "executeRuleAfterTimeoutForPreExecutionEvent": false,
            "executeRuleAndPollForResult": false,
            "expectsOffers": false,
            "expectsPaymentTenders": false,
            "expectsTransactionData": false,
            "numberOfTimesToRetryRequest": 0,
            "pollUntilTransactionErrorStatuses": [],
            "pollUntilTransactionSuccessStatuses": [],
            "preExecutionEventWaitTime": 0,
            "requestProcessingTimeInSeconds": 0,
            "returnEligibleOffers": false,
            "returnNextProcessingRule": false,
            "returnTransactionDetails": true,
            "returnTransactionStatus": true,
            "transactionStatusesAfterRuleExecution": [
                "PROCESSING",
                "CLOSED",
                "FAILED"
            ],
            "transactionStatusesBeforeRuleExecution": [],
            "waitForPreExecutionEvent": "DO_NOT_BLOCK",
            "waitTime": 45000,
            "returnTransactionMetaData": true,
            "returnRefundableReceipts": false
        },
        "externalEvents": []
    }
}

updateMobileTransactionRequest (CONFIRM_TRANSACTION) for withdrawal

{
  "updateMobileTransactionRequest":{
    "messageHeader":{
      "partnerId":"test-partner-id-0001",
      "messageId":"test-message-id",
      "versionId":"test-version-id-0.0.1",
      "environmentId":"sandbox"
    },
    "tenant":{
      "partnerUri":"paydiant:entity:partner#XXX",
      "tenantUri":"tnt001:entity:issuingpartner#XXX"
    },
    "customerUri":"tnt001:entity:customer#XXX",
    "deviceUri":"tnt001:entity:device#XXX",
    "deviceUniqueId":"XXX",
    "checkoutTokenValue":"XXX",
    "paydiantReferenceId":"XXX",
    "selectedPaymentInstruments":[ ],
    "customerConfirmationForPOSRequestedPayments":true,
    "executingFlowRule":"CONFIRM_TRANSACTION",
    "cashAccessDetail":null,
    "tipAmount":null,
    "offers":[ ],
    "refundDetail":null,
    "secondaryIdentifier":null,
    "fuelAccessDetail":null,
    "mobileRequestedPayments":[ ],
    "transactionMetaData":[ ]
  }
}

Response

{
  "updateMobileTransactionResponse":{
    "messageHeader":{
      "partnerId":"test-partner-id-0001",
      "messageId":"test-message-id",
      "versionId":"test-version-id-0.0.1",
      "environmentId":"sandbox"
    },
    "status":{
      "statusCode":"SUCCESS",
      "statusDescription":"Status Description",
      "statusDetails":[ ]
    },
    "configurationDetails":[ ],
    "transactionStatus":"CLOSED",
    "transactionMetaData":{
      "acceptanceLocation":{
        "uri":"apdev-1685:entity:acceptancelocation#XXX",
        "acceptancePartner":{
          "logoUrl":"https://localhost:8443/logo/target/merchant_logo_Target.png",
          "modifiedTime":1479209408929,
          "name":"Acceptance Partner",
          "partnerUri":"paydiant:entity:partner#XXX",
          "uri":"apdev-1685:entity:acceptancepartner#XXX",
          "cardSurfaceDiscountLabel":""
        },
        "address1":"512 Commonwealth Avenue",
        "address2":"",
        "city":"boston",
        "country":"US",
        "currencyCode":"USD",
        "name":"MYBANK",
        "state":"MA",
        "storeCode":"ATM00100",
        "zipCode":"02110",
        "tippingEnable":false
      },
      "supportedPaymentTenders":[
        {
          "tenderType":{
            "accountTypeName":"Debit",
            "accountTypeUri":"paydiant:payment-account-management.accounttype#Debit",
            "networkTypeName":"NYCE",
            "networkTypeUri":"paydiant:payment-account-management.networktype#NYCE"
          },
          "splitPaymentEnabled":false
        },
        {
          "tenderType":{
            "accountTypeName":"PayPal",
            "accountTypeUri":"paydiant:payment-account-management.accounttype#PayPal",
            "networkTypeName":"CCA",
            "networkTypeUri":"paydiant:payment-account-management.networktype#CCA"
          },
          "splitPaymentEnabled":false
        }
      ],
      "siteLocation":null
    },
    "transactionDetail":{
      "transactionAmountSummary":{
        "totalTaxAmount":0.0,
        "transactionAmount":12.0,
        "transactionPointsAmount":0.0,
        "totalAmountDue":0.0,
        "totalAmountPaid":12.0,
        "totalPointsDue":0.0,
        "totalPointsPaid":0.0,
        "totalTipAmount":0.0,
        "totalOfferDiscountAmount":0.0
      },
      "ticket":{
        "lineItems":[ ],
        "ticketType":"CASH_WITHDRAWAL",
        "cashierId":"",
        "cashierName":"",
        "checkNumber":"",
        "tableNumber":"",
        "discountAmount":0.0,
        "discountedAmount":12.0,
        "merchantTransactionRefId":"XXX",
        "taxAmount":0.0,
        "originalAmountLessTaxes":12.0,
        "amount":12.0,
        "subTotal":10.0,
        "terminalId":"62001",
        "totalTicketTipAmount":0.0,
        "otherTransactionTypeDescription":"CASH_ACCESS",
        "transactionSubType":"OTHER",
        "fuelTicketDetail":null,
        "surcharge":2.0,
        "checkRevision":"",
        "amountPoints":0.0,
        "calculateTipAmount":0.0,
        "includedGratuity":0.0
      },
      "redeemedOffers":[ ],
      "loyaltyAccrualActivities":[ ],
      "posRequestedPayments":[ ],
      "posUtilizedOffers":[  ],
      "currentPaymentResult":{
        "paymentInstrument":{
          "paymentAccountUri":"acc1:accountmenagement:cardaccount#XXX",
          "tenderType":{
            "accountTypeName":"PayPal",
            "accountTypeUri":"paydiant:payment-account-management.accounttype#PayPal",
            "networkTypeName":"CCA",
            "networkTypeUri":"paydiant:payment-account-management.networktype#CCA"
          },
          "additionalData":[
            {
              "key":"MASKED_CARD_NUMBER",
              "value":"xxxxxxxxxxxx7894"
            },
            {
              "key":"NICK_NAME",
              "value":"Mr. MobileGateway's ATM"
            }
          ],
          "extendedPaymentTenderData":[  ]
        },
        "currencyCode":"USD",
        "paidOrRefundAmount":12.0,
        "paidOrRefundTime":1479986741932,
        "paydiantReferenceId":"XXX",
        "paymentStatus":"Approved",
        "paymentStatusCode":200,
        "externalPaymentStatusCode":"200",
        "externalPaymentStatusDescription":"Success",
        "paymentTransactionUri":"XXX",
        "additionalData":[ ]
      },
      "previousPaymentResults":[ ],
      "posRequestMobileTender":null,
      "processedPreAuthPaymentResults":[ ]
    },
    "nextExecutingFlowRule":null,
    "currentExecutingFlowRule":"CONFIRM_TRANSACTION",
    "checkoutToken":{
      "checkoutTokenValue":"XXX",
      "checkoutTokenType":"CASH_ACCESS"
    },
    "paydiantReferenceId":"XXX",
    "nextTransactionFlowRuleSpecification":null,
    "externalEvents":[ ]
  }
}

ATM deposit of cash and checks

The following diagram shows the points of interaction in the transaction flow for:

  • A mobile wallet to deposit cash and checks into an ATM using Paydiant’s cardless cash access.
  • The call sequence from the mobile app integrator for a deposit is identical to that of a withdrawal, except for some specific deposit elements that are populated differently from the cash withdrawal values.
  1. retrieveMobileTransactionMetadata (DISCOVERY) for deposit.
    This call is configured identically to the withdrawal example.
  2. updateMobileTransaction (SUBMIT_CASH_ACCESS_TICKET) for deposit.
    See link for details of the differences.
  3. updateMobileTransaction (CONFIRM_TRANSACTION) for deposit.
    The request is identical to the withdrawal but the response populates with deposit-related transactionDetails.

retrieveMobileTransactionMetadata (DISCOVERY) for deposit

This call is configured identically to the sample for retrieveMobileTransactionMetadata (DISCOVERY) for withdrawal.

updateMobileTransactionRequest (SUBMIT_CASH_ACCESS_TICKET) for deposit

In this call request, the cashAccessDetail object indicates the deposit using the cashAccessType, as shown in the following request exerpt:

...
"cashAccessDetail": {
    "cashAccessType": "DEPOSIT",
    "cashAmount": 0.0,
    },
...

Note: The request does not include the amount of the deposit. Once the user inputs the deposit, the ATM itemizes its contents and the response includes the results, as shown in the following response excerpt. In this case, a deposit of one ten-dollar bill for a total deposit amount of $10.00.

...
"transactionDetail":{
  "transactionAmountSummary":{
    "totalTaxAmount":0.0,
    "transactionAmount":10.0,
    "transactionPointsAmount":0.0,
    "totalAmountDue":0.0,
    "totalAmountPaid":10.0,
    "totalPointsDue":0.0,
    "totalPointsPaid":0.0,
    "totalTipAmount":0.0,
    "totalOfferDiscountAmount":0.0
  },
  "ticket":{
    "lineItems":[ ],
    "ticketType":"CASH_DEPOSIT",
    "cashierId":null,
    "cashierName":null,
    "checkNumber":null,
    "tableNumber":null,
    "discountAmount":0.0,
    "discountedAmount":10.0,
    "merchantTransactionRefId":"XXX",
    "taxAmount":0.0,
    "originalAmountLessTaxes":null,
    "amount":10.0,
    "subTotal":10.0,
    "terminalId":"72001",
    "totalTicketTipAmount":null,
    "otherTransactionTypeDescription":"CASH_ACCESS",
    "transactionSubType":"CASH_DEPOSIT",
    "fuelTicketDetail":null,
    "surcharge":null,
    "checkRevision":null,
    "amountPoints":null,
    "calculateTipAmount":null,
    "includedGratuity":null
  },
  "cashAccessDepositProperties":{
    "availableBalance":100.0,
    "availableNow":100.0,
    "cashDeposits":[
      {
        "billDenomination":10,
        "noOfBills":1
      }
    ],
    "checkDeposits":[ ],
    "noOfChecksDeposited":0,
    "postDate":"2017-04-05 08:11:19",
    "transactionSubType":"CASH_DEPOSIT"
  }
  

updateMobileTransactionRequest (CONFIRM_TRANSACTION) for deposit

The request call for the transaction confirmation is identical to that of the updateMobiletransactionrequest (CONFIRM_TRANSACTION) for withdrawal.

The response is similar to the withdrawal response, but the transactionDetails identify properties that are specific to a deposit (such as ticketType, transactionSubType, and paymentResult).

Fuel Transaction with Webhook Push

In a typical fuel transaction, the Merchant's app server uses a series of successive calls to the Paydiant platform to poll for the state of the fuel pump as it progresses through the transaction life cycle. An issuing partner can avoid the need to poll for the transaction state by implementing a webhook so that Paydiant can push the transaction lifecycle events to the Merchant as the events occur. If the push cannot be completed, the typical polling method is used as its fallback so both techniques must be implemented.

The following transaction flow digram shows using a webhook to perform a fuel transaction.

Sample fuel transaction with webhook push flow

Description API/Event
1. retrieveMobileTransactionMetadata
(DISCOVERY + FUEL_CHECKIN)
The mobile device validates the geo-location of the site and the user confirms the location, so the app server requests site data such as supported payment tenders, pump availability, site resources, or other details.
2. updateMobileTransaction
(SUBMITTENDER_FOR_FUEL_
WITH_FUEL_TICKET)
The user selects a fuel pump and a payment tender so the app server.
3. Webhook Push
(FUEL_PUMP_ACTIVATED)
After the platform receives the Pre-Auth confirmation from the payment processor, it calls the fuel site to request pump activation. When the site confirms the pump activation, the platform sends the webhook push notification with the retrieveMobileTransactionMetadata Webhook data needed for the PUMP_ACTIVE fuel event.
4. Webhook Push
(FUEL_BEGIN)
When the consumer lifts the fuel nozzle and begins fueling, the fuel site notifies the platform that fueling has begun. The platform sends a Webhook push notification with the retrieveMobileTransactionMetadata Webhook data needed for the FUEL_BEGIN fuel event.
5. Webhook Push
(FUEL_END)
When the consumer returns the fuel nozzle to the pump, the fuel site notifies the platform that fueling has ended along with a final amount due. The platform sends a Webhook push notification with the retrieveMobileTransactionMetadata Webhook data for the FUEL_END event and submits a payment authorization request to the payment processor.
6. Webhook Push
(RECEIPT_DATA)
When the platform receives payment authorization from the processor, it sends a Webhook push notification containing the retrieveMobileTransactionMetadata Webhook data for the RECEIPT_DATA fuel event and also sends the mobile receipt to the fuel site, completing the transaction.

Sample webhook payload

The following sample payload shows an example of the data that is pushed for a FUEL_PUMP_ACTIVATED portion of the transaction. The data is pushed in a JSON object. Null fields are not sent.

{
  "RetrieveMobileTransactionMetadataRequest":{
    "metaData":{
      "customerUri":"abc:entity:customer#116c2cab-4747-4295-a3be-2bcf15d5f243",
      "deviceUri":"7814419456-BB51-46A1-BDA8-32B652C9830G",
      "deviceUniqueId":"7814419456-BB51-46A1-BDA8-32B652C9830G"
    },
    "transactionMetaData":{
      "acceptanceLocation":{
        "uri":"fuelph1:entity:acceptancelocation#bcd3fa3d-3cbb-47ab-92d4-2636fe6baa24",
        "acceptancePartner":{
          "logoUrl":"logo/abc/merchant_logo_abc.png",
          "name":"abc_0315161645",
          "partnerUri":"paydiant:entity:partner#40299f26-8a9d-400f-9b8a-d619826dd732",
          "uri":"fuelph1:entity:acceptancepartner#4a47268c-880d-42e2-af06-c39a544eb5b7"
        },
        "address1":"272 Grove Street",
        "city":"Newton",
        "country":"US",
        "name":"FuelPh1Loc site0523165456",
        "state":"MA",
        "storeCode":"site0523165456",
        "zipCode":"02466"
      },
      "transactionStatus":"OPEN",
      "transactionDetail":{
        "transactionAmountSummary":{
          "totalTaxAmount":0.0,
          "transactionAmount":0.0,
          "transactionPointsAmount":0.0,
          "totalAmountDue":480.6,
          "totalAmountPaid":0.0,
          "totalPointsDue":0.0,
          "totalPointsPaid":0.0,
          "totalTipAmount":0.0,
          "totalOfferDiscountAmount":0.0
        },
        "ticket":{
          "lineItems":[ ],
          "ticketType":"FUEL",
          "discountAmount":0.0,
          "discountedAmount":480.6,
          "merchantTransactionRefId":"7a2xMNgCXMyz",
          "taxAmount":0.0,
          "originalAmountLessTaxes":480.6,
          "amount":480.6,
          "subTotal":480.6,
          "terminalId":"14",
          "otherTransactionTypeDescription":"FUEL",
          "transactionSubType":"FUEL",
          "fuelTicketDetail":{
            "additionalData":[ ],
            "fixedAmount":480.6,
            "printReceipt":false,
            "pumpNumber":"14"
          }
        },
        "redeemedOffers":[ ],
        "loyaltyAccrualActivities":[ ],
        "posRequestedPayments":[ ],
        "posUtilizedOffers":[ ],
        "currentPaymentResult":{
          "paidOrRefundAmount":0.0,
          "paymentStatusCode":0,
          "additionalData":[ ],
          "mobileReceivedPaymentProcessedMetaData":[ ]
        },
        "previousPaymentResults":[ ],
        "processedPreAuthPaymentResults":[
          {
            "paymentInstrument":{
              "paymentAccountUri":"abc:accountmenagement:cardaccount#d340cb63-c8fe-4a1b-b870-126a0505b57d",
              "tenderType":{
                "accountTypeUri":"paydiant:payment-account-management.accounttype#sampleacctype",
                "networkTypeUri":"paydiant:payment-account-management.networktype#samplenetwktype"
              },
              "additionalData":[ ],
              "extendedPaymentTenderData":[ ]
            },
            "currencyCode":"USD",
            "paidOrRefundAmount":480.6,
            "paidOrRefundTime":1538409726918,
            "paydiantReferenceId":"5bb4c64f-d20e-4c84-9942-f3d2c861a0eb",
            "paymentStatus":"Authorization approved",
            "paymentStatusCode":210,
            "externalPaymentStatusCode":"SIMULATION_MODE",
            "externalPaymentStatusDescription":"In simulation mode",
            "paymentTransactionUri":"fuelph1:connector-sample:transactionsummary#d4893f7f-def3-4997-970b-2001c7cd9131",
            "additionalData":[ ],
            "mobileReceivedPaymentProcessedMetaData":[ ]
          }
        ]
      },
      "checkoutToken":{
        "checkoutTokenValue":"abc.hlwdGeMzDUcZ",
        "checkoutTokenType":"FUEL"
      },
      "paydiantReferenceId":"5bb4c64f-d20e-4c84-9942-f3d2c861a0eb",
      "externalEvents":[
        {
          "additionalData":[ ],
          "externalEventType":"FUEL_PUMP_ACTIVATED"
        }
      ]
    }
  }
}

Next

Feedback