Home > API General, Payments > SWS MakePayment Method

SWS MakePayment Method


Allows for payment on an account for rental and/or retail items. Any unused amount will be applied to their account as cash credit/escrow, if the site rules allow. Partial payments are not allowed through the API. This payment method allows you to use two payment types at one time, with up to three payments per type. Due to system restrictions you will not be able to use multiple payment types, if there are multiple units and a check is involved. To apply the check, use it towards one unit. The balance will apply to cash credit/escrow which can be used towards the remaining payment/s.

Parameters

Name DataType Is Required
AcctID Long Required
Description The account’s ID number. This is returned when you use the CreateNewAccount method or can be retrieved with the SearchBy method.
CashCreditAmount Decimal Optional
Description You can find the amount of cash credit/escrow on the account using the GetCashCredit method. If you are using any portion of a cash credit/escrow, this is required to tell the system how much of the cash credit/escrow to use.
CashCreditID Decimal Optional
Description You can find the amount of cash credit/escrow on the account using the GetCashCredit method. If you are using any portion of a cash credit/escrow, this is required to tell the system which cash credit to use for the cash credit amount if there are multiple cash credits.
CashInfo Decimal Optional*
Description This is the total amount of the cash portion of the payment.
* At least one form of payment is required.
CheckInfo CheckData Optional*
Description If making a check payment, you can use the CheckData object for up to three checks.
* At least one form of payment is required.
CreditCardInfo CreditCardData Optional*
Description If making a credit card payment, you can use the CreditCardData object for up to three credit cards.
* At least one form of payment is required.
Cycles Integer Array Optional
Description The number of rental cycles/periods for which the payment will apply. If no cycles are passed in it is assumed only one cycle should be paid. You are limited to the number of cycles you can apply based on the “Allowed Number of Days Paid Ahead” rule for the site. This can be found using the GetSiteRules method. This array must contain the same number of items as the RentalIDs. The arrays will match one to one when determining how many cycles to pay on each rental item. For example if an account has two rentals and you wish to pay for 2 cycles on the first and 1 cycle on the second, the value for this field would be {2,1}.
IsRetail Boolean Required
Description Indicates if the payment will be for only retail assessments (“True”) or only for rental assessments (“False”).
IsRetailAndRental Boolean Required
Description Indicates if the payment will be for both retail and rental assessments (“True”) or only for rental assessments (“False”).
MoveOutDate DateTime Optional
Description The date applied when vacating a rental item. This defaults to today’s date unless otherwise specified, if the payment is for a move out. The date can be set in the past, based on the site’s End Rental rule settings. This can be found using the GetSiteRules method. No future dates are allowed.
PayAssessData AssessmentData Optional
Description Allows a tenant to pay for specific assessments on a rental item instead of the amount due. This will allow a customer to pay one month of assessment if they are delinquent.
RentalIDs Long Array Optional
Description The rental item’s ID number, or an array of rental IDs, to specify which units are to be paid. If no IDs are passed in, all rentals on the account are paid. This array must contain the same number of items as the cycles. The arrays will match one to one when determining how many cycles to pay on each rental item.
SiteID Long Required
Description The site’s ID number. This can be found using the GetSiteList method.
TaxExemptNumber String Optional
Description If the organization is tax exempt, the tax ID must be included here. If the tax ID number is not the same as it is for the rental or if the rental is not tax exempt, multiple MakePayment transactions must be completed. String limit 20 characters.
TotalAmtDue Decimal Required
Description The total amount due based on the rental IDs, retail items, tax and other assessments. To obtain the total due, see the GetAssessments and GetTotalDue methods.
TotalAmtPaid Decimal Required
Description The total amount paid for the rental item which amounts to the total amount due. Only payment in full is accepted. The entire amount is applied.

Returned Parameters

Name DataType
CashCreditApplied Boolean
Description Indicates if an existing cash credit/escrow was successfully applied to the payment (“True”) or not (“False”).
TranID Long
Description The transaction’s ID number. Transaction IDs are system generated for each payment transaction that occurs in the system. A null or “0” response indicates the transaction failed.

Example

As with every method we need to pass in credentials. We do this with the LookupUser request object.

We’ll assume you’ve got a web reference, let’s name it SWS, in your Visual Studio project.  At this point we need to our objects.  We’ll need the standard service object, a MakePayment request object and a MakePayment response object. I am alos creating a CardData object as this example is for a credit card payment.

// Create a request and response objects
SWS.WSSoapClient service = new SWS.WSSoapClient();
SWS.MakePayment_Request request = new SWS.MakePayment_Request();
SWS.MakePayment_Response response;

