Overview

The OP Payment Web Service is designed to accept the details of a payment transaction and process it in Patriot and through the payment gateway. It accepts the payment information as well as the payment and optional invoice information, processes the request and returns the result.


Behavior

The web service is an ASP.NET web handler that accepts a valid JSON string structured per the details of this documentation and returns a JSON response. Providing the required fields below creates a payment record in Patriot with payment details, processes the payment to the gateway with the information provided in the request and if successful, confirms the payment in Patriot with the transaction details or removes the payment in Patriot. An optional configuration allows the creation of an associated invoice within that the payment applies to.



Current Limitations

The web service cannot:

· process a payment without creating a payment within Patriot.

· create an invoice that has a balance due

· create donations

· update existing payments or invoices

 

Field Name

DataType

Valid Values

Required?

Purpose

IsRecurring

Boolean

True, False

Yes

Indicate if payment is recurring

IsTestMode

Boolean

True, False

Yes

Indicate if payment is being processed in test mode

Amount

Decimal

Decimal value

Yes

Total amount of payment

PayeeType

Char

"P" (Person) or "C" (Chapter)

Yes

Indicate whether it's a Person or Chapter

PaymentMethod

String

"CreditCard" or "ACH"

Yes

Indicate payment method

Amount

Decimal

Decimal value

Yes

Amount to be processed as payment

FirstName

String

Yes

First name of payee

LastName

String

Yes

Last name of payee

Address

String

Yes

Billing address of payee

City

String

Yes

Billing city of payee

State

String

Yes

Billing state of payee

Zip

String

Yes

Billing Zip of payee

Phone

String

Yes

Billing phone number of payee

EmailAddress

String

Yes

Billing email address of payee

Company

String

No (First + Last name will be used)

Billing company of payee

Source

String

Yes

Appears as LastModBy and CreatedBy on Patriot records as a source identifier

Description

String

No

Appears in Note field of Patriot records

SendAcknowledgementEmail

Boolean

True, False

No (default value is False)

If true, will allow the payment gateway to send receipt to customer

MerchantAccountOwner

String

"Fraternity", "Foundation"

Yes

Selects which merchant account to use

AssociatedInvoiceID

Integer

*Return value - Read Only

If transaction succeeds, returns the InvoiceID

NumberOfRecurrences

Integer

> 0

*Yes if IsRecurring = True

RecurrenceFrequency

String

“OneTime”, “Weekly”, “Monthly”, “Quarterly”, “Annually”, “Yearly”

*Yes if IsRecurring = True

Username

String

 

Yes. Must match value in tlkOP_SystemSettings.ProcessPaymentsWebUsername

 

Password

String

Yes. Must match value in tlkOP_SystemSettings.ProcessPaymentsWebPassword

Credit Card Fields

*Required if PaymentMethod = "CreditCard"

CardType

String

“Visa”, “Mastercard”, “American Express”, “Discover”

Yes

NameOnCreditCard

String

Yes

CreditCardNumber

String

Yes

CCVerification

String

3-4 digit number

Yes

CCExpMonth

Integer

2 digit month

Yes

Format: MM

CCExpYear

Integer

4 digit year

Yes

Format: YYYY

 Company

String

 

No

If CC is a business card, the Company will be used if provided. If not provided, the NameOnCreditCard will be used.

ACH Fields

*Required if PaymentMethod = "ACH"

BankName

String

Yes

BankAccountType

String

“Checking”, “Savings”

Yes

BankAccountOwnerType

String

“Personal”, “Business”

Yes

NameOnBankAccount

String

Yes

Bank account owner’s name

BankAccountNumber

String

Valid bank account number

Yes

RoutingNumber

String

Valid routing number

Yes

CheckNumber

String

Yes (if no valid check number is available, pass in a placeholder value)

Payment/Invoice Fields

CreateAssociatedInvoice

Boolean

True, False

Yes

If true, will create an associated invoice with details and apply the payment to it. Note: the current design always creates a $0-balance due invoice.

PersonID

Integer

> 0, must be valid value in Patriot

Yes if the invoice is created for a Person

ChapterID

Integer

> 0, must be valid value in Patriot

Yes if the invoice is created for a Chapter

RegistrationID

Integer

> 0, must be valid value in Patriot

No. Only for reference for use with a convention registration

PostedStatus

Char

"U" (unposted), "H" (Held)

No. Default value is "U" (unposted)

Note

String

Max 1000 chars

No.

Some of the available characters are in use by the service which appends some transaction data into the notes field.

BatchDate

String

MM/DD/YYYY

Yes if different from Today's date

BatchName

String

Max 100 chars

No. Standard default batch names will be applied

InvoiceDueDate

String

MM/DD/YYYY

No. Today’s date will be used as default

Payment/Invoice Detail Fields

ProductID

Integer

> 0, must be valid value in Patriot

Yes

AssociatedPersonID

Integer

> 0, must be valid value in Patriot

Yes if applied to person

AssociatedChapterID

Integer

> 0, must be valid value in Patriot

Yes if applied to chapter

Quantity

Integer

> 0

Yes

ItemCost

Decimal

>= 0

Yes

ItemPaidAmount

Decimal

>= 0

No. Default will be ItemCost

Allows ability for partial payments to be applied per item

ItemDescription

String

Max 200 chars

No

Description on invoice detail

NextExpectedPaymentDate

String

MM/DD/YYYY

No

DetailDueDate

String

MM/DD/YYYY

No

ItemStatus

Char

Must match a value from tlkInvoiceStatus.InvoiceStatus

No

ProductTemplateID

Integer

> 0, must be valid value in Patriot

No

PaymentID

Integer

*Return value - Read Only

InvoiceDetailID

Integer

*Return value - Read Only

Response

*Return Values Read Only

Success

Boolean

True If payment/payment details successfully created in Patriot and payment is successfully processed through gateway

ErrorMessage

String

Present if errors occur. If payment is successfully processed but errors occur creating invoice/invoice details, a value may be present but the Response.Success field may be True

ResponseDescription

String

Description returned from gateway

TransactionID

String

Payment/Transaction ID returned from gateway

PaymentID

Integer

PaymentID of Payment created in Patriot

InvoiceID

Integer

InvoiceID created in Patriot (if requested)

 

 

Sample JSON Request String:

   

{
 "Success": true,
 "InvoiceID": 657,
 "ErrorMessage": "",
 "ResponseDescription": null,
 "TransactionID": "2584163898",
 "PaymentID": 989
}

   

 

Sample JSON Successful Response String:


  

{
 "Success": true,
 "InvoiceID": 657,
 "ErrorMessage": "",
 "ResponseDescription": null,
 "TransactionID": "2584163898",
 "PaymentID": 989
}

 

Sample JSON Failed Response String:

 

{
 "Success": false,
 "ErrorMessage": "Credit Card Type does not match card number",
 "ResponseDescription": null,
 "TransactionID": 0,
 "PaymentID": 0
}

 

 

Sample JavaScript implementation:

 

 function buildRequest() {
 var request = {
 "EmailAddress": "invalid_7814@patriotsoftware.net",
 "PaymentMethod": "CreditCard",
 "PostedStatus": "U",
 "RegistrationID": 12345,
 "SendAcknowledgmentEmail": true,
 "Amount": 8.99,
                "PersonID": 85001,
 "PayeeType": "P",
 "CreditCardNumber": "4111111111111111",
 "City": "Indianapolis",
 "State": "IN",
                "Username": "v1QAPIxpIhO",
 "NameOnCreditCard": "Patriot Testmember",
 "Source": "OP: ProcessPaymentsWeb",
 "CCExpYear": 2018,
 "CardType": "Visa",
 "MerchantAccountOwner": "Fraternity",
 "IsTestMode": true,
 "Company": "Patriot Software",
 "PaymentDetails": [
 {
 "AssociatedChapterID": 123,
 "AssociatedPersonID": 123,
 "Quantity": 1,
 "ProductID": 1,
 "NextExpectedPaymentDate": "1/1/2014",
 "ItemDescription": "My Item",
 "ProductTemplateID": 12,
 "ItemCost": 1.37,
 "ItemPaidAmount": 22.00,
 "ItemStatus": "D",
 "DetailDueDate": "1/3/2014"
 }
 ],
 "Phone": "(317)-573-7199",
 "FirstName": "Patriot",
 "Zip": "46679",
 "InvoiceDueDate": "2/23/2015",
                "Password": "y0kteTVJx3f",
 "CCExpMonth": 9,
 "Address": "1899 E 96th Street",
 "Description": "This payment was made through the OP in the payment module",
 "Note": "You should see this extra note in the Payment and Invoice Note fields",
 "BatchName": "Online CC Payment Batch",
 "ChapterID": 1203,
 "CreateAssociatedInvoice": true,
 "LastName": "Testmember 13",
 "CCVerification": 790
 }
 return request;
 }
 
 function submitRequest() {
 var request = buildRequest();
 
 var submitUrl = "https://myofficerportal.org/WebServices/ProcessPaymentsWeb.ashx";
 $.ajax({
 type: "POST",
 async: false,
 url: submitUrl,
 cache: false,
 processData: false,
 data: JSON.stringify(request),
 contentType: "application/json; charset=utf-8",
 dataType: "json",
 success: function (result) {
 console.dir(result);
 },
 error: function (xhr, status, error) {
 var err = eval("(" + xhr.responseText + ")");
 if (!suppressErrorMessage) { console.dir(err.Message); }
 }
 });
 }