Cash Advance

A cash advance is the purchase of cash using a credit card. Cash advance is only supported for merchants with a specific Merchant Category Code (MCC). This typically includes financial institutions such as banks.

note

Cash Advance is not supported for debit cards.

Code Samples

CWS

Request

Property	Description
method string \| required	`startPaymentTransaction`
requestId string \| required	Transaction Request ID
targetType string \| required	`paymentGatewayConverge`
parameters JSONObject \| required	All relevant parameters for Cash Advance transactions.
paymentGatewayId string \| required	Payment Gateway ID Unique identifier of the payment gateway as returned in the openPaymentGateway transaction response.
transactionType string \| required	Transaction Type Valid value: CASH_ADVANCE
tenderType string \| required	Tender Type Valid value: CARD
baseTransactionAmount JSONObject \| required	The amount of the Cash Advance transaction `“baseTransactionAmount” : { “currencyCode” : “USD”, “value” : 2000 }` NOTE: Value for monetary amounts is always in minor units.

Start the transaction

{
  "method" : "startPaymentTransaction",
  "requestId" : "832364634",
  "targetType" : "paymentGatewayConverge",
  "parameters" : {
    "paymentGatewayId" : "11b0032b-eb0d-4d9a-8664-eb430684cb92",
    "transactionType" : "CASH_ADVANCE",
    "tenderType" : "CARD",
    "baseTransactionAmount" : {
      "value" : 2000,
      "currencyCode" : "USD"
    }
  }
}

Later to query the status of the transaction

{
  "method" : "getPaymentTransactionStatus",
  "requestId" : "832364635",
  "targetType" : "paymentGatewayConverge",
  "parameters" : {
    "paymentGatewayId" : "11b0032b-eb0d-4d9a-8664-eb430684cb92",
    "chanId" : "8ac52fbd-d251-4fb3-a90b-e07e2ace7cfc"
  }
}

Response

Initial response to startPaymentTransaction request

{
  "requestId" : "832364634",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : false,
      "eventQueue" : [
        {
          "timeStamp" : "1658351823412",
          "statusDetails" : "STARTING"
        }
      ],
      "chanId" : "8ac52fbd-d251-4fb3-a90b-e07e2ace7cfc"
      }
   }
}

Complete response

{
  "requestId" : "832364635",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : true,
      "chanId" : "8ac52fbd-d251-4fb3-a90b-e07e2ace7cfc",
      "paymentTransactionData" : {
        "transactionType" : "CASH_ADVANCE",
        "tenderType" : "CARD",
        "result" : "APPROVED",
        "id" : "200722A3F-8E973388-857F-479A-BD6D-73F46EB8E2D6",
        "date" : "Wed Jul 20 17:17:27 EDT 2022",
        "maskedPan" : "54**********4111",
        "cardType" : "CREDIT",
        "cardEntryType" : "EMV_PROXIMITY",
        "cardScheme" : "MASTERCARD",
        "authCode" : "QMC062",
        "isFallback" : false,
        "amountAuthorized" : {
          "value" : 2000,
          "currencyCode" : "USD"
        },
        "amount" : {
          "value" : 2000,
          "currencyCode" : "USD"
        },
        "oarData" : "010001432307202117270720000173400000000000QMC062MCC0E7CAC",
        "ps2000Data" : "MMCC0E7CAC      0720A1",
        "iccAid" : "A0000000041010",
        "iccArc" : "00",
        "iccAtc" : "022F",
        "iccIad" : "0110a00003220000000000000000000000ff",
        "iccAppName" : "MASTERCARD",
        "iccTsi" : "c000",
        "iccTvr" : "0400008001",
        "iccCvmr" : "NO_CVM_REQUIRED",
        "iccCsn" : "01",
        "iccMode" : "ICC_MODE",
        "approved" : "yes",
        "errors" : []
      }
    }
  }
}

Java

Initialize Commerce SDK and receive an ECLAccountInterface instance named account.
Create a transaction reference.

ECLMoney amount = new ECLMoney(ECLCurrencyCode.USD, 2000);
ECLCurrencyTransactionInterface transaction = account.getTransactionProcessor().createCashAdvanceTransactionWithTotal(amount);

Note: See the Sale page for more details around starting a transaction and receiving the result.

Objective-C

Initialize Commerce SDK and receive an ECLAccountProtocol instance named account.
Create a transaction protocol.

ECLMoney *amount = [[ECLMoney alloc] initWithMinorUnits:2000 withCurrencyCode:ECLCurrencyCode_USD];
id<ECLCurrencyTransactionProtocol> transaction = [[_account transactionProcessor] createCashAdvanceTransactionWithTotal:amount];

Note: See the Sale page for more details around starting a transaction and receiving the result.

C#

PaymentArgs paymentArgs = new PaymentArgs();
paymentArgs.paymentGatewayId = m_PaymentGatewayId;
paymentArgs.transactionType = TransactionType.CASH_ADVANCE;
paymentArgs.tenderType = TenderType.CARD;
paymentArgs.baseTransactionAmount = new Money(CurrencyCode.USD, 2000);  
 
m_CWS.StartPaymentTransaction(paymentArgs, MyNotifyCWSEvent, MyPaymentComplete);