Paymate Sentinel API - Technical Information
- General information
- Integration through an SDK
- Integration at the network level (HTTPS and XML)
If you wish to understand the business features and benefits of Paymate Sentinel, see: Paymate Sentinel FAQ.
General Information
This document is intended for a technical audience of developers.
Paymate Sentinel is a specific Paymate service that merchants can apply for and requires approval and set up by Paymate staff prior to implementation. 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.
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 queries only or queries and payments.
A 'sandbox' environment is provided for testing.
Payment flow
- Payment request-response.
- A sequence of queries to get the final status of the payment.
Notes:
- A payment may not receive a final Approved or Denied response within the maximum wait period due to traffic congestion or because it had been stopped for manual risk assessment. In that case the implementation should query for the final status of pending transactions on a daily basis.
- To cater for network problems where the payment had already been submitted and the response was not received the implementation should use the seller's order reference to check if the payment had gone through or not. Submitting a payment again without this check may result in a payment being processed twice.
Query flow
API queries can be submitted in one of the following formats:
- Query based on a specific Paymate transaction ID.
- Query based on a specific seller's order reference ID.
- Batch query based on a date range and pagination.
Notes:
- If query is made for a seller's order reference that is not unique the last payment will be returned.
- Batch queries are limited by a page size. The implementation should be designed to query for additional pages as it sees fit.
Understanding the Payment Status Codes
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:
- PROCESSING (PP): Denotes that the payment request was submitted successfully but a final decision on the payment is yet to be made.
- APPROVED (PA): Denotes that the payment passed the risk assessment and received bank authorization. The money has been taken from the buyer but is yet to be passed to the seller. At this phase it is safe for the seller to ship the goods. Note that the status code will still change to PAID (or REFUNDED) at a later stage.
- PAID (PC): An extension to the APPROVED status. It denotes that the funds have been submitted to the bank for settlement to the seller's bank account. The seller should have shipped the goods.
- DECLINED (PD): The payment has been declined, either by Paymate after risk assessment or the bank after a request for authorization. The seller should NOT ship goods or deliver services. We recommend the transaction be canceled or a different method of payment be requested. Note that Paymate will NOT provide a reason for the decline decision.
- REFUNDED (PR): the transaction has been refunded to the buyer. This may be done by Paymate on the basis of a risk assessment decision or on receipt of instructions from the seller.
- STOPPED (PS): the transaction is stopped (may be stopped indefinitely), pending a decision by Paymate. The buyer has not been debited at this stage.
- DELAYED (PL): the payment is pending, subject to a final decision on the payment by Paymate. This may happen for example when the transaction is required to pass further security checks.
Service URLs
API requests should be directed to:
- Sandbox environment: https://sandbox.paymate.com/PayMate/api. You will need to register a Paymate account and process payments for testing purposes. No payments will be processed, but you can use nominated credit card numbers to receive different responses.
- Production environment: https://www.paymate.com/PayMate/api. 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 Terms of Use.
XML Schema Location
The location of the schema definition of the XML responses is:
http://www.paymate.com/schema/api/2.0/service.xsd
Downloads
Integration through an SDK
The general steps for integration through the API are as follows:
- Create a sandbox account and an API signature.
- Download the SDK.
- Ensure that the specific SDK prerequisites are met.
- Compile the SDK and run the samples on the sandbox.
- Incorporate the SDK into your project.
- Implement daily queries to handle delayed payments and network problems.
Java SDK integration
Prerequisites
- Java version 6.0 or later with support of JAXB.
- Apache HTTP client version 3.0 or later.
Structure
The main SDK call classes can be found under the package 'au.com.npaymate.api.client’. These are:
- GetTransactionDetailsCall - implements queries for a single transaction (either by Paymate's transaction ID or by seller order reference).
- GetTransactionsCall - implements the query for multiple transactions based on dates and page ranges.
- MakePaymentCall - implements the payment flow.
SDK classes that are used to wrap the requests and responses can be found under the package: ‘au.com.npaymate.formbean.transfer.api’.
Source code
PHP SDK integration
Prerequisites
- PHP version 5.2 or later.
- cURL either integrated to PHP or with a path on the local machine .
Structure
The SDK objects are divided into calls and types with corresponding folders. The main SDK call class is 'MakePaymentCall'.
Source code
The source code includes the SDK and a reference implementation of a payment module for osCommerce. You may deploy it to an osCommerce shopping cart of version 2.
Integration at the network level (HTTPS and XML)
As an alternative to the use of the SDK you may integrate at the lower, protocol level. Note that this is not recommended and should be considered only by experienced developers and only for programming languages other than Java or PHP.
Request-response protocol format
API requests must be sent as an HTML form format. API responses will be returned in XML format.
Sample request forms
Request parameters
| Parameter ID |
Used in |
Format |
Description |
| mid |
all requests |
text/ascii |
Merchant ID.
|
| ver |
all requests |
text/ascii.
Must be '2.0'
|
API version |
| sig |
all requests |
text/ascii |
API secure access token. |
| method |
all requests |
text/ascii
Must be one of the following:
- payment
- queryByOrderRef
- queryByTransactionId
- batchQueryByDates
|
API method to be invoked. |
|
| Payment parameters: |
| amt |
payment |
decimal number.
Example: 10.01
|
The total amount to be paid by the buyer.
|
| currency |
payment |
Three ascii characters.
ISO format.
Must be one of the following:
'AUD', 'NZD', 'GBP', 'USD', 'EUR'
|
The buyer currency. |
| ccnum |
payment |
text/ascii
Credit card number without hyphens and spaces.
|
|
| ccowner |
payment |
text/ascii
|
Credit card owner |
| ccmonth |
payment |
two digits (1-12).
Example: '05'
|
Credit card expiry month |
| ccyear |
payment |
two digits (1-99).
Example: '09'
|
Credit card expiry year |
| ref |
payment |
text/ascii
URL encoded.
|
seller's unique order reference ID |
| remote_ip |
payment |
text/ascii
URL encoded IP address.
Example: '1.1.1.1'
|
The IP address of the buyer's browser. |
|
| Payment buyer parameters: |
| firstname |
payment |
UTF8, URL encoded |
buyer first name |
| lastname |
payment |
UTF8, URL encoded |
buyer last name/surname |
| email |
payment |
UTF8, URL encoded |
buyer email |
| phone |
payment |
UTF8, URL encoded |
buyer phone |
| address1 |
payment |
UTF8, URL encoded |
buyer address |
| address2 |
payment |
optional, UTF8, URL encoded |
buyer address |
| citysub |
payment |
UTF8, URL encoded |
buyer city or suburb |
| stateprov |
payment |
UTF8, URL encoded |
buyer state or province |
| country |
payment |
text/ascii
two character country ISO code
Example: 'US'
|
buyer country |
| postcode |
payment |
text/ascii |
buyer post or zip code |
|
| Single query request parameters: |
| txnid |
queryByTransactionId |
text/ascii |
Paymate transaction ID |
| oref |
queryByOrderRef |
UTF-8, URL encoded. |
seller's order reference |
|
| Batch query request parameters: |
| startdate |
batchQueryByDates |
dd/MM/yyyy HH:mm:ss |
start date and time for the query. |
| enddate |
batchQueryByDates |
optional, dd/MM/yyyy HH:mm:ss
defaults to current date/time
|
end date and time for the query. |
| pagenumber |
batchQueryByDates |
integer (1-99)
defaults to 1
|
|
| pagesize |
batchQueryByDates |
optional integer (1-100)
defaults to 10
|
|
|
