Payment
Version: 1.33
Payment is the act of receiving a payment from your customer. The Payment can be applied directly to the Billing Account, to an Invoice, or to an Order in progress.
Used In: Refund, SalesOrder, RenewalOrder, and GLAccountingTransaction.
Commands: ApplyPayment, ApplyRefund, ConfirmOrder, CancelPayment, and ReallocatePayment.
Parameters
| Element Name | Query Key | Element Type | Field Length | Required to Create | Description |
|---|---|---|---|---|---|
|
queryScope |
QueryScope |
- - |
N |
Whether default query results are overridden by QueryScope resulting in SHALLOW or DEEP query results. Refer to QueryScope for details. |
|
|
eid |
Y |
Long |
System Generated |
System Generated |
System generated unique identity number assigned to all entities in Gotransverse. |
|
billingAccount |
BillingAccount |
- - |
Y |
The Billing Account number. Click on the link of BillingAccount formore information. |
|
|
CHOOSE one of the following Payment Methods:
|
|
- - |
Y |
Enter payment information. |
|
|
amount |
Y |
Decimal |
As needed |
Y |
The amount of the Payment. |
|
description |
String |
255 |
N |
Description of the Payment if needed. |
|
|
authorization |
Y |
String |
255 |
N |
An authorization code or number sent from the payment processor. |
|
reference |
Y |
String |
255 |
N |
A reference number sent from the paymentprocessor. |
|
occurredOn |
Y |
DateTime |
Refer to Data Types for dateTime formats. |
N |
Date and time on which the Payment occurred. |
|
useRecurringPayment |
Boolean |
Enter either: "true" (Yes) or "false" (No) |
N |
Use a Recurring Payment? Yes (True), use the payment information on file. No detailed payment information is required. The payment is processed through the credit card being used for auto-payments. No (False), then provide the payment information. |
|
|
status |
Y |
PaymentStatus |
- - |
N |
One of the following statuses:
|
|
unappliedAmount |
Decimal |
As needed |
N |
Any amount mof funds that has not been applied to an invoice. |
|
|
refunds |
Refund |
- - |
N |
List of any refunds. |
| Attribute | Required? | Datatype | Description |
|---|---|---|---|
|
receivedAmount |
decimal |
||
|
refundedAmount |
decimal |
||
|
canceledAmount |
decimal |
||
|
receivedCurrency |
CurrencyType |
|
|
|
conversionRate |
decimal |
||
|
effectiveConversionRate |
decimal |
||
|
applyAutomatically |
boolean |
||
|
errorMessage |
string |
Query a Payment
| Query Key | Value | Definition | |||
|---|---|---|---|---|---|
|
eid |
Long |
The eid number of the Payment. |
|||
|
accountNum |
String |
The Account Number of the Billing Account receiving the Payment. |
|||
|
billingAccountEid |
Long |
The eid number of the Billing Account receiving the Payment. |
|||
|
occurredOn |
DateTime |
The dateTime on which the Payment occurred. |
|||
|
reference |
String |
A reference number sent from the payment processor. |
|||
|
status |
The status of the Payment: Draft, Processing, Completed, Void, Processing Error, Merchant Verification, Merchant Verification Failed. |
||||
|
authorization |
String |
An authorization code or number sent from the payment processor. |
|||
|
token |
String |
The token from a tokenized payment method |
|||
Use Payments to retrieve paged results.
| Query to Use | Query for | Parameter Name and Value | Returns | ||
|---|---|---|---|---|---|
|
SimpleDataQuery |
Payment |
<parameter name><parameter value> |
List and information of your Payments for that parameter name and value. |
||
|
createPayment |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments |
|
getPayments |
GET |
https://my.tractbilling.com/t/s/r/1.33/payments |
|
rejectPayment |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+}/reject |
|
voidPayment |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+}/void |
|
processingPayment |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+}/processing |
|
generatePaymentCollectionReferrerToken |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/referrerToken |
|
applyRefund |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+}/applyRefund |
|
reversePayment |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+}/reverse |
|
approvePayment |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+}/approve |
|
cancelPayment |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+}/cancel |
|
reallocatePayment |
POST |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+}/reallocate |
|
getPayment |
GET |
https://my.tractbilling.com/t/s/r/1.33/payments/{eid: \d+} |
Sample Requests and Responses
SOAP
In the following example SOAP query, the parameter of billingAccountEid was used. The Billing Account's EID value (in this example "195"), was learned through a previous query on BillingAccount.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:query xmlns="http://www.tractbilling.com/billing/1_31/domain" xmlns:ns2="http://www.tractbilling.com/billing/1_31/service">
<ns2:queryRequest>
<simpleDataQuery startIndex="0" size="50">
<type>Payment</type>
<parameter parameter="billingAccountEid" parameterValue="195"/>
</simpleDataQuery>
</ns2:queryRequest>
</ns2:query>
</soap:Body>
</soap:Envelope>
This was the response:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:queryResponse xmlns="http://www.tractbilling.com/billing/1_31/domain" xmlns:ns2="http://www.tractbilling.com/billing/1_31/service">
<ns2:return successful="true">
<payments pageNumber="1" pageSize="50" totalElements="1" elementCount="1" totalPages="1">
<payment amount="100.00" occurredOn="2012-11-27T10:47:43-06:00" useRecurringPayment="false" status="COMPLETED" eid="274732">
<billingAccount accountNum="100008762" billType="EMAIL" automaticRecurringPayment="false" status="ACTIVE" pendingChargesTotal="0.00" balance="-8.83" eid="195">
<monthlyBillCycle dayOfMonth="2" name="Cycle 1"
startDate="2012-11-02T00:00:00-05:00" endDate="2012-12-02T00:00:00-06:00"
billCycleType="Monthly" autoBill="false" eid="1527"/>
<person firstName="FAWNIE" lastName="SMITH" dob="1956-06-06" taxIdNumber="***-**-0000" eid="185">
<addresses>
<emailAddress purpose="PRIMARY" email="fsmith@gotransverse.com" eid="574"/>
<postalAddress purpose="SERVICE" country="USA" city="BOISE"
regionOrState="ID" postalCode="66666" line1="555 HAYES DRIVE" eid="575"/>
<postalAddress purpose="BILLING" country="USA" city="DEL MONTE"
regionOrState="ID" postalCode="66677" line1="111 FALLON AVENUE" eid="576"/>
<postalAddress purpose="SHIPPING" country="USA" city="HAPPY CITY"
regionOrState="AL" postalCode="22222" line1="123 HELLO STREET" eid="578"/>
</addresses>
</person>
<billingAccountCategory type="Consumer" description="Private Consumer"
status="BA_CATEGORY_ACTIVE" eid="29"/>
<services pageNumber="1" pageSize="50" totalElements="3"
elementCount="0" totalPages="1"/>
</billingAccount>
<cashPayment eid="39434"/>
<refunds pageNumber="1" pageSize="0" totalElements="0" elementCount="0"
totalPages="1"/>
</payment>
</payments>
</ns2:return>
</ns2:queryResponse>
</soap:Body>
</soap:Envelope>
REST
REST Example Query and Response
In the following example REST query, the parameter of billingAccountEid was used. The Billing Account's EID value (in this example "195"), was learned through a previous query on BillingAccount.
-
GET https://my.tractbilling.com/t/s/r/1.33/payments?billingAccountEid=195
This was the response (line breaks and formatting added for ease of reading):
<?xml version="1.0" encoding="UTF-8"?>
<payments elementCount="1" pageNumber="1" pageSize="50" totalElements="1" totalPages="1">
<ns2:payment xmlns:ns2="http://www.tractbilling.com/billing/1_31/domain" amount="100.00" eid="274732" occurredOn="2012-11-27T10:47:43-06:00" status="COMPLETED"useRecurringPayment="false">
<ns2:billingAccount accountNum="100008762" automaticRecurringPayment="false" balance="-8.83" billType="EMAIL" eid="195" pendingChargesTotal="0.00" status="ACTIVE">
<ns2:monthlyBillCycle autoBill="false" billCycleType="Monthly" dayOfMonth="2" eid="1527"
endDate="2013-02-02T00:00:00-06:00" name="Cycle 1" startDate="2013-01-02T00:00:00-06:00"/>
<ns2:person dob="1956-06-06" eid="185" firstName="FAWNIE" lastName="SMITH" taxIdNumber="***-**-0000">
<ns2:addresses>
<ns2:postalAddress city="DEL MONTE" country="USA" eid="576" line1="111 FALLON AVENUE"
postalCode="66677" purpose="BILLING" regionOrState="ID"/>
<ns2:postalAddress city="HAPPY CITY" country="USA" eid="578" line1="123 HELLO STREET"
postalCode="22222" purpose="SHIPPING" regionOrState="AL"/>
<ns2:postalAddress city="BOISE" country="USA" eid="575" line1="555 HAYES DRIVE"
postalCode="66666" purpose="SERVICE" regionOrState="ID"/>
<ns2:emailAddress eid="574" email="qa_test@gotransverse.com" purpose="PRIMARY"/>
</ns2:addresses>
</ns2:person>
<ns2:billingAccountCategory description="Private Consumer" eid="29" status="BA_CATEGORY_ACTIVE" type="Consumer"/>
<ns2:services elementCount="0" pageNumber="1" pageSize="50" totalElements="3" totalPages="1"/>
</ns2:billingAccount>
<ns2:cashPayment eid="39434"/>
<ns2:refunds elementCount="0" pageNumber="1" pageSize="0" totalElements="0" totalPages="1"/>
</ns2:payment>
</payments>
REST Example Create a Payment
The following REST example creation of a payment shows a payment of $20.00 being created for (but not applied to) a Billing Account with an EID of "2202236." The Billing Account's EID value was learned through a previous query on BillingAccount. After you create the payment, to apply the payment, Refer to ApplyPayment.
-
POST https://my.tractbilling.com/t/s/r/1.33/payments
<payment amount="20.00" description="Credit Card Payment" xmlns="http://www.tractbilling.com/billing/1_33/domain"> <billingAccount eid="2202236"/> <creditCardPayment cardType="MASTERCARD" cardHolderFirstName="Jane" cardHolderLastName="Smith" cardIdentifierNumber="5500000000000004" cardExpiration="01/2020"> <postalAddress purpose="PAYMENT" country="USA" city="Austin" line1="600 Congress Ave" regionOrState="TX" postalCode= "78701"/> <emailAddress email="janesmith@iliveinaninterestingcity.com" purpose="PAYMENT"/> </creditCardPayment> </payment>
REST Example Command Apply a Refund
Refer to Refund to create the Refund, then use applyRefund to apply the refund through the Gotransverse API back to the payment method, such as a credit card.
In the following REST example command to apply a Refund, a refund of $10.00 is going back to the payment method. The original Payment EID of "444577" and the RefundReason of "97" were learned through separate queries.
POST https://my.tractbilling.com/t/s/r/1.33/payments/<eid>/applyRefund
<applyRefund xmlns="http://www.tractbilling.com/billing/1_31/domain">
<payment eid="666322"/>
<refund amount="10.00" description="Refunding">
<originalPayment eid="444577" />
<refundReason eid="97" />
</refund>
</applyRefund>
REST Example Command Generate Collection Referrer Token
The following REST example shows Generating a Collection Referrer Token. Refer to GenerateCollectionReferrerToken for more details.
-
POST https://my.tractbilling.com/t/s/r/1.33/payments/referrerToken
<generatePaymentCollectionReferrerToken xmlns="http://www.tractbilling.com/billing/1_31/domain">
<errorUrl>http://yourcompanyspageforerror.com/</errorUrl>
<completeUrl>http://yourcompanyspageforcomplete.com/</completeUrl>
<cancelUrl>http://yourcompanyspageforcancel.com</cancelUrl>
</generatePaymentCollectionReferrerToken>
Refer to the following topics for more information: