Saving a Payment Account and Token for Later Use

Sometimes an application external to CostGuard will be the one to interface with a payment gateway and facilitate the entry of payment account information, such as credit card or bank account info. The result of this action would be an account token that can be associated with the payment info.

This article describes the steps needed for that application to save information about the payment account in the CostGuard system, including gateway-specific account token formats, so that it can be used later for either one-time or recurring payments.

Prerequisites

This guide assumes a basic level of familiarity with CostGuard web services and the concepts behind them, i.e. SOAP vs. OData requests, how to create the security token and how to issue requests.

If you would like further background in these areas, please see our Getting Started articles such as CostGuard Web API Overview and Getting Started: Security.

Web Service Documentation

The Customer web service is used to manage customer accounts in CostGuard and will be used in this guide to manage payment accounts. Here are links to both the Web APIs in general and the Customer web service.

Web Services API Documentation

Customer Service API

Managing Customer Accounts

In the CostGuard system, a payment account must be associated with a customer account and payment accounts are managed using the same web service operations that are used to manage customer accounts.

All requests to CostGuard SOAP web services will involve two objects: a Request object and a Req object. The Request object is the one passed into the web service channel request. It in turn will always contain two child objects: a Requestor object that contains authorization and user information and the Req object. The Req object contains the information pertinent to the operation being performed, which for the purposes of this guide would be either CreateCustomerReq or ModifyCustomerReq. The key difference between these two operations is that to modify an existing customer you must identify the account using the CustomerID, which you might obtain from a list of customers such as the CustomerSummary OData.

This example shows the objects in the discussion above being assembled to perform a request to modify an existing customer:

ModifyCustomerReq modifyCustomerReq = new ModifyCustomerReq()
{
    CustomerID = new AuthenticatedID()
    {
        AuthenticatedKey    = customerID.ToString(),
        ID                  = CustomerID
    }
};

ModifyCustomerRequest modifyCustomerRequest = new ModifyCustomerRequest()
{
    Request     = modifyCustomerReq,
    Requestor   = requestor
};

Once fully assembled, the request can then be submitted to the Customer web service channel as follows:

ModifyCustomerResponse modifyCustomerResponse = channel.ModifyCustomer(modifyCustomerRequest);

Like the request objects explained above, all responses from CostGuard SOAP web services will also involve two objects: a Response object and a Result object. The Response object is the one returned from the web service request. It in turn will always contain two child objects: a Messages object that contains any warnings or errors that occurred and the Result object. The Result object contains the information pertinent to the operation being performed, which for this guide will be either CreateCustomerResult or ModifyCustomerResult.

Note: In general for CostGuard SOAP web services, you should always start by looking for any errors in the Messages object and handle those appropriately. If there are no errors, then you can proceed with processing the Result object.

Managing Payment Accounts

Now that you understand the basic mechanism for managing information on customer accounts, we will discuss how payment accounts are managed.

Like other CostGuard SOAP web service objects, the unique identifier PaymentAccountID is required when modifying an existing PaymentAccount object. When no value is specified for PaymentAccountID, a new payment account is created and associated with the customer that was specified in the request. We will add the following code to our earlier code example to create a new PaymentAccountCreditCard with a new contact. An existing contact can also be used. See the Customer web service documentation noted earlier for further contact options.

Note: Both PaymentAccountCreditCard and PaymentAccountBankAccount are sub-types of the PaymentAccount object.

PaymentAccountCreditCard paymentAccountCreditCard = new PaymentAccountCreditCard()
{
	CardNumber = "1201",
	CreditCardType = CreditCardType.Visa,
	ExpirationDate = "2021-09-30T00:00:00.000000",  // Must match the ISO 8601 format
	Contact = new ContactInformationItem()
	{
		FirstName = "John",
		LastName = "Doe"
	}
};
modifyCustomerReq.PaymentAccounts = new PaymentAccounts();
modifyCustomerReq.PaymentAccounts.Add(paymentAccountCreditCard);

Payment Gateway Account Token

To be able to use a payment account for either one-time or recurring transactions in the future, the Token property must be specified on the PaymentAccount object in a format that is specific to the payment gateway. The following Token property documentation is copied from the Customer web service for convenience:

Recurring Payment Accounts

To configure a payment account for automatic recurring payments, a PaymentAccountRecurring object must be added to the payment account as follows:

PaymentAccountRecurring paymentAccountRecurring = new PaymentAccountRecurring()
{
	StartDate = DateTime.Now
};
paymentAccountCreditCard.PaymentAccountRecurring = paymentAccountRecurring;

Summary

Using the above steps, we have created a CostGuard SOAP web service request such that during either creation of a new customer account or modification of an existing customer account, a credit card payment account will also be either created or modified on that customer account, and optionally the payment account will also be configured for automatically recurring payments for that customer.