The CreditCardVault AppFx Web Service endpoint accepts credit card information, wraps it up in a call to the Blackbaud Payment Service, and then returns tokens in place of sensitive credit card information. You provide credit card information to the endpoint in a CreditCardVaultRequest object, and the endpoint returns tokens in a CreditCardVaultReply object.
Credit card tokens are necessary because Blackbaud CRM does not store credit card numbers in order to comply with Payment Card Industry and Payment Application Data Security Standards. The application stores reference tokens in place of credit card numbers and then uses those tokens to charge credit cards in transactions.
Warning: Your organization is responsible for the security and encryption of cardholder data before credit card tokens are entered into Blackbaud CRM. For information about PCI compliance, see the PADSS Implementation Guide at Blackbaud CRM 4.0 How-to Documentation.
The CreditCardVault endpoint is primarily used for two key scenarios:
When Blackbaud CRM customers use third-party vendors to acquire donors and collect credit card information, they can provide vendors with access to the AppFx Web Service API. After vendors safely and securely collect credit card information, they can call the CreditCardVault endpoint to generate tokens for credit cards. When the endpoint returns the tokens, the vendors can save them with other donor information to pass along to the Blackbaud CRM customer.
Similarly, when Blackbaud CRM customers convert credit card information from legacy systems, they can provide third-party processors with access to call the CreditCardVault endpoint to generate tokens for credit cards. Processors can then provide tokens along with the corresponding gift and donor information to convert into Blackbaud CRM.
This tutorial that follows describes the workflow for the scenario where a third-party vendor or conversion processor tokenizes credit card information. A complete code sample is also available to demonstrate how to call the endpoint, and a technical reference provides descriptions of the endpoint's properties.
Step 1 - The Blackbaud CRM customer creates an application user for the third-party vendor and assigns rights to use the CreditCardVault endpoint.
To enable third-party vendors to use the AppFx Web Service API to tokenize credit card information, Blackbaud CRM customers must first provide access to Blackbaud CRM and the rights to use the CreditCardVault endpoint. Vendors do not require rights to any other features to tokenize credit card information.
Create an application user for the vendor in Blackbaud CRM.
From Administration, Security, Application Users, click Add, then specify a domain and user name for the application user and click Save.
For more information about application users, see the Security Guide at Blackbaud CRM User Guides.
Create or import a system role with rights to vault credit card numbers into the Blackbaud Payment Service.
To configure the system role manually, go to Administration, Security, System Roles and click Add.
Specify a name and description for the system role, and click Save.
On the system role page, select the Features tab and click Assign feature permissions.
Under Features on the Assign feature permissions screen, select Revenue, Business Process, Credit Card Processing.
Under Permissions, select Credit Card Vault System Privilege and then click Grant.
Click Save. On the system role page, the Features tab displays the feature permission.
Alternatively, to import the system role, create a file with the following XML:
<SystemRole>
<RecordInformation>
<ID>DBA606CF-5C4F-40CE-A265-E4736C15D4DF</ID>
<Name>Credit Card Vault</Name>
<Description>Grants rights to use the credit card vault endpoint for tokenizing credit cards.</Description>
</RecordInformation>
<FeaturePerms>
<SysPrivs>
<SysPriv>
<FeatureID>98A058BD-E9CA-4E9D-A140-A61D225A1B1C</FeatureID>
<GrantState>Grant</GrantState>
</SysPriv>
</SysPrivs>
</FeaturePerms>
</SystemRole>
In Blackbaud CRM, go to Administration, Security, System Roles and click Import role definition.
Click Choose file and browse to your file.
Click Save. The System Roles page displays a Credit Card Vault role.
For more information about system roles, see the Security Guide at Blackbaud CRM User Guides.
Assign the application user to the security role.
On the system role page, select the Users tab and click Add.
On the Add system role user screen, select the vendor's application user in the Application user field.
Click Save. On the system role page, the Users tab displays the application user.
Step 2 - The Blackbaud CRM customer provides the vendor with access to Blackbaud CRM and the CreditCardVault endpoint.
After the application user for the vendor is in place, the Blackbaud CRM customer must provide the vendor with credentials for the application user. Keep in mind that you should password-protect the credential and provide them in a secure method.
In addition, the vendor needs the name of the Blackbaud CRM database to include in the connection string. This is the display value that appears in the application URL after "databasename=" and that you can set in the web.config file.
You may also want to provide the vendor with the URL for the CreditCardVault endpoint.
Step 3 - The vendor writes code to call the endpoint and then sends credit card information to the endpoint as necessary.
After the Blackbaud CRM customer provides access to Blackbaud CRM and the AppFx Web Service API, the vendor can write code to call the CreditCardVault endpoint. Then after the vendor collects credit card information, it can use the code to call the endpoint and exchange credit card numbers for tokens.
Tip: You can include multiple credit cards in a call to the endpoint, and we recommend that you handle CreditCardVault calls in bulk rather than making one-off calls for each credit card.
The AppFx Web Service is accessible through industry standard web protocols, so you can consume it with any programming language (Java, PHP, .NET, etc.). For the code sample in this tutorial, we use C#.
First, create a CreditCardInfo object for the credit card. Within this object, you provide several properties for the credit card:
The CardHolder property specifies the name of card holder.
The CardNumber property specifies the credit card number.
The ExpirationDate property specifies the date when the credit card expires. Within it, you can include the Year, Month, and Day properties.
The optional ValidFrom property specifies the date when the credit card was issued. This is for UK credit cards only.
The optional IssueNumber property specifies the issue number of the card. This is for UK credit cards only.
// Build credit card info
CreditCardInfo ccInfo = new CreditCardInfo();
ccInfo.CardHolder = "John Doe";
ccInfo.CardNumber = "4111111111111111";
ccInfo.ExpirationDate = new CreditCardFuzzyDate() { Year = 2020, Month = 6 };
//ValidFrom and IssueNumber are only required for UK credit cards
ccInfo.ValidFrom = new CreditCardFuzzyDate() { Year = 2012, Month = 12 };
ccInfo.IssueNumber = "ABC";
Next, you build the request with a CreditCardVaultRequest object. You must provide client application information that describes the database to use and the name of the application. The name of the application can be anything that uniquely describes the client application. The CreditCardVaultRequest object can include multiple CreditCardInfo objects to tokenize multiple credit cards, but this sample only provides one CreditCardInfo object and only returns one token.
Tip: Remember to update the REDatabaseToUse value from "BBInfinity" to the name of your database that you want to use.
// Build request
CreditCardVaultRequest ccReq = new CreditCardVaultRequest();
ccReq.ClientAppInfo = new ClientAppInfoHeader();
ccReq.ClientAppInfo.ClientAppName = "Credit Card Vault Test";
ccReq.ClientAppInfo.REDatabaseToUse = "BBInfinity";
ccReq.CreditCards = new CreditCardInfo[] { ccInfo };
The next step is to send the request to the endpoint. The AppFxWebService is the object provided by the WebAPI dll to handle how to send SOAP requests to the Blackbaud endpoint. You must provide the URL of the AppFxWebService endpoint and your credentials. The credentials must exist for a user in the application database that is provided in ClientAppInfo. For demonstration purposes, the code sample specifies the credentials (user name, password, and domain) for the user running the application directly in the code, but you don't want to hardcode the credentials this way in a production environment .
// Build appfx webservice and send request
using (AppFxWebService svc = new AppFxWebService())
{
svc.Url = "http://localhost/bbappfx.spdev/appfxwebservice.asmx";
svc.Credentials = new System.Net.NetworkCredential("John.Smith", "password", "Blackbaud");
try
{
CreditCardVaultReply ccReply = svc.CreditCardVault(ccReq);
if (ccReply.CreditCardResponses[0].Status == CreditCardVaultStatus.Success)
{
Console.WriteLine("Success - {0}", ccReply.CreditCardResponses[0].Token);
}
else
{
Console.WriteLine("Error - {0}", ccReply.CreditCardResponses[0].ErrorMessage);
}
}
catch (System.Net.WebException ex)
{
Console.WriteLine("Error encountered invoking endpoint - {0}", ex.Message);
}
}
Step 4 - The vendor receives credit card tokens from the endpoint for each credit card.
After you send the request, the endpoint returns a CreditCardVaultReply object that contains a CreditCardResponses property with an array of each CreditCardResponse. Each response can include the following properties:
The Status property indicates whether the request succeeded or failed.
The ErrorMessage property describes the error in the case of a failure.
The Token property provides a token for a credit card that is processed successfully.
The code example in the previous step demonstrates the use of all 3 properties in CreditCardResponse.
After the endpoint returns credit card tokens for each credit card, the vendor stores the tokens in the vendor system along with other donor information.
Step 5 - The vendor sends the tokens to the Blackbaud CRM customer along with other details about donors and gifts, and the Blackbaud CRM customer imports the data.
The vendor creates a file that meets the requirements of the Blackbaud CRM customer and then passes along the donor and gift information, including credit card tokens.
Then the Blackbaud CRM customer imports the data into Blackbaud CRM.
For information about how to import data into Blackbaud CRM, see the Batch and Import Guide at Blackbaud CRM User Guides.