SWS.CreditCardData cardRequest = new SWS.CreditCardData();

Here’s my sample code of the Request object paying for two rentals on an account for 2 cycles on each rental using a credit card.

// MakePayment Request
cardRequest.CardHolderName = "John Doe";
cardRequest.CardNumber = "4111111111111111";
cardRequest.CVV2 = "111";
cardRequest.ExpireMonth = "02";
cardRequest.ExpireYear = "2020";
cardRequest.Amount = 100m;

request.SiteID = 123456;
request.AcctID = 123456;
request.RentalIDs = new long[] { 123456, 456789 };
request.Cycles = new int[] { 2, 2 };
request.IsRetail = false;
request.TotalAmtDue = 100m;
request.TotalAmtPaid = 100m;
request.CreditCardInfo = new SWS.CreditCardData[] { cardRequest };

Finally we can call the method and pass across the login object and the request object to make our payment. It’s a good idea to do this in a Try Catch block.

// Call the method that will load the response object
try
{
  response = service.MakePayment(user_request, request);
}
catch (Exception ex)
{
  MessageBox.Show(ex.Message);
}

Note that if something goes wrong the service will respond with an exception. You’ll want to take a look at that message returned in that exception so it can be debugged.

For a full list of methods see SWS Methods.

Categories: API General, Payments Tags:
  1. swsBecky
    April 24, 2017 at 3:09 pm

    Updated August 17, 2012:The upcoming product update will change how MakePayment handles the check payment type. Multiple checks will no longer be accepted on a single transaction and checks cannot be mixed with any other payment types when paying for multiple rentals. These changes were made to overcome some complications that arose when multiple checks were on the same transaction and one or more of those checks were later returned because of insufficient funds.

    I’ve put together a couple of examples demonstrating code that works today but will return errors after the update.

    Example 1

    A tenant has a rental with a rate of $100/mo and wants to pay for one month with two checks. The code for the request is going to look something like this.

    SwsAsmx.MakePayment_Request reqPayment = new SwsAsmx.MakePayment_Request()
    {
    SiteID = 1000000012,
    AcctID = 1000000123,
    RentalIDs = new long[] { 1000001014 },
    IsRetail = false,
    IsRetailAndRental = false,
    TotalAmtDue = 100m,
    TotalAmtPaid = 100m,
    CheckInfo = new SwsAsmx.CheckData[] {
    new SwsAsmx.CheckData()
    {
    CheckType = SwsAsmx.paymentTypeLookupOrder.CHECK,
    CheckNumber = 123456,
    Amount = 75m
    },
    new SwsAsmx.CheckData()
    {
    CheckType = SwsAsmx.paymentTypeLookupOrder.CHECK,
    CheckNumber = 876543,
    Amount = 25m
    }
    }
    };
    SwsAsmx.MakePayment_Response payment = swsClientProxy.MakePayment(swsLogin, reqPayment);
    Currently, the payment will succeed and there will be a transaction recorded with the payment spread across two checks. After the update, the MakePayment method will throw an error with the message:

    Payment with multiple checks is not allowed.

    One way to permit this scenario is to remember that any payment through SWS that is not exactly the amount due will go to cash credit. So you can make a payment with the first check, which will generated cash credit, and use that cash credit with the second check in another transaction to complete the payment in full.

    SwsAsmx.MakePayment_Request reqPayment = new SwsAsmx.MakePayment_Request()
    {
    SiteID = 1000000012,
    AcctID = 1000000123,
    RentalIDs = new long[] { 1000001014 },
    IsRetail = false,
    IsRetailAndRental = false,
    TotalAmtDue = 100m,
    TotalAmtPaid = 75m,
    CheckInfo = new SwsAsmx.CheckData[] {
    new SwsAsmx.CheckData()
    {
    CheckType = SwsAsmx.paymentTypeLookupOrder.CHECK,
    CheckNumber = 123456,
    Amount = 75m
    }
    }
    };
    SwsAsmx.MakePayment_Response payment = swsClientProxy.MakePayment(swsLogin, reqPayment);
    SwsAsmx.GetCashCreditsRequest reqCashCredit = new SwsAsmx.GetCashCreditsRequest()
    {
    LookupUser_Request = swsLogin,
    Request = new SwsAsmx.GetCashCredits_Request()
    {
    SiteID = 1000000012,
    AccountID = 1000000123,
    RentalID = 1000001014
    }
    };
    SwsAsmx.GetCashCreditsResponse cashCredit = swsClientProxy.GetCashCredits(reqCashCredit);
    long escrowID = cashCredit.GetCashCreditsResult.Where(cc => 1 == cc.CREDIT_TYPE && 75m == cc.BALANCE).Select(cc => cc.ESCROW_ID).First();
    reqPayment = new SwsAsmx.MakePayment_Request()
    {
    SiteID = 1000000012,
    AcctID = 1000000123,
    RentalIDs = new long[] { 1000001014 },
    IsRetail = false,
    IsRetailAndRental = false,
    TotalAmtDue = 100m,
    TotalAmtPaid = 25m,
    CashCreditID = escrowID,
    CheckInfo = new SwsAsmx.CheckData[] {
    new SwsAsmx.CheckData()
    {
    CheckType = SwsAsmx.paymentTypeLookupOrder.CHECK,
    CheckNumber = 876543,
    Amount = 25m
    }
    }
    };
    payment = swsClientProxy.MakePayment(swsLogin, reqPayment);
    The transaction history will not be as tidy as before but you will be able to process each check separately in case of NSFs.

    Example 2

    A tenant has two rentals, each with a $100/mo rent rate, and wants to pay for one month on both with a check and some cash. The code for the request will look something like this.

    SwsAsmx.MakePayment_Request reqPayment = new SwsAsmx.MakePayment_Request()
    {
    SiteID = 1000000012,
    AcctID = 1000000123,
    RentalIDs = new long[] { 1000001014, 1000001057 },
    IsRetail = false,
    IsRetailAndRental = false,
    TotalAmtDue = 200m,
    TotalAmtPaid = 200m,
    CashInfo = 50m,
    CheckInfo = new SwsAsmx.CheckData[] {
    new SwsAsmx.CheckData()
    {
    CheckType = SwsAsmx.paymentTypeLookupOrder.CHECK,
    CheckNumber = 123456,
    Amount = 150m
    }
    }
    };
    SwsAsmx.MakePayment_Response payment = swsClientProxy.MakePayment(swsLogin, reqPayment);
    This is currently allowed and results in a transaction with the payment spread across two forms of payment. However, there is no way to know which of the two rentals received how much from each payment type. If the check were to be returned at a later point for insufficient funds, we don’t know which of the two rentals will have $50 remaining on its balance and which will owe the entire rent amount. After the update, MakePayment will throw an exception when it detects multiple rentals with multiple payment types containing this message:

    Payment for multiple rentals with mixed payment types that includes checks is not allowed.

    Again, one possibility is to break up the single transaction into separate calls to MakePayment. Make one call to MakePayment with the check and a second one using the cash credit from the first call and the cash payment.

    SwsAsmx.MakePayment_Request reqPayment = new SwsAsmx.MakePayment_Request()
    {
    SiteID = 1000000012,
    AcctID = 1000000123,
    RentalIDs = new long[] { 1000001014, 1000001057 },
    IsRetail = false,
    IsRetailAndRental = false,
    TotalAmtDue = 200m,
    TotalAmtPaid = 150m,
    CheckInfo = new SwsAsmx.CheckData[] {
    new SwsAsmx.CheckData()
    {
    CheckType = SwsAsmx.paymentTypeLookupOrder.CHECK,
    CheckNumber = 123456,
    Amount = 150m
    }
    }
    };
    SwsAsmx.MakePayment_Response payment = swsClientProxy.MakePayment(swsLogin, reqPayment);
    SwsAsmx.GetCashCreditsRequest reqCashCredit = new SwsAsmx.GetCashCreditsRequest()
    {
    LookupUser_Request = swsLogin,
    Request = new SwsAsmx.GetCashCredits_Request()
    {
    SiteID = 1000000012,
    AccountID = 1000000123,
    RentalID = 1000001014
    }
    };
    SwsAsmx.GetCashCreditsResponse cashCredit = swsClientProxy.GetCashCredits(reqCashCredit);
    long escrowID = cashCredit.GetCashCreditsResult.Where(cc => 1 == cc.CREDIT_TYPE && 150m == cc.BALANCE).Select(cc => cc.ESCROW_ID).First();
    reqPayment = new SwsAsmx.MakePayment_Request()
    {
    SiteID = 1000000012,
    AcctID = 1000000123,
    RentalIDs = new long[] { 1000001014, 1000001057 },
    IsRetail = false,
    IsRetailAndRental = false,
    TotalAmtDue = 200m,
    TotalAmtPaid = 200m,
    CashCreditID = escrowID,
    CashInfo = 50m
    };
    payment = swsClientProxy.MakePayment(swsLogin, reqPayment);

    This only affects payment types of check. Even though money orders and travelers checks are passed in using the CheckData structure, they have a different CheckType and so they don’t have the same restrictions.

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: