Archive
SWS GetTransactionDetails Method
Returns receipt detail information for the specified transaction ID(s).
Parameters
| Name | DataType | Is Required |
|---|---|---|
| SiteID | Long | Required |
| Description | The site’s ID number. This can be found using the GetSiteList method. | |
| TransactionIDs | ArrayOfLong | Required |
| Description | The transaction’s ID number. Transaction IDs are system generated for each payment transaction that occurs in the system. The transaction ID is returned when any MakePayment method is used. | |
Returned Parameters
| Name | DataType |
|---|---|
| TransactionID | 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. |
| ErrorMsg | String |
| Description | If there is an error processing this method this will provide text about the problem that occurred. |
| TransactionDate | DateTime |
| Description | The date the transaction occured. |
| TransactionTime | String |
| Description | The time the transaction occured. |
| PaymentAmount | Decimal |
| Description | The total amount to be paid after all assessments and credits are applied. |
| EscrowCreditAmount | Decimal |
| Description | The amount of the funds taken that were applied to cash credit/escrow. |
| Type | String |
| Description | The type of transaction that occurred. |
| Status | String |
| Description | The status of the transaction. |
| Agent | String |
| Description | The name of the user that completed the transaction. |
| AccountName | String |
| Description | The name on the account where the transaction occurred. This may differ from the primary contact’s name in some instances, such as a business account or a guardianship account. |
| TransactionPaymentMethod: PaymentMethod | String |
| Description | The type of payment that was received for the transaction. |
| TransactionPaymentMethod: Amount | Decimal |
| Description | The total amount to be paid after all assessments and credits are applied. |
| TransactionPaymentMethod: AmountTendered | Decimal |
| Description | The amount received from the customer. |
| TransactionPaymentMethod: CashBack | Decimal |
| Description | If the payment was cash, this indicates the cash returned to the customer. |
| TransactionReceiptDetail: ChargeDate | DateTime |
| Description | The date the transaction occurred. |
| TransactionReceiptDetail: ItemDescription | String |
| Description | The name of the assessment that was paid. |
| TransactionReceiptDetail: Amount | Decimal |
| Description | The amount of the particular assessment. |
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 GetTransactionDetails request object and a GetTransactionDetails response object. We can define and create those like this:
// Create a request and response objects
SWS.WSSoapClient service = new SWS.WSSoapClient();
SWS.GetTransactionDetails_Request request = new SWS.GetTransactionDetails_Request();
SWS.GetTransactionDetails_Response response;
Here’s my sample code of the Request object.
// GetTotalDuePastDue Request
request.SiteID = 123456;
request.TransactionIDs = new long[] { 123456 };
Finally we can call the method and pass across the login object and the request object to retrieve the transaction details. 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.GetTransactionDetails(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.
Workflow for Creating a Reservation or Rental
Entities
The following is a flow chart of the main entities involved in creating a rental or reservation in SWS.
An account can have multiple contacts and multiple rentals. A rental must have a primary contact (Contact Type = ACCOUNT_MANAGER) and can have additional secondary contacts. Site rules may require at least one secondary contact as well. A contact that is primary on one rental may be primary, secondary or not related at all to another rental on the account. The account name for personal accounts is the last name, first name of the first contact added to the account. For business accounts an account name should be specified. Each rental will be associated with the unit being rented. The unit has a number assigned by the organization and a primary key known as the UnitID. The two are often confused. If you are displaying information to a tenant you will generally want to use the Unit Number. If you are renting or adjusting a unit in code the unit ID, as the item’s primary key, is generally required.
Finding A Unit and Dynamic Pricing
The first step is displaying the available units. There are multiple options for this: GetSiteUnitData, GetSiteUnitDataV2, GetSiteUnitDataV3, GetUnitData and GetUnitDataWithPromos. GetUnitData returns ALL units in a site along with their pertinent information including ID’s and its version number which will be important when reserving the unit. This method allows a site to customize grouping, pricing and promos to their specifications. It means a little more work, but things will come out exactly how the organization prefers. The only required parameter is the SiteID, the rest of the parameters allow for filtering the results and are all optional. The GetSiteUnitData methods return a single unit based on a pre-set grouping. This grouping takes Width, Depth, Door, Climate, Access Type and Features values into account. For example, if you have ten 5X5 units, half that are climate controlled and half not, you will receive back, IF available, two units, one with climate control and one without. You also have the option to include the best available promotion for each item selected. Again, SiteID is the only required field. There are fewer filter options on this as the items have already been winnowed down. Also failing to indicate a desire for promos will default to false for performance purposes. Both methods return the information necessary to complete a reservation/create a new rental using the MakeReservation method.
Choosing an Account
For a brand new tenant, call CreateNewAccount. This method will create the account and at least one new contact, one new address and one new phone, which will then be available to accept rentals.
If you wish to add a unit to an existing customer’s account, you will need to use the SearchBy method to retrieve their AccountID and then use the AccountID to add the rental to their account.
Making a Reservation/Creating a New Rental
Once you have either created a new account or located an existing account, you can create a reservation/rental. First some terminology regarding reservations and rentals:
- Quote Only – This is created when a person has indicated interest in renting a unit but does not wish to commit to a reservation or rental. An account is still required. This allows for obtaining all the contact information. A unit is still required so anyone following up on the potential sale is aware of what type of rental the customer is looking for. The unit is NOT put on hold and can be rented at anytime by anyone else.
- Soft Reservation – This does not hold a specific unit, but will hold a unit of this type. The reservation will exist until its expiration date or until the reservation is cancelled. If there is only one unit left, it will not show as available to rent due to the soft reservation.
- Hard Reservation – This method holds a specific unit for a site specified length of time. Generally there is also a reservation deposit amount paid, although it is not required. If there is a deposit required, the payment process described below MUST be completed before the reservation process is considered complete. If it is not the rental will be cancelled during our nightly processing.
- Rental – To heck with reservations, the customer has a moving van parked out front. The move in is NOT done, however, until the payment process below has been completed.
MakeReservation does all of the above including upgrading from one status to another. MakeReservation will always return a QuoteID. If a reservation or rental is created there will also be a RentalID returned.
Making a Payment
So you’ve created the account and we’ve made our unit selection now we have to pay for the thing. Making a payment is a three step process.
Step One – GetAssessments – This method retrieves a list of line items to be paid. Regardless if this is a new or existing rental and whether or not you already know the total due this method MUST be called. Assessments may or may not be in existence for the rental. By calling this method it will create any assessments the organization or site requires. Failing to call this process means you may not have the correct total due and will cause errors in payment.
The method will return a list of line items that are due for the requested time-frame. If the tenant has any cash credit/escrow that can be used for payment, they will also be listed here. Note: Cash credit/escrow is not automatically deducted from the total due.
Step Two – GetTotalDue – This step can be skipped if the items in GetAssessments are looped through and totaled. There are some rules to keep in mind for this option. Extended is the total due not including taxes for the assessment, a fulfilled amount indicates some payment has been made on the assessment and that will not be deducted from extended, finally any tax amount must be added in. If a cash credit/escrow is present the extended amount indicates the available balance that can be used toward payment.
Step Three – MakePayment – And you thought we’d never get here. MakePayment accepts the above data, some total data and three payment types. One or any combination of payment types is allowed (i.e., customer wishes to pay half cash, half on a card, or possibly split the payment between two cards, etc.).
But, wait?! They have a promotion for the first month free and GetTotalDue says $0 is due. I don’t have to make a payment…. Yes, you do!!! Any new rental is not moved in until a payment is made. This will push the paid thru date forward and move the tenant in. If no payment is made, even if it’s a $0 cash payment, the rental will be ended as an abandoned rental during nightly processing. They will have to be moved in again, possibly missing out on a day of rent.
The MakePayment method will return a transaction ID if successful. The CashCreditApplied field has been deprecated.
SWS VoidRetailAssessments Method
Allows you to void an assessment for a retail item. A void can only be completed on the same day the item was assessed and prior to nightly processing.
Parameters
| Name | DataType | Is Required |
|---|---|---|
| AssessID | Long | Required |
| Description | The assessment’s ID number. This can be retrieved using the GetAssessments method. | |
| SiteID | Long | Required |
| Description | The site’s ID number. This can be found using the GetSiteList method. | |
Returned Parameters
| Name | DataType |
|---|---|
| AssessID | Long |
| Description | The assessment ID number of the item that was voided. |
| ErrorMessage | Boolean |
| Description | A message with details about why the void failed. |
| Success | Boolean |
| Description | Indicates if the retail item was voided successfully (“True”) or not (“False”). |
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 VoidRetailAssessment request object and a VoidRetailAssessment response object. We can define and create those like this:
// Create a request and response objects
SWS.WSSoapClient service = new SWS.WSSoapClient();
SWS.VoidRetailAssessment_Request request = new SWS.VoidRetailAssessment_Request();
SWS.VoidRetailAssessment_Response response;
Here’s my sample code of the Request object.
// VoidRetailAssessments Request
request.SiteID = 123546;
request.AssessIDs = new long[] { 123456 };
Finally we can call the method and pass across the login object and the request object to void our retail assessment. 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.VoidRetailAssessments(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.
SWS ReturnRetailItems Method
Processes returns for retail items based on the site rules. If the credit card option is chosen but fails to process through the card processor, a check will be mailed to the contact instead based on refund approval rules.
Parameters
| Name | DataType | Is Required |
|---|---|---|
| contactInfo:AccountID | Long | Optional |
| Description | The account’s ID number. | |
| contactInfo:Address1 | String | Optional* |
| Description | The first line of the address where the refund check will be sent or the address on the credit card where the funds will be returned. *This is required if using CHECK or CREDIT_CARD refund types. |
|
| contactInfo:Address2 | String | Optional |
| Description | The second line of the address where the refund check will be sent or the address on the credit card where the funds will be returned. | |
| contactInfo:City | String | Optional* |
| Description | The city of the address where the refund check will be sent or the address on the credit card where the funds will be returned. *This is required if using CHECK or CREDIT_CARD refund types. |
|
| contactInfo:ContactName | String | Required |
| Description | The name to whom the check should be made out or the name on the credit card where the funds are being returned. | |
| contactInfo:Country | String | Optional |
| Description | The country of the address where the refund check will be sent or the address on the credit card where the funds will be returned. | |
| contactInfo:PostalCode | String | Optional* |
| Description | The postal/ZIP code of the address where the refund check will be sent or the address on the credit card where the funds will be returned. *This is required if using CHECK or CREDIT_CARD refund types. |
|
| contactInfo:State | String | Optional* |
| Description | The state/province of the address where the refund check will be sent or the address on the credit card where the funds will be returned. *This is required if using CHECK or CREDIT_CARD refund types. |
|
| OrgID | Long | Required |
| Description | The organization’s ID number. | |
| ReturnRetailData | ReturnRetailItem | Required |
| Description | The object containing the details about the retail item/s being returned. Create a collection for each RetailObjectID being returned. | |
| RefundType | RefundTypes | Required |
| Description | The refund type for reimbursing the customer. Available values (Note: The site’s rules determine how a refund will be issued and not all values will be available for all refunds.):
|
|
| RentalID | Long | Optional |
| Description | The rental item’s ID number. Depending on your xml parser, you may have to pass in a ‘0’ to avoid getting an error. | |
| SiteID | Long | Required |
| Description | The site’s ID number. This can be found using the GetSiteList method. | |
| TransactionID | Long | Optional |
| Description | The original transaction’s ID number. Transaction IDs are system generated for each payment transaction that occurs in the system. If there is no transaction ID the transaction failed. The transaction ID is returned when any MakePayment method is used. | |
Returned Parameters
| Name | DataType |
|---|---|
| TotalRefundAmount | Decimal |
| Description | The refund amount. This is automatically calculated by the Store application, based on the Refund rules for the site. |
| RefundMessage | String |
| Description | The message associated with the success or failure of processing the refund. This will provide additional information if needed. |
| NewReturnTransactionID | Long |
| Description | The transaction’s ID number. Transaction IDs are system generated for each payment transaction that occurs in the system. A blank 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 ReturnRetailItems request object and a ReturnRetailItems response object. As part of the ReturnRetailItems request object we also need ContactInfo object and an array of ReturnRetailItem objects. We can define and create those like this:
// Create a request and response objects
SWS.WSSoapClient service = new SWS.WSSoapClient();
SWS.ReturnRetailItems_Request request = new SWS.ReturnRetailItems_Request();
SWS.ReturnRetailItems_Response response;
SWS.ContactInfo contactInfo = new SWS.ContactInfo ();
SWS.ReturnRetailItem returnItem = new SWS.ReturnRetailItem();
Here’s my sample code of the Request object.
// Requests
contactInfo.AccountID = 123456;
contactInfo.ContactName = "John Doe";
contactInfo.Address1 = "123 Main St";
contactInfo.City = "My Town";
contactInfo.State = "CA";
contactInfo.PostalCode = "12345";
returnItem.RetailObjectID = 123456;
returnItem.Quantity = 1;
returnItem.ReturnReason = SWS.RetailReturnReasons.DEFECTIVE_VENDOR_RETURN;
request.OrgID = 123456;
request.SiteID = 123456;
request.TransactionID = 123456;
request.RefundType = SWS.RefundTypes.CREDIT_CARD;
request.ContactData = contactInfo;
request.ReturnRetailData = new SWS.ReturnRetailItem[] { returnItem };
Finally we can call the method and pass across the login object and the request object to return our retail items. 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.ReturnRetailItems(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.
Yardi Store Developer eXchange 