Payments API

At a glance

The Payments API lets your server send payments to Monek directly, with no customer on a payment page. Use it for repeat and recurring charges, refunds, and call centre payments.

For taking payments on your website, the Checkout Page is usually the better choice. It handles card details and 3-D Secure for you.

Try it

See how a Payments API request works, step by step. This is a simulation: nothing is sent to Monek.

Demo only. Nothing is sent to Monek and no payment is taken.

1Request
2Process
3Response

1. Your server sends a request

Amount (£)ApiKey

Card numberExpiry (MM/YY)CV2

Try 25.00 (approved) or 120.00 (declined), the same rules as a Monek test account. Clear the ApiKey to see what happens without it.

Sending card details from your own systems requires PCI DSS accreditation. For payments on your website, use the Checkout Page instead.

The request your server sends:

POST /Secure/Transact.ashx HTTP/1.1
Host: elite.monek.com
Content-Type: application/x-www-form-urlencoded

MerchantID=0000000&ApiKey=YOUR_API_KEY&Amount=2500&CountryCode=826&CurrencyCode=826&MessageType=SALE_CNP_TO&Dispatch=NOW&ResponseAction=JSON&ThreeDSAction=NONE&CardNumber=&ExpiryMonth=&ExpiryYear=&CV2=&PaymentReference=ORDER-1001

Before you start

Testing your integration

Staging is not a sandbox. To test your integration, request a test Merchant ID from support@monek.com. Test Merchant IDs return simulated responses based on the transaction amount. See Test Cards for the expected responses.

Never send real card details to a test Merchant ID, and never use your live Merchant ID for testing on either gateway.

Authentication

Every Payments API request must include your MerchantID and ApiKey. Contact Monek Support to get your API key.

info

ApiKey is replacing ValidityID and will be required for all direct server to server transaction requests. All new integrations should ensure ApiKey is populated in preparation for this change.

If you have already been issued a ValidityID you can continue to use this value as your ApiKey.

ApiKey and ValidityID must be kept private and should only be used on direct API calls. ApiKeyDigest will be available soon for use on public hosted page redirects.

Gateway URLs

Primary: https://elite.monek.com/Secure/Transact.ashx
Staging: https://staging.monek.com/Secure/Transact.ashx

Both gateways are live and will process payments for all Monek merchant accounts. Staging gives early access to new features before they reach the primary platform.

Making a request

Send a server-to-server HTTP POST to Transact.ashx, with the fields form-encoded (Content-Type: application/x-www-form-urlencoded). The result comes back in the same call. Set ResponseAction=JSON for the most detailed response.

This example refunds £10.00 of an earlier payment, using the CrossReference that payment returned:

POST /Secure/Transact.ashx HTTP/1.1
Host: elite.monek.com
Content-Type: application/x-www-form-urlencoded

MerchantID=0000000&ApiKey=YOUR_API_KEY&Amount=1000&CountryCode=826&CurrencyCode=826&MessageType=REFUND_CNP&Dispatch=NOW&ResponseAction=JSON&ThreeDSAction=NONE&CrossReference=240401101112457459X2R&PaymentReference=REFUND-0001

A ResponseCode of 00 means the transaction succeeded. See Response formats for a full example response, and Response Code Values for the other codes.

Common tasks

You can try the first four in the demo above.

Task	`MessageType`	Send	More
Take a payment, e.g. a phone or mail order	`SALE_CNP_TO` / `SALE_CNP_MO`	Card details	Requires PCI DSS accreditation. For payments on your website, use the Checkout Page.
Check a card without charging it	`VERIFY_CNP`	Card details, `Amount=0`	No money is taken
Charge a stored card, e.g. a monthly subscription	`ESALE_KEYED`	`CrossReference`, `CAType`, `COFInitiatedBy=MERCHANT`	Recurring Payments
Refund a payment	`REFUND_CNP`	`CrossReference` of the original payment
Reverse a payment made today	`REVERSAL_KEYED`	`CrossReference` of the original payment	Same day only
Settle a payment authorised earlier	`PAYMENT_ONLY_` prefix	`CrossReference`, `AuthorisationCode`	Deferred Dispatch

All of these need your ApiKey.

Looking for a field that isn't here?

The full list of every request and response field, and every message type, is in the Field Reference.

Recommended features

Idempotency Tokens protect against duplicate transactions if your system retries a request.
Webhooks send transaction results straight to your server.
Basket Details send itemised basket details, which also meets American Express requirements.

3-D Secure by API

