Issue an EmailPay link

The first step to processing an EmailPay transaction is to submit an issue request via our API which can additionally be processed with 3D Secure. Configuring your account for 3D Secure can be performed at boarding or at a later date.

In response to an EmailPay Single Link issue request for a payment or payout, a single URL is returned. In the case of an EmailPay Batch issue request a batch of payment or payout URLs is returned. You can then use the returned URL(s) to present to the customer(s), via any electronic means including email, SMS, chat facilities and social media.

When creating payout links that require a saved payment method such as a stored card, there can be no guarantee that the payment method still exists or is valid at the time the payout link is activated. Visiting a payout link that requires a saved payment method, when there is none, will show an error page.

Single LinkBatch of Links

API Examples

Creating a Payment Link with an Expiry date



POST /smartlink/links/{instId}/payment
{
  "smartLink": {
    "expires": "2022-12-24T12:15:00.000+00:00"
  },
  "transaction": {
    "merchantReference": "mer_txn_1234556",
    "money": {
      "currency": "GBP",
      "amount": {}
    },
    "description": "some transaction description",
    "commerceType": "ECOM"
  }
}

HTTP/1.1 201
{
  "smartLinkResponseDetail": {
    "expires": "2022-12-24T12:15:00.000+0000",
    "usage": "SINGLE",
    "status": "ACTIVATED",
    "link": "https://s.mite.pay360.com/a/X_HrVFwx8_A",
    "linkId": "52aef20c-6b53-4491-ad5d-08c25e681af0"
  },
  "status": "SUCCESS",
  "reasonCode": "S100",
  "reasonMessage": "SmartLink created"
}

Creating a Payout Link with an Expiry date



POST /smartlink/links/{instId}/payout
{  

   "smartLink": {
     "expires": "2022-12-24T12:15:00.000+00:00"
    },
    "transaction": {
        "merchantReference": "mer_txn_1234556",
        "money": {
            "currency": "GBP",
            "amount": {
                "fixed": 10.99
            }
        },
        "commerceType": "ECOM",
        "description": "SmartLink Payout"
    },
    "session": {
        "returnUrl": {
            "url": "http://www.example.com/return"
        },
        "cancelUrl": {
            "url": "http://www.example.com/cancel"
        }
    },
    "features": {
        "newAccountPayoutEnabled": true
    }
}

HTTP/1.1 201
{
  "smartLinkResponseDetail": {
    "expires": "2022-12-24T12:15:00.000+0000",
    "usage": "SINGLE",
    "status": "ACTIVATED",
    "link": "https://s.mite.pay360.com/a/X_HrVFwx8_A",
    "linkId": "b4560fb2-fc18-4033-9505-08708b1788b1"
  },
  "status": "SUCCESS",
  "reasonCode": "S100",
  "reasonMessage": "SmartLink created"
}

API Endpoints

endpoint: /smartlink/links/{instId}/payment

endpoint: /smartlink/links/{instId}/payout

method: POST

summary: Issue a Link

parameters:

instId

string

The installation id

request body:

