Version 2.0.2
Last Updated: 9/9/2020
Last Updated: 9/9/2020
Overview
The SecurePay 2 Payment API is a web service that allows merchants to securely interface with SecurePay to process transactions. The web service is an extension of the SecurePay gateway product offering and allows merchants who already have websites or applications to easily integrate with the SecurePay gateway to accept credit card payment. The API can be used in most programming languages that support web services.
This API document provides the necessary information to transmit payment processing information to SecurePay’s gateway servers directly from a web server or other application connected to the internet using the standard SOAP web service protocol.
API
If you plan to utilize the SecurePay API the minimum requirements have to be met and are as follows listed below. These requirements have to be met if these requirements are not been met than you will not be able to use the SecurePay API as an integration method for your integration needs.
- Active SecurePay account.
- SecurePay Merchant ID.
- Website or Integration method must use HTTPS
Supported Web Service Protocols
- SOAP – Simple Object Access Protocol. Common, platform independent communication protocol.
Service URLs
- Development – https://apidev.securepay.net
- Production – https://api.securepay.net
Service API Functions
Below are the supported service API function(s).
- ProcessTransaction – is used to process a card transaction.
Service Request Object
| Property | Required | Type | Description |
|---|---|---|---|
| MerchantID | Yes | long | A unique merchant identifier assigned to the Merchant by SecurePay. |
| TransactionKey | Yes | string | A passcode to add an additional layer of protection to your online transactions. This prevents anyone from creating an interface to your merchant account without your authorization. This feature can be modified in the Merchant Portal under the SecureGuard link on the navigation menu. |
| CreateToken | No | boolean | Allows the card number to be converted into an encrypted token which allows you to process the card holder’s transaction without the card number being required. |
| TransactionType | Yes | Alphanumeric | Allows the card number to be converted into an encrypted token which allows you to process the card holder’s transaction without the card number being required. SALE – Indicates a charge to be placed against a credit card account. CREDIT – Indicates a refund or “credit” to be placed against a credit card account. PREAUTH– Indicates a pre-authorization on a Credit Card. This is a temporary hold on an Amount submitted by the Merchant. This is not a qualified transaction and if not closed with a FORCE transaction it will release the hold after 5-7 days depending on the card issuer. This can have a negative impact on the funds availability of the card holder and should be used appropriately. FORCE – Indicates a closure of a previously PREAUTH (pre-authorized) transaction. VOID – Indicates a reversal of a transaction conducted on the same business day. |
| Amount | Yes | decimal | The amount of the transaction. Needs to be decimal format to 2 decimal places, ranging from 0.01 to 1000000.00. |
| CardNumber | Yes | string | The account number of the credit card. The type of card that is acceptable depends what is setup for the SecurePay account profile. SecurePay accepts Visa, MasterCard, Discover, and American Express cards to be processed through our gateway. This parameter is also used to process Tokens and Swipe Track Data. No spaces, dashes or other special characters. |
| IsSwipe | Yes | boolean | Indicator for a swipe transaction. |
| ExpirationDate | Yes* | string i.e. 0118 |
The expiration date of the credit card. No spaces, dashes or other special characters. Not required for swipe transactions. |
| CVV2 | Yes* | string | The 3 or 4 digit security code that is issued on the credit card. Not required for swipe transactions. |
| OriginalTransactionID | No | long | The transaction ID issued upon completion of processing a transaction. This is used to issue Voids on transactions to remove authorization but must be completed before transaction has been settled to a batch. |
| ApprovalCode | No | string | The response code issued from a transaction. This code indicates that the Transaction is approved and the Card may be honored. The code can also be used to issue Credits on transactions that have been settled to a batch. |
| TestRequest | No | boolean | Identifies a transaction as a test request, for integration purposes. |
| CardName | Yes* | string | The name issued on the credit card. Not required for swipe transactions. |
| Street | Yes* | string | The billing street address associated with the credit card. Not required for swipe transactions. |
| City | Yes* | string | The billing city associated with the credit card. Not required for swipe transactions. |
| State | Yes* | string i.e. NY, GA |
The billing state associated with the credit card. Not required for swipe transactions. |
| Zip | Yes | string i.e. 30022 |
The billing zip code associated with the credit card. |
| Country | Yes* | string i.e. US |
The billing country associated with the credit card. Not required for swipe transactions. |
| Phone | No | string i.e. 800-123-4567 |
The contact number for the credit card holder. |
| No | string | The email address for the credit card holder. | |
| CustomField1 | No | string | Ties to Custom Field #1 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…).This can be configured in the Merchant Portal under the Account Information link. |
| CustomField2 | No | string | Ties to Custom Field #2 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…). This can be configured in the Merchant Portal under the Account Information link. |
| CustomField3 | No | string | Ties to Custom Field #3 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…). This can be configured in the Merchant Portal under the Account Information link. |
| MerchantReceipt | No | boolean | Indicates whether an email receipt will be sent to the merchant. |
| CardHolderReceipt | No | boolean | Indicates whether an email receipt will be sent to the card holder. |
| IsRecurring | No | boolean | Indicates whether to add the card information as a recurring billing account. |
| RecurringAmount | No* | decimal | The amount that will be charged on a recurring basis. Needs to be decimal format to 2 decimal places. This field is required if IsRecurring = 1. |
| RecurringStartDate | No* | date i.e. 10/15/2014 |
The date to start the recurring billing cycle. This field is required if IsRecurring = 1. |
| RecurringEndDate | No* | date | The date to end recurring billing. This field is required if IsRecurring = 1. |
| RecurringFrequency | No* | string | The frequency that the recurring billing will occur. This field is required if is Recurring = 1. Weekly – reprocess the transaction weekly. Monthly – reprocess the transaction once, monthly. Bimonthly – reprocess the transaction every two weeks. Quarterly – reprocess the transaction once a quarter (every 3 months). Annually – reprocess the transaction once a year. Biannually – reprocess the transaction twice a year. |
| IsAchTransaction | Yes | boolean | Indicator for a ACH transaction |
| AccountNumber | string | Customer Bank Account Number for ACH | |
| RoutingNumber | string | Customer Routing Number for ACH | |
| AccountType | string | Customer Account Type, Personal, Business | |
| BankAccountType | string | Customer Account Type, Saving, Checking | |
| NameOnAccount | string | Customer name on the Bank Account |
Service Request example:
- REST
- SOAP
- JSON
- XML
- Request URL: {service-url}/TransactionService.svc/Json/ProcessTransaction
- Request Data:
{
"TestRequest": "true",
"MerchantID": "<merchant-id>",
"CardNumber": "4012888818888",
"ExpirationDate": "1220",
"CardName": "Test",
"Street": "950 North Point Pwk",
"City": "Alpharetta",
"State": "GA",
"Zip": "30022",
"Country": "US",
"Email": "jmartin@olb.com",
"Phone": "6782938675",
"CVV2": "999",
"CardType": "Visa",
"TransactionType": "sale",
"Amount": "4.97",
"TransactionKey": "<transaction-key>"
}
- Request URL: {service-url}/TransactionService.svc/Xml/ProcessTransaction
- Request Data:
<Request xmlns="http://schemas.datacontract.org/2004/07/SecurePayTransactionService">
<Amount>3.15</Amount>
<CVV2>999</CVV2>
<CardName>TEST</CardName>
<CardNumber>4111111111111111</CardNumber>
<City>Alpharetta</City>
<Country>United States</Country>
<Email>hpanchal@olb.com</Email>
<ExpirationDate>1220</ExpirationDate>
<MerchantID>100031</MerchantID>
<Phone>6782938675</Phone>
<State>GA</State>
<Street>950 North Point Pwk</Street>
<TestRequest>true</TestRequest>
<TransactionKey>zQsJskk2iFcv6jHq</TransactionKey>
<TransactionType>sale</TransactionType>
<Zip>30022</Zip>
</Request>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ProcessTransaction xmlns="http://www.securepay.net/">
<request>
<TestRequest>true</TestRequest>
<MerchantID>100031</MerchantID>
<IsSwipe>False</IsSwipe>
<TransactionType>Sale</TransactionType>
<TransactionKey>XXXXXXXXXXXXXX</TransactionKey>
<CardNumber>4111111111111111</CardNumber>
<ExpirationDate>1225</ExpirationDate>
<CreateToken>False</CreateToken>
<CardName>test Test</CardName>
<Street>1 test Ave</Street>
<City>Testing</City>
<State>GA</State>
<Zip>99501</Zip>
<Country>USA</Country>
<email>test@test.com</Email>
<Phone>1234567890</Phone>
<CVV2>111</CVV2>
<TransactionType>Sale</TransactionType>
<Amount>0.01</Amount>
<OriginalTransactionID></OriginalTransactionID>
<IsRecurring>false</IsRecurring>
<RecurringAmount></RecurringAmount>
<RecurringStartDate></RecurringStartDate>
<RecurringFrequency></RecurringFrequency>
<RecurringEndDate></RecurringEndDate>
<ApprovalCode></ApprovalCode>
<CustomValue1>test Value</CustomValue1>
<CustomValue2></CustomValue2>
<CustomValue3></CustomValue3>
<MerchantReceipt>True</MerchantReceipt>
<CardHolderReceipt>True</CardHolderReceipt>
<IsAchTransaction>False</IsAchTransaction>
<AccountNumber></AccountNumber>
<RoutingNumber></RoutingNumber>
<AccountType></AccountType>
<BankAccountType></BankAccountType>
<NameOnAccount></NameOnAccount>
</request>
</ProcessTransaction>
</soap:Body>
</soap:Envelope>
Service Response Values
| Property | Type | Description |
|---|---|---|
| TransactionID | long | A unique identifier assigned to the transaction by SecurePay. This is used to issue Voids on transactions to remove authorization but must be completed before transaction has been settled to a batch. |
| ResponseCode | string | A response code for the transaction response from the authorization platform. 00 = Approved Transaction 05 = Decline Transaction SG99 = Reject Transaction due to Secure Guard Settings SP05 = Decline Transaction due to AVS Rejection. |
| ResponseMessage | string | The response message for the transaction from the authorization platform. Approved = Approved Transaction Decline = Decline Transaction SecureGuard setting: = SecureGuard setting that caught transaction. |
| ResponseMessageDetail | string | Further detailed response information for the transaction from the authorization platform. |
| ApprovalCode | string | The approval code issued from a transaction. This code indicates that the Transaction is approved and the Card may be honored. The code can also be used to issue Credits on transactions that have been settled to a batch. |
| Token | string | A randomly generated value that maps back to the sensitive card data stored in SecurePay. The token can be safely stored in your application and used for subsequent transactions. |
| AVSResponseCode | string | The Address Verification System response. See below for detailed responses. |
| RecurringResponse | string | This indicates success in setting up the transaction as a recurring transaction. Success = Enter into the Recurring databases successful Failed = Not Entered into the Recurring Database Not Requested = Not Requested from the API |
| RecurringAmount | string | The amount that will be charged on a recurring basis. |
| RecurringStartDate | string | The date to start the recurring billing cycle. |
| RecurringEndDate | string | The date to end recurring billing. |
| CustomField1 | string | Custom Field #1 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…). This can be configured in the Merchant Portal under the Account Information link. |
| CustomValue1 | Alphanumeric | Ties to Custom Field #1 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…). This can be configured in the Merchant Portal under the Account Information link |
| CustomField2 | Alphanumeric | Custom Field #2 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…). This can be configured in the Merchant Portal under the Account Information link. |
| CustomValue2 | Alphanumeric | Ties to Custom Field #2 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…). This can be configured in the Merchant Portal under the Account Information link. |
| CustomField3 | Alphanumeric | Custom Field #3 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…). This can be configured in the Merchant Portal under the Account Information link. |
| CustomValue3 | Alphanumeric | Ties to Custom Field #3 for the merchant account. This allows the merchant to tie their data to the transaction (Invoice ID, etc…). This can be configured in the Merchant Portal under the Account Information link. |
Service Response example:
- REST
- SOAP
- JSON
- XML
- Response Data:
{
"ApprovalCode": "TAS352",
"AvsResponseCode": "N",
"CustomField1": "",
"CustomField2": "",
"CustomField3": "",
"CustomValue1": "",
"CustomValue2": "",
"CustomValue3": "",
"RecurringAmount": "",
"RecurringEndDate": "",
"RecurringResponse": "Not Requested",
"RecurringStartDate": "",
"ResponseCode": "00",
"ResponseMessage": "Approved",
"ResponseMessageDetail": "NO MATCH",
"Token": "",
"TransactionID": 86597
}
<Response xmlns="http://schemas.datacontract.org/2004/07/SecurePayTransactionService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <ApprovalCode>TAS864</ApprovalCode> <AvsResponseCode>N</AvsResponseCode> <CustomField1/> <CustomField2/> <CustomField3/> <CustomValue1/> <CustomValue2/> <CustomValue3/> <RecurringAmount/> <RecurringEndDate/> <RecurringResponse>Not Requested</RecurringResponse> <RecurringStartDate/> <ResponseCode>00</ResponseCode> <ResponseMessage>Approved</ResponseMessage> <ResponseMessageDetail>NO MATCH</ResponseMessageDetail> <Token/> <TransactionID>86586</TransactionID> <TransactionID>86586</TransactionID> </Response>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ProcessTransactionResponse xmlns="http://www.securepay.net/"> <ProcessTransactionResult> <TransactionID>11111</TransactionID> <ResponseCode>00</ResponseCode> <ResponseMessage>Approved</ResponseMessage> <ResponseMessageDetail></ResponseMessageDetail> <ApprovalCode>123456</ApprovalCode> <Token></Token> <AvsResponseCode>A</AvsResponseCode> <RecurringResponse></RecurringResponse> <RecurringAmount></RecurringAmount> <RecurringStartDate></RecurringStartDate> <RecurringEndDate></RecurringEndDate> <CustomValue1>Test Value</CustomValue1> <CustomValue2></CustomValue2> <CustomValue3></CustomValue3> <CustomField1></CustomField1> <CustomField2></CustomField2> <CustomField3></CustomField3> </ProcessTransactionResult> </ProcessTransactionResponse> </soap:Body> </soap:Envelope>
AVS Response Code
The AVS Response variable provides a method to develop a business rule set to work in conjunction with the AVSREQ variable to limit merchant liability in credit card acceptance. The AVS system involves presenting 2 pieces of data to the processor as a comparative check against information the processor has on file. The data used in this comparison are the “Billing Street Address” and the “Billing Zip Code” of the credit card holder. Dependent on the success of the comparative match on this information the value of the AVS Response variable will be one of the following:
| AVS Code | AVS Definition |
|---|---|
| A | Address (Street) matches, Zip does not. |
| E | AVS Error |
| G | Issuing bank does not subscribe to the AVS system |
| N | No match on Address or Zip Code. |
| R | Retry, system unavailable or timed out. |
| S | Service not supported by issuer. |
| U | Address information unavailable |
| W | 9 digit Zip matches, Address does not. |
| X | Exact AVS match |
| Y | Address and 5 digit zip code match. |
| Z | 5 digit Zip Code matches, Address does not. |
Note: The AVS system used by SecurePay.Com supports the United States. All AVS requests for Card Accounts issued outside the US may or may not return an AVS match. It is dependent on the card issuing bank and whether that card issuing bank subscribes and participates with the AVS system. AVS requests for cards issued outside the US where the bank does not participate in the AVS process will contain a specific AVS Response of “G”.
ACH Transaction
ACH Transaction Request example:
- REST
- SOAP
- JSON
- XML
- Request URL: {service-url}/TransactionService.svc/Json/ProcessTransaction
- Request Data:
{
"TestRequest": "true",
"MerchantID": "100031",
"Street": "950 North Point Pwk",
"City": "Alpharetta",
"State": "GA",
"Zip": "30022",
"Country": "US",
"Email": "jmartin@olb.com",
"Phone": "6782938675",
"CardType": "Visa",
"TransactionType": "sale",
"Amount": "5.74",
"TransactionKey": "zQsJskk2iFcv6jHq",
"IsAchTransaction": true,
"AccountNumber": "5637492437",
"RoutingNumber": "111000025",
"AccountType": "Checking",
"BankAccountType": "Personal",
"NameOnAccount": "TEST"
}
Request URL: {service-url}/TransactionService.svc/Xml/ProcessTransaction
- Request Data:
<Request xmlns="http://schemas.datacontract.org/2004/07/SecurePayTransactionService">
<AccountNumber>5637492437</AccountNumber>
<AccountType>Checking</AccountType>
<Amount>2.89</Amount>
<BankAccountType>Personal</BankAccountType>
<City>Alpharetta</City>
<Country>United States</Country>
<Email>hpanchal@olb.com</Email>
<IsAchTransaction>true</IsAchTransaction>
<MerchantID>100031</MerchantID>
<NameOnAccount>TEST</NameOnAccount>
<Phone>4803333333</Phone>
<RoutingNumber>111000025</RoutingNumber>
<State>GA</State>
<Street>950 North Point Pwk</Street>
<TestRequest>true</TestRequest>
<TransactionKey>zQsJskk2iFcv6jHq</TransactionKey>
<TransactionType>sale</TransactionType>
<Zip>30022</Zip>
</Request>
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ProcessTransaction xmlns="http://www.securepay.net/"> <request> <TestRequest>true</TestRequest> <MerchantID>100031</MerchantID> <CardNumber>string</CardNumber> <Street>950 North Point Pwk </Street> <City>Alpharetta</City> <State>GA</State> <Zip>30022</Zip> <Country>US</Country> <Phone>4803333333</Phone> <TransactionType>Sale</TransactionType> <Amount>2.30</Amount> <TransactionKey>zQsJskk2iFcv6jHq</TransactionKey> <IsAchTransaction>true</IsAchTransaction> <AccountNumber>5637492437</AccountNumber> <RoutingNumber>111000025</RoutingNumber> <AccountType>Checking</AccountType> <BankAccountType>Personal</BankAccountType> <NameOnAccount>TEST</NameOnAccount> </request> </ProcessTransaction> </soap:Body> </soap:Envelope>
ACH Transaction Response example:
- REST
- SOAP
- JSON
- XML
- Response Data:
{
"ApprovalCode": "T:5QHQ090MLA7",
"AvsResponseCode": null,
"CustomField1": null,
"CustomField2": null,
"CustomField3": null,
"CustomValue1": "",
"CustomValue2": "",
"CustomValue3": "",
"RecurringAmount": null,
"RecurringEndDate": null,
"RecurringResponse": null,
"RecurringStartDate": null,
"ResponseCode": "00",
"ResponseMessage": "Approved",
"ResponseMessageDetail": null,
"Token": null,
"TransactionID": 0
}
- Response Data: <Response xmlns="http://schemas.datacontract.org/2004/07/SecurePayTransactionService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <ApprovalCode>T:JQHQ090MLA7</ApprovalCode> <AvsResponseCode i:nil="true"/> <CustomField1 i:nil="true"/> <CustomField2 i:nil="true"/> <CustomField3 i:nil="true"/> <CustomValue1/> <CustomValue2/> <CustomValue3/> <RecurringAmount i:nil="true"/> <RecurringEndDate i:nil="true"/> <RecurringResponse i:nil="true"/> <RecurringStartDate i:nil="true"/> <ResponseCode>00</ResponseCode> <ResponseMessage>Approved</ResponseMessage> <ResponseMessageDetail i:nil="true"/> <Token i:nil="true"/> <TransactionID>0</TransactionID> </Response>
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <ProcessTransactionResponse xmlns="http://www.securepay.net/"> <ProcessTransactionResult> <TransactionID>0</TransactionID> <ResponseCode>00</ResponseCode> <ResponseMessage>Approved</ResponseMessage> <ApprovalCode>T:43FD78ZLLA3</ApprovalCode> <CustomValue1 /> <CustomValue2 /> <CustomValue3 /> </ProcessTransactionResult> </ProcessTransactionResponse> </soap:Body> </soap:Envelope>
All code is developed by SecurePay.com is protected by Copyright.
Copyright SecurePay.com, Inc., All rights Reserved.
Distribution rights are held by SecurePay.Com. This file is not to be published or distributed without written permission from SecurePay.com
Questions and inquiries should be directed to:
SecurePay Technical Support 855.452.7135 services@securepay.com