If the ThreeDSAction field was set and the Transact.ashx has determined that user authentication is required, then an appropriate 3-D Secure response will be returned and must be processed by the merchant. Otherwise a standard Transaction Response will be returned.

tip

In most cases the Checkout Page flow is more appropriate for Ecommerce transactions with 3-D Secure

JSON
XML
HTMLQS
REDIRECT
ACSDIRECT

If the ThreeDSAction field was set to JSON the response fields are sent to the client as JSON in the body of the response e.g.

{
    "veResponse": {
        "md": "[ENCODEDDATA]",
        "enrolled": "Y",
        "paReq": "[ENCODEDDATA]",
        "acsUrl": "https://3ds2api.monek.com/3ds/acs"
    }
}

If the ThreeDSAction field was set to XML the response fields are sent to the client as XML 1.0 in the body of the response e.g.

<?xml version="1.0" encoding="UTF-8"?>
<veresponse>
    <md>[ENCODEDDATA]</md\> 
    <enrolled>Y</enrolled> 
    <pareq>[ENCODEDDATA]</pareq> 
    <acsurl>https://3ds2api.monek.com/3ds/acs</acsurl>
</veresponse>

If the ThreeDSAction field was set to HTMLQS the response fields are sent to the client as a QueryString style list of field names and values in the body of the response e.g.

MD=<ENCODEDDATA>&PaReq=<ENCODEDDATA>&ACSURL=https%3a%2f%2fdropit.3dsecure.net%3a9443%2fPIT%2fACS

If the ThreeDSAction field was set to REDIRECT TransactDirect issues a redirect to the web client, redirecting it to the Ret3DSAddress with the response fields sent as query string attachments to the redirect URL e.g.

http://www.myurl.com/3ds.asp?md=[ENCODEDDATA]&pareq=[ENCODEDDATA]&acsurl== https%3a%2f%2fdropit.3dsecure.net%3a9443%2fPIT%2fACS

If the ThreeDSAction field was set to ACSDIRECT then TransactDirect will automatically redirect the client to the appropriate ACS URL for authentication. The ACS request will be configured to automatically redirect back to TransactDirect (TransactACS.ashx) on completion.

Note: This method provides for the simplest implementation of 3-D Secure and requires no additional coding or communication with the Web Client due to the automatic redirect handling, however this flow is more appropriate when using the Checkout Page transaction flow.

3-D Secure ACS Response Fields

If the ThreeDSAction was set to HTMLQS, XML or REDIRECT the response will include the following fields to allow the Web Client to handle the ACS redirection. For example, if the Web Client needs to embed the ACS prompt within a branded web page.

Field Name	Description	Size	Type
ACSURL	Access Control Server URL. Used in redirecting the client browser to the card issuer's 3-D Secure authentication host.	V	A
MD	Merchant Data. All transaction data is retained by the `Transact.ashx` page. The MD field is used to allow this data to be retrieved and must be included unaltered in the subsequent calls to the `ACSURL` and `TransactACS.ashx`.	V	A
PAReq	The full 3-D Secure request as returned by the card scheme enrolment verification server. This should be passed in its entirety to the issuer's ACS.	V	A

Redirect to Card Issuer's ACS

The web client must redirects the cardholder to the 3-D Secure web server at ACSURL by sending the following fields as an HTTP POST request. Note: The ACSURL will not accept transactions redirected using the HTTP GET method.

Field Name	Description	Req'd	Size	Type
MD	Merchant Data. This field should be passed unaltered from the Transact.ashx response.	M	V	A
PaReq	The full 3-D Secure request. This field should be passed unaltered from the Transact.ashx response.	M	V	A
TermUrl	Termination URL. This is the address that the issuer's ACS will call after payer authentication is complete.	M	50 max.	A

The TermUrl field can be used to direct the ACS response back to the Web Client or directly to TransactACS.ashx to complete the transaction.

ACS Response Fields

If TermUrl is set to direct responses to the merchant web site, then the following fields will be returned. All fields should be forwarded in their entirety and unaltered to TransactACS.ashx to complete the transaction.

Field Name	Description	Req'd	Size	Type
MD	Merchant Data.	M	V	A
PaRes	The full 3-D Secure response as returned by the cardholder's issuer.	M	V	A

If TermUrl is set to direct to TransactACS.ashx then these fields will be passed automatically.

At a glance​

Try it​

1. Your server sends a request

Before you start​

Authentication​

Gateway URLs​

Making a request​

Common tasks​

Recommended features​

3-D Secure by API​

3-D Secure ACS Response Fields​

Redirect to Card Issuer's ACS​

ACS Response Fields​