{
smartLink {
expires	dateTime Date/time at which the link should expire and become unusable, in ISO-8601 format. Omit to create a link that does not expire. Links may be cancelled early if needed.
onDeadLink	string URL to redirect the customer to upon attempting to access an expired or otherwise inactive link. Where possible, the customer is redirected to this URL with a query string of `?l={linkId}&s={status}` where `{status}` is one of `DEACTIVATED`, `CANCELLED`, `USED`, `EXPIRED`, `ERROR`, `PENDING` or `NOT_FOUND`. When not set, or where link details cannot be retrieved, a generic error page will be used instead.
}
transaction {	Mandatory
merchantReference	string Your reference for the transaction.
money {	Mandatory
currency	string Mandatory The currency of your Customer’s transaction. Use the 3 character ISO-4217 code.
amount {	Mandatory Choose one of fixed, choice, range or suggested amount specifications.
fixed	float Choice Use if you want your customer to only make a payment for a fixed amount. The customer can not change the amount.
choice {	Choice Use if you want your customer to select from a predefined set of amounts.
option [	array Mandatory
item	float
]
}
range {	Choice Use if you want your customer to choose an amount between a minimum and maximum value. You can also provide a default amount. This can be overtyped by the customer if they want to.
min	float
max	float
default	float
}
suggested {	Choice Use if you want to your customer to choose an amount between a minimum and maximum value or from a predefined set of amounts.
choice {	Mandatory
option [	array Mandatory
item	float
]
}
range {	Mandatory
min	float
max	float
default	float
}
}
}
}
description	string The description of the transaction.
commerceType	string Possible Values: ECOM, MOTO The commerce type for your Customer’s transaction.
channel	string Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER The sales channel for your Customer’s transaction. If no channel is provided we’ll automatically classify the channel as WEB
deferred	boolean Indicates if you want the Payment to be Authorised and Captured separately.
recurring	boolean Indicates that the Payment should initiate a recurring Continuous Authority relationship.
instalment	boolean Indicates that the Payment should initiate an instalment Continuous Authority relationship.
continuousAuthorityAgreement {	Conditional The continuous authority agreement established with the cardholder. Required if you want to process a transaction initiating a recurring or instalment series using 3DSv2
minFrequency	integer Mandatory Minimum number of days expected between payments in a recurring or instalment sequence. Must be >= 1.
expiry	date Mandatory Date (YYYY-MM-DD) at which recurring/instalment agreement expires, or at which it will need to be re-authenticated in order to continue. Must be in the future.
numberOfInstalments	integer Conditional Total number of payments in an instalment sequence – including this one, if starting with a payment. Required only for instalments; must be >= 2.
}
do3DSecure	boolean Indicates if the transaction should be processed with 3D Secure. This will override account configuration for 3D Secure.
}
customer {
create	boolean Deprecated. Use ‘registered’ instead, as this will be removed in the future.
registered	boolean Indicates if you wish to create or use a registered customer. False if you do not wish to register your customer, otherwise set to true. Default value is true.
identity {	Conditional Mandatory when registering a new customer, or using an already registered customer, optional otherwise.
platformCustomerId	string Choice Our ID for your customer.
merchantCustomerId	string Choice Your ID for the customer.
}
details {	Conditional Mandatory when registering a new customer, optional otherwise.
name	string Conditional The Customer’s name. Required when registering a new customer, optional otherwise.
address {	The address of the Customer.
line1	string Line 1 of the Customer’s billing address.
line2	string Line 2 of the Customer’s billing address.
line3	string Line 3 of the Customer’s billing address.
line4	string Line 4 of the Customer’s billing address.
city	string City of the Customer’s billing address.
region	string Region of the Customer’s billing address.
postcode	string Post Code of the Customer’s billing address.
countryCode	string The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
telephone	string Telephone number for the customer. For best results, use international format, e.g. “+441234567890”.
emailAddress	string Email address for the Customer.
ipAddress	string The Customer’s IP address.
}
}
financialServices {	Supplementary data for Financial Services payments, including loan repayments and other credit-related activities. UK- and Europe-based merchants with merchant category code (MCC) 6012, and some merchants coded MCC 6051 or MCC 7299, are required to provide this information about the primary recipient, who may be different from the customer making payment. Consult your acquirer if you are not sure whether you should submit this. Cannot be submitted in conjunction with accountFunding.
dateOfBirth	string Date of birth of the recipient, in YYYYMMDD format. For example, for Jan 2nd, 1980, this would be “19800102”.
surname	string Surname/family name of the recipient; up to six characters, excluding numbers or special characters. If the name is longer than six characters, then provide the first six. For example, for “Smith”, this would be “Smith”; for “Williams”, this would be “Willia”.
accountNumber	string Account number used to identify the recipient or loan. If this is a PAN, then provide the first six and last four digits of the PAN. Otherwise, provide up to ten characters of the account number.
postCode	string First part of the recipient’s postal code; up to six characters. For example, if the postal code is “LE11 3QF”, this would be “LE11”.
}
accountFunding {	Supplementary data for Account Funding Transactions (AFT), e.g. money transfers. You should provide this if advised by your acquirer. Cannot be submitted in conjunction with financialServices.
recipient {	Details about the funding recipient
givenName	string Recipient’s given name
surname	string Recipient’s surname/family name
address	string Recipient’s address (house/building name and number, street/road name, etc.)
city	string Recipient city
state	string Only for recipients based in the US or Canada Recipient state/province code (2-3 characters), e.g. “CA”, “DE”, “MD”, “TN” et al. in the US; “AB”, “ON”, “QC”, “SK” et al. in Canada
countryCode	string Recipient country code (ISO-3166-alpha-3), e.g. “CAN”, “GBR”, “USA” et al.
}
}
locale	string The ISO-639 code for your Customer’s locale.
features {	Holder of features that can be enabled/disabled during a hosted session.
paymentMethodRegistration	string Possible Values: always, optional Allow the customer to choose if they wish their payment method to be registered.
paymentMethods	array Possible Values in the Array: card, applepay, googlepay, paypal, openbanking, visacheckout Specify which payment methods are to be displayed, in the specified order. The array should contain strings for the names of payment methods. This is only available for a version 2 skin. Any payment methods not enabled on your account will not be displayed.
newAccountPayoutEnabled	string Possible Values: true, false Allow the customer to register a new payment method for a payout.
sendEmailReceipt	boolean If true, an email receipt will be sent for this transaction. If false, no receipt will be sent. If not present, your account configuration determines if an email is sent.
showResultsPage	boolean If true, after processing the transaction, a result page with a summary of key transaction details is shown prior to returning the customer. Default is false. If omitted, your account configuration will determine whether this is shown. Only available when using a version 2 skin. For EmailPay links, if no `session.returnUrl` is supplied, then a second, simpler result page is shown instead.
}
session {
preAuthCallback {	Details of the callback made before the transaction is sent for authorisation.
url	string Mandatory The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format	string Possible Values: REST_XML, REST_JSON The format of the callback content.
}
postAuthCallback {	Details of the callback made after the transaction is sent for authorisation.
url	string Mandatory The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format	string Possible Values: REST_XML, REST_JSON The format of the callback content.
}
transactionNotification {	Details of the notification sent after transaction completion.
url	string Mandatory The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format	string Possible Values: REST_XML, REST_JSON The format of the callback content.
}
returnUrl {	The URL that we will return your customer to after processing the transaction. If omitted a simple result page will be displayed.
url	string Mandatory
}
cancelUrl {	The URL that we will return your customer to if they cancel the hosted session. If omitted the returnUrl is used if they cancel.
url	string Mandatory
}
skin	string The ID of the skin used to drive look and feel for this session. Refer to Customise hosted look and feel for more information
}
customerNotice {	Additional information/instructional text to display to the customer while collecting payment details; see Customer Notice
content	string Text to display to the cardholder, up to 1000 characters. Supports a limited subset of HTML.
locator	string Possible Values: FORM_TOP, FORM_AFTER, FORM_BOTTOM Position of the notice on the page. Defaults to FORM_TOP if not set.
}
}

response:

{
smartLinkResponseDetail {	The details of the created link.
expires	dateTime The date and time this link will expire, in ISO-8601 format.
onDeadLink	String URL the customer will be redirected to upon attempting to access an expired or otherwise inactive link.
usage	string Possible Values: SINGLE Links can be used to make a single successful transaction. They may be re-accessed after a decline or other failure in order to try again.
status	string Possible Values: ACTIVATED, DEACTIVATED, CANCELLED, USED, EXPIRED Links are created with a status of ACTIVATED.
link	string The link. A HTTP URL that will initialise a Hosted session so that a payment or payout may be taken.
linkId	string A unique ID that can be used to identify the link created.
}
status	string Possible values: SUCCESS, FAILURE Status of the request
reasonCode	string A code that indicates a response message, it can be looked up for trouble shooting.
reasonMessage	string A description of the reason code.
}

API Examples

Creating a Batch of Payment Links with a single Expiry Date



POST /smartlink/links/{instId}/batch/payment
{
  "smartLink": {
    "expires": "2022-12-24T12:15:00.000+00:00"
  },
  "transaction": {
    "merchantReference": "mer_txn_1234556",
    "money": {
      "currency": "GBP",
      "amount": {}
    },
    "description": "some transaction description",
    "commerceType": "ECOM"
  },
  "batchSize": 3
  
}

HTTP/1.1 201
{
  "smartLinkResponseDetail": {
    "expires": "2020-12-24T12:15:00.000+0000",
    "usage": "SINGLE",
    "status": "ACTIVATED",
    "links": [
      {
        "linkId": "f5bb6bd2-9a22-43f3-b881-d912fef8d1ae",
        "link": "https://s.mite.pay360.com/a/X_HrVFwx8_A_1"
      },
      {
        "linkId": "f8bd586d-5b1d-4b78-bee0-a9479b6fa14f",
        "link": "https://s.mite.pay360.com/a/X_HrVFwx8_A_2"
      },
      {
        "linkId": "dc3a77ef-24c5-4c98-866d-58799deab378",
        "link": "https://s.mite.pay360.com/a/X_HrVFwx8_A_3"
      }
    ]
  },
  "status": "SUCCESS",
  "reasonCode": "S100",
  "reasonMessage": "SmartLink batch created"
}

Creating a Batch of Payout Links with a single Expiry Date



POST /smartlink/links/{instId}/batch/payout
{
    "transaction": {
        "merchantReference": "mer_txn_1234556",
        "money": {
            "currency": "GBP",
            "amount": {
                "fixed": 10.99
            }
        },
        "commerceType": "ECOM",
        "description": "SmartLink Payout"
    },
    "session": {
        "returnUrl": {
            "url": "http://www.example.com/return"
        },
        "cancelUrl": {
            "url": "http://www.example.com/cancel"
        }
    },
    "features": {
        "newAccountPayoutEnabled": true
    },
    "batchSize": 3
}

HTTP/1.1 201
{
  "smartLinkResponseDetail": {
    "usage": "SINGLE",
    "status": "ACTIVATED",
    "links": [
      {
        "linkId": "23876105-112a-4bd3-a5f4-d549bd6ffb73",
        "link": "https://s.mite.pay360.com/a/X_HrVFwx8_A_1"
      },
      {
        "linkId": "4167174d-6082-44bc-be1e-893529802245",
        "link": "https://s.mite.pay360.com/a/X_HrVFwx8_A_2"
      },
      {
        "linkId": "cbb2d759-e463-4167-ae6a-4ac8d21da247",
        "link": "https://s.mite.pay360.com/a/X_HrVFwx8_A_3"
      }
    ]
  },
  "status": "SUCCESS",
  "reasonCode": "S100",
  "reasonMessage": "SmartLink batch created"
}

API Endpoints

endpoint: /smartlink/links/{instId}/batch/payment

endpoint: /smartlink/links/{instId}/batch/payout