Paymate Sentinel API - Technical Information
Paymate delivers a set of tools to assist merchants of all sizes with integrating the Paymate API into their website and applications. Please click on one of the links below to find the information you need in order to facilitate this process:
General Information
This document is intended for a technical audience of developers.
Paymate Sentinel API is a specific Paymate service to provide a simple and secure method to process credit card payment through the Internet. By sending HTTPS POST request with minimal transaction information to the Paymate server, a merchant can utilise Paymate's payment processing and fraud prevention service to authorise a credit card payment.
A merchant needs to apply for Paymate Sentinel service and it requires approval and set up by Paymate staff prior to implementation. A merchant is responsible for all development and security required to post the request and handle the response. This includes being PCI compliant and maintaining compliance. Please email This e-mail address is being protected from spambots. You need JavaScript enabled to view it to accept the commercial arrangements BEFORE commencing integration with this Application Programming Interface (API). If you are a developer considering Paymate Sentinel for a client, please have them contact us to agree terms prior to commencing development.
Payment Processing Payment type
Paymate Sentinel service accepts the following payment types:
|
Payment Type |
Description |
Comments |
|
Sale |
If the transaction receives an approval, it will be automatically marked for settlement to the merchant at the same time. |
The credit card associations require that a transaction be identified by the method of acceptance. Paymate will mark all merchants who use Paymate Sentinel service as Non-Card-Present Mail/Telephone Order (MOTO) merchants on our system.
Note: Merchants will need to contact Paymate Client Services to have any refunds processed, either on 1800 240 112 or This e-mail address is being protected from spambots. You need JavaScript enabled to view it .
Sentinel API
Communication Protocol
The Paymate Sentinel API supports HTTP protocol using Secure Socket Layer (HTTPS).A merchant sends a HTTPS POST Request with minimal transaction data to Paymate server. Paymate server will return a HTTPS Response to the merchant.
-
HTTPS POST Request will have name-value pairs in Request Body.
-
HTTPS Responses will have XML document in Response Body.
Processing flow
-
A payment request is sent to Paymate server
-
A successful response is returned within the maximum waiting period (30 seconds default)
-
An error response is returned if there are errors in the request data or there are errors in the Paymate server
-
An error response is returned after the maximum waiting period, indicating a timed-out error.
Notes:
-
A timed-out error response will be returned to the sender after the maximum waiting period (30 seconds currently) due to a payment processing delay. In this case the merchant should contact Paymate Client Services for the transaction status or use the Paymate Transaction Inquiry API to query the payment status by using the seller's order reference before re-sending a payment reques
-
A "connection timed out" may occur at the network level. In this scenario there is NO HTTP Response returned. To cater for "connection timed out" issues, to querythe payment status, the merchant should contact Paymate Client Services or use the Paymate Transaction Inquiry API using seller's order reference before re-sending a payment request.
Request Field Definitions
|
Field Name |
Description |
Required |
Length |
Format |
Comments |
|
mid |
Paymate account ID. |
Yes |
4-50 |
Alpha//Numeric |
|
|
sig |
Paymate Sentinel API access signature. |
Yes |
up to 40 |
Alpha/Numeric |
a signature is provided by Paymate after a merchant is approved to use Sentinel service |
|
ver |
API version |
Yes |
3 |
Numeric and period "." |
Must be '2.0' |
|
payment_type |
Payment Type |
Yes |
4-20 |
Alpha |
Must be (lower case):
|
|
amt |
Transaction amount to be processed |
Yes |
4-8 |
Numeric and period "." |
Example: 10.01 |
|
currency |
Currency |
Yes |
3-4 |
Alpha |
Must be one of the following (upper case): 'AUD', 'NZD', 'GBP', 'USD', 'EUR' |
|
ccnum |
Credit card number without hyphens and spaces |
Yes |
5-22 |
Numeric |
Two digits (01-12). Example: '05' |
|
ccowner |
Name on credit card |
Yes |
2-50 |
Alpha |
Two digits (01-99). Example: '13' |
|
ccmonth |
Credit card expiry month |
Yes |
2 |
Numeric |
|
|
ccyear |
Credit card expiry year |
Yes |
2 |
Numeric |
|
|
cccvv2 |
CVC Security Code |
Yes |
3-4 |
Numeric |
3 digit security code for Visa and MasterCard, 4 digit security code for American Express (note that AMEX is not supported by Paymate currently) |
|
refid |
Merchant's unique order reference ID |
Yes |
2-50 |
Alpha/Numeric |
Only the following characters are accepted: Alpha Numeric SPACE - _ , |
|
client_refid |
Merchant defined reference number that may be used for cross reference and internal tracking |
No |
2-50 |
Alpha/Numeric |
Only the following characters are accepted: Alpha Numeric SPACE - _ , |
|
invoice_number |
merchant defined invoice number |
No |
2-50 |
Alpha/Numeric |
Only the following characters are accepted: Alpha Numeric SPACE - _ , |
|
remote_ip |
The IP address of the buyer's browser. |
Yes |
7-15 |
Numeric and period "." |
Example: "1.1.1.1" |
|
buyer_firstname |
buyer first name |
Yes |
2-50 |
Alpha |
|
|
buyer_lastname |
buyer last name/surname |
Yes |
2-50 |
Alpha |
|
|
buyer_email |
buyer email |
Yes |
2-50 |
Alpha/Numeric |
Example " This e-mail address is being protected from spambots. You need JavaScript enabled to view it " |
|
buyer_phone |
buyer phone |
Yes |
2-50 |
Numeric and "-", "+" only |
Example: "+1-123-456-7890" |
|
buyer_address1 |
buyer address |
Yes |
2-100 |
Alpha/Numeric |
Only the following characters are accepted: Alpha Numeric SPACE - _ , |
|
buyer_address2 |
buyer address |
Yes |
2-100 |
Alpha/Numeric |
Only the following characters are accepted: Alpha Numeric SPACE - _ , |
|
buyer_citysub |
buyer city or suburb |
Yes |
2-50 |
Alpha/Numeric |
Only the following characters are accepted: Alpha Numeric SPACE - _ , |
|
buyer_stateprov |
buyer state or province |
Yes |
2-50 |
Alpha/Numeric |
Only the following characters are accepted: Alpha Numeric SPACE - _ , |
|
buyer_country |
Two letter ISO (International Organization for Standardization) country codes |
Yes |
2 |
Alpha |
Example: "US" or "AU" |
|
buyer_postcode |
buyer post or zip code |
Yes |
2-50 |
Alpha/Numeric |
Only the following characters are accepted: Alpha Numeric SPACE - _ , Example: "K1P 1A4" |
Response XML
After processing the HTTP Request, the Paymate sever will return a HTTP Response with XML document in the response body. There are 2 types of response, Success and Error.
-
A success response is a HTTP Response where XML document in the response body has a value "Success" in the element tag "Ack"
-
An error response is a HTTP Response where XML document in the response body has a value "Error" in the element tag "Ack"
Response XML Schema
The location of the schema definition of the XML responses is:
http://www.paymate.com/schema/sentinel/SentinelResponse.xsd
Response XML SampleThe location of sample response is:
http://www.paymate.com/sentinel/sentinel_api_v2.0_sample_response.doc
Transaction Status Code
It is important to understand the different statuses that a payment may reach. In particular take note Paymate recommends the seller should ship the goods or supply services only once the payment has been marked as APPROVED. The status codes that a payment may be assigned by Paymate are:
-
APPROVED (PA): Denotes that the payment request passed the risk assessment and was processed successfully by the bank. It applies to Payment Type 'sale'.
-
DECLINED (PD): The payment has been declined, either by Paymate after risk assessment or the bank after a request for authorisation. The seller should NOT ship goods or deliver services. We recommend the transaction be cancelled or a different method of payment be requested. Note that Paymate will NOT provide a reason for the decline decision.
Testing
Obtain Sentinel API Signature
Once a merchant is approved to use Sentinel API they (or their web developper) will need to email Paymate Client Services. Paymate will provide a signature/token that is required to make API calls. However, the Sentinel API has to be enabled for you by Client Services before you can make API calls.
Sentinel Server URL
API requests should be directed to:
-
Production environment: https://www.paymate.com/PayMate/sentinel. The seller will need to have a valid Paymate account and be approved and set up for use of the Paymate API for production usage. Payments will be processed and fees applied under our
API Access Credentials
In order to obtain API access you will need to email This e-mail address is being protected from spambots. You need JavaScript enabled to view it . Please specify if you are interested in query only access or Paymate Sentinel (payment and query) access. Paymate will then provide a digital signature that you may use for secure API access.
API flows can be roughly divided into payment and queries. The payment flow may require queries in order to get the final status of the payment or in the event of network problems. However you should be aware that the API has to be enabled by Paymate, for both query only or query and payment.
Certification process for Sentinel API usage
In order to be approved to use Sentinel API you must be certified by Paymate Client Services. Contact This e-mail address is being protected from spambots. You need JavaScript enabled to view it and we will discuss whether the functionality is appropriate to you and whther you meet the certification requirements.
