Uses the PAY.Link endpoint.
Before you start #
On the Plugin settings page, make sure you’ve entered your Merchant UUID and API Key – these can be found on the Settings page in Barracks. You’ll also need to enter your Endpoint – see the Setup page for information.
Collect Data #
You will need to collect:
- Amount (as a decimal number – we recommend collecting/storing this as a “currency” field)
- Currency (3-letter code)
- Transaction Product (sale/payment reference) (text)
- Hash – we’ll cover how to generate this below.
- Return URL – OPTIONAL
- Notify URL – OPTIONAL
- Expiry (date-time) – OPTIONAL
- Customer Name (text)
- Customer Address (text)
- Customer City (text)
- Customer State (text)
- Customer Country (2 letters)
- Customer Postcode (4-10 characters)
- Customer Phone (up to 25 numbers) – OPTIONAL but recommended
- Customer Email (text) – OPTIONAL but recommended
- Send Email (boolean)
- Reminder Frequency (number)
- Custom 1/2/3 (text) – OPTIONAL
- Reference Text (text) – OPTIONAL
- Link Reference ID (text) – OPTIONAL
We recommend storing the expiry month and year in a Thing directly from the input fields when parsing the response, as they are not passed back by Merchant Warrior. This will help with managing expiring cards.
Create a Workflow #
Create a Workflow, and add the “MW – PAY.Link” action from the “Plugins” tab of the Actions list.
Each parameter in the action settings matches a parameter in the Merchant Warrior documentation.
transactionAmount #
The amount must be formatted to have two decimal places. Any amounts without two decimal places or amounts less than one cent will be rejected.
Example: 10.00
We recommend passing this from a “currency” field, then entering it as dynamic data “formatted as:” “number”, to 2 decimal places, with a period for the decimal and no symbol for the thousands. Have a look at how we pass the value to the Hash in this step for a reference.
transactionCurrency #
One of the following: AUD, CAD, EUR, GBP, JPY, NZD, SGD, USD. This is provider dependent. Please check with MW before attempting to process transactions in any currency other than AUD. This field is case insensitive.
Example: AUD
transactionProduct #
A product (or sale) id or description. We recommend using an order/product id. This field’s primary purpose is to help the transaction be identifiable for reporting and accounting purposes.
Example: ABC4321
Valid length: Up to 255 characters. Some Acquirers limit this field to 40 characters.
hash #
returnURL #
If hardcoded in Barracks, leave blank.
The customer will be redirected to this URL upon completion of the transaction. This parameter can also be hardcoded via the merchant administration interface.
Example: https://www.example.com/return.php
notifyURL #
If hardcoded in Barracks, leave blank.
If no specific URL required, leave as default URL provided.
Asynchronous POST notifications will be sent to this URL. This parameter can also be hardcoded via the merchant administration interface.
Example: https://www.example.com/notify.php
expiry #
If you’re redirecting the end-user to the PAY.Link straight away, you can leave this blank, expiry will default to 7 days.
The expiration of the unique payment link. This parameter should be formatted as a DateTime (yyyy-mm-dd hh:mm:ss). By default the unique payment link will expire after 7 days.
Example: 2017-05-01 17:45:12
customerName #
This field can only contain alphanumeric characters, as well as the full stop, comma, apostrophe, ampersand, space and hyphen characters.
Example: Mr. Example Person
Valid length: Between 2 and 255 characters
customerAddress #
Freeform field.
Example: 123 Test Street
Valid length: Up to 255 characters
customerCity #
Freeform field, keep consistent for your records and reporting.
Example: Brisbane
Valid length: Up to 75 characters
customerState #
Freeform field, keep consistent for your records and reporting.
Example: Queensland
Valid length: Up to 75 characters
customerCountry #
Two letter ISO 3166-1 alpha-2 country code.
Example: AU
Valid length: 2 characters
customerCountry #
This can also accommodate ZIP/Post codes for international transactions.
Example: 4000
Valid length: Between 4 and 10 characters
customerPhone #
Optional, but highly recommended.
Anything other than +,-, space and 0-9 will be stripped.
Example: 0401234567 or 61731234567
Valid length: Up to 25 characters
customerEmail #
Optional, but highly recommended.
Example: person@example.com
Valid length: Up to 255 characters
sendEmail #
This value is a boolean denoting whether to automatically send an email to the customer with the unique payment link
Example: 1
reminderFrequency #
How often to send a reminder email to the customer if the unique payment link is unpaid. Reminder emails will only be sent if the sendEmail parameter was set to true. If this value is not set, or 0, no reminder emails will be sent
Example: 7
custom1/2/3 #
These fill the Custom1, Custom2, and Custom3 fields in Barracks – they’re optional.
Freeform fields.
Valid length: Up to 500 characters each
referenceText #
Optional
This parameter is used to describe the order/product ID or reference. It will be placed next to the transactionProduct mentioned above in the payment page.
Example: Booking #
Valid length: Up to 50 characters
linkReferenceID #
Optional
This is a merchant’s unique reference ID that can be used to match a uniqueCode with a merchant’s internal reference ID.
Example: A257240023321
Valid length: Up to 40 characters
Parse Response #
The response will contain:
custom1/2/3 (if present) #
The same format posted in the original request.
responseCode #
| Code | Meaning |
|---|---|
| < 0 | MW validation error |
| 0 | Transaction/Operation was successful |
| > 0 | Transaction/Operation was declined or delayed by the provider or service |
responseMessage #
If the responseCode is not 0, this will provide basic insight into the reason for failure.
uniqueCode #
Long-form string with the ID of the link.
expiry #
DateTime format of the expiry of the link.
linkURL #
The full URL of the PAY.Link
transactionProduct #
The same format posted in the original request.
transactionAmount #
The same amount/format posted in the original request.
transactionCurrency #
The same format posted in the original request.
linkReferenceID (if present) #
The same format posted in the original request.
Next Actions #
We recommend adding a step with an “only when” of “…’s responseCode is not 0” that deals with the error, most commonly parsing the “responseMessage”. Otherwise, passing the variables you need to a Thing and/or to an Element, would be the logical next step.
