TriggerPay Client API

TriggerPay offers a REST API which allows you to integrate the TriggerPay functionality in a flexible way with your own systems. How the API is implemented will depend on your own particular use case.

Below you will find details of each of the methods available with example requests and response objects.

For sandbox access, please request credentials from your TriggerPay account manager.

You can find some examples of business use cases which make use of this API in the Articles area of this website.

Overview

Messages should be send using HTTPS requests and in the case of POST requests the header “Content-Type” should be set to “application/json”.

The body of your request should be JSON encoded and in the format specified for each method below.

Responses will be returned in JSON format as specified in this document.

Authentication

The TriggerPay Client API uses API Keys to authenticate each request. Every request must include a header “X-ApiKey” followed by your api key.

API keys can be requested from your account manager.

End Points

The API end point is : https://api.triggerpay.co.uk/<method_name>

E.g. to make a request to createPayment you would send the request to https://api.triggerpay.co.uk/createPayment.

Message Flow

Payment processing in ecommerce checkout using redirect process.

Your customer selects TriggerPay as their payment method during their checkout process.
You call the createPayment method and with a successful response, you redirect the customer to the payment_link url.
Your customer follows the process of selecting their bank from the list and then authorises the payment with their bank account.
Your customer is then redirected to the url you provided in post_auth_url along with the status of the payment.
TriggerPay also sends you a webhook notification to a specified endpoint with the status of the payment. (at any time you also have the option to call getPayment to check on the status of the payment)

TriggerPay Client API

POST createPayment

This method is used to request a payment redirect link which your customer will follow in order to authorise payment with their preferred bank. On completion of this process they will be returned to the url you specify in the post_auth_url field along with the status of their payment.

If a valid mobile phone number is provided for customer_phone, TriggerPay will send the customer an SMS message with the payment authorisation link.

If a valid email address is provided for customer_email, TriggerPay will send the customer an email with the payment authorisation link.

Request JSON Example

{

“amount”:99.10,

“remittance_ref”:“order123”,

“post_auth_url”:“https://triggerpay.co.uk/return_url”,

“customer_name”:“Joe Bloggs”,

“customer_phone”:“447123456789”,

“customer_email”:“example@gmail.com”,

“order_details”: {

“items”: [

{

“name”: “Blue Jeans”,

“description”: “Wrangler Blue Jeans”,

“quantity”: 1,

“amount”: 89.10

{

“name”: “Hat”,

“description”: “Cowboy Hat”,

“quantity”: 1,

“amount”: 10

}

]

}

Field Descriptions:

Field	Data Type	Description	Required
amount	decimal	The total amount to be paid by the customer. Do not include any currency symbols. Maximum 2 decimal places	Yes
remittance_ref	string	This should be a value that identifies the order/booking on your system. Max Length 11 characters In addition to the regular set of alphanumeric characters the following special characters are allowed: / – ? : ( ) . , ‘ + Space # = ! “ % & * < > ; { @	Yes
post_auth_url	string	The location where the customer should be returned to after payment is authorised.	No (if not provided, we will use the default value assigned to the API Key used)
customer_name	string	Your customer’s name Max Length 100 characters	No
customer_phone	string	Your customer’s phone number. Please ensure it is provided without spaces and that it uses international format, e.g. 441211234567	No
customer_email	string	Your customer’s email address	No
order_details	array	Holds Order Details related to payment amount.	No
items	array	Holds list of the line items.	Yes – If you include the field order_details, it must follow the structure provided in the example.
name	string	The name of the item being purchased Max Length 35 characters This text will show in the order breakdown in the payment authorisation screen.	Yes – If you include the field order_details, it must follow the structure provided in the example.
description	string	Brief description of the item being purchased Max Length 254 characters This text will not show in the payment authorisation screen but will be available to the customers to view within the Customer TriggerPay dashboard.	Yes – If you include the field order_details, it must follow the structure provided in the example.
quantity	integer	Quantity of the particular item being purchased	Yes – If you include the field order_details, it must follow the structure provided in the example.
amount	decimal	Amount of payment in the specified currency at the specified rate. Do not include any commas or currency symbols.	Yes – If you include the field order_details, it must follow the structure provided in the example.

Response JSON Example

{

“status”:true,

“payment_id”:452809,

“payment_ref”:re27gry2dw,

“payment_link”:“https://api.nuapay.com/tpp-ui/redirect?userInterfacePaymentId=re27gry2dw”

}

Field	Data Type	Description
status	boolean	This will be either true or false depending on the success of generating the payment link.
payment_id	integer	Identifies the payment on the TriggerPay system and should be used in queries to getPayment.
payment_ref	string	Identifies the payment reference used in the bank authorisation process. This value is necessary for checkout processes that use the popup authorisation integration.
payment_link	string	The URL that you should send your customer to in order to authorise payment with their bank.

GET getPayment

At any time after a successful createPayment request, you are able to check the status of that request using the getPayment method.

As this is a GET request, there is no JSON body to pass. Instead, the payment_id is appended to the url as follows:

https://api.triggerpay.co.uk/getPayment/123456

You will receive a JSON response to your request as follows:

{

“status”: true,

“payment_id”: 12345,

“payment_ref”: “3omgl3gabk”,

“remittance_ref”: “1677510833”,

“payment_status”: “Requested”,

“created”: “2023-02-28 01:57:16”,

“payment_link”: “https://sandbox.nuapay.com/tpp-ui/redirect?userInterfacePaymentId=3omgl3gabk”,

“amount”: “10.10”,

“payment_link_expires”: “2023-02-28 04:57:16”,

“customer_name”: “Joe Smith”,

“customer_email”: “example@gmail.com”,

“customer_phone”: “+447123456789”,

“order_details”: {

“items”: [

{

“name”: “Pre-theatre Special”,

“description”: “Chicken & Rice”,

“quantity”: “1”,

“amount”: “12.99”

{

“name”: “Pre-theatre Special”,

“description”: “Steak & Ale Pie”,

“quantity”: “1”,

“amount”: “13.99”

{

“name”: “Beverages”,

“description”: “Btl House White Wine”,

“quantity”: “1”,

“amount”: “15.99”

}

]

}

Field	Data Type	Description
status	boolean	This will be either true or false depending on the success of retrieving the payment status.
payment_id	integer	Identifies the payment on the TriggerPay system and should be used in queries to getPayment.
payment_ref	string	Identifies the payment reference used in the bank authorisation process. This value is necessary for checkout processes that use the popup authorisation integration.
remittance_ref	string	Identifies the payment on your system.
amount	decimal	The total payment amount
payment_status	string	Will be one of: Requested Authorised Settled Cancelled
created	date time	Identifies when the payment request was made.
payment_link	string	The url customer should be directed to authorise the payment with their bank.
payment_link_expires	date time	The day and time the payment link will timeout and no longer be available for authorisation.
customer_name	string	The customer’s name.
customer_email	string	The customer’s email address.
customer_phone	string	The customer’s phone number.
order_details	array	Holds Order Details related to payment amount.
items	array	Holds list of the line items.
name	string	The name of the item being purchased
description	string	Brief description of the item being purchased
quantity	integer	Quantity of the particular item being purchased
amount	decimal	Amount of payment in the specified currency at the specified rate.

Notes on payment_status

Both the Authorised and Settled status values mean that the payment authorisation is successful. The settled status shows that in addition to the payment being authorised, the funds have physically been moved which for Faster Payments can take up to 2 hours.
A cancelled status includes when the customer has chosen not to continue with authorisation or should the bank decline the Faster Payments request, among other more specific scenarios.

POST refundPayment

This method is used to request a refund of a payment made by a customer. Refunds can only be made when the original payment status is Settled and the client balance has enough available funds to cover the refund. Once a refund request has been made, it will move to a status of Refund Settled or Refund Rejected once processed by the bank. A webhook will be sent when the status is updated to inform you of the result.

Request JSON Example

{

“amount”:22.50,

“payment_id”:1234,

“reason”:“cancelled booking”

}

Field	Data Type	Description	Required
amount	decimal	The total amount to be refunded to the customer. This cannot be more than the original payment amount less any other partial refunds	Yes
payment_id	integer	The numeric payment id of the original customer payment to apply the refund to.	Yes
reason	string	A short description of why the refund is being requested.	Not required but is recommended.

Response JSON Example

{

“status”:true,

“refund_id”:452809

}

Field	Data Type	Description
status	boolean	This will be either true or false depending on the success of requesting the refund..
refund_id	integer	Identifies the refund on the TriggerPay system and should be used in queries to getRefund.

GET getRefund

At any time after a successful refundPayment request, you are able to check the status of that request using getRefund.

As this is a GET request, there is no JSON body to pass. Instead, the refund_id is appended to the url as follows:

https://api.triggerpay.co.uk/getRefund/123456

You will receive a JSON response to your request as follows:

{

“status”: true,

“refund_id”: 123456,

“refund_status”: “Refund Requested”,

“created”: “2023-03-12 12:41:42”,

“amount”: “5.00”,

“customer_name”: “Joe Smith”,

“customer_email”: “example@gmail.com”,

“customer_phone”: “+44712345678”,

“reason”: “cancelled booking”,

“payment_id”: 123452

}

Field	Data Type	Description
status	boolean	This will be either true or false depending on the success of retrieving the payment status.
refund_id	integer	Identifies the refund on the TriggerPay system and should be used in queries to getRefund.
amount	decimal	The total amount refunded to the customer.
refund_status	string	Will be one of: Refund Requested Refund Rejected Refund Settled
created	date time	Identifies when the refund request was made.
customer_name	string	The customer’s name.
customer_email	string	The customer’s email address.
customer_phone	string	The customer’s phone number.
reason	string	Holds a description of the reason for the refund.
payment_id	integer	Identifies the payment record for which the refund has been requested.

POST customerAccountImport

This method is used to import customer accounts. Should an account already exist with the same ‘client_ref’ value, the account name and contact information will be updated.

Request JSON Example

[

{

“client_ref”:“ACCREFA”,

“name”:“Joe Bloggs”,

“mobile”:“+447987654321”,

“email”:“testing@testing.com”

{

“client_ref”:“ACCREFB”,

“name”:“Jim Jones”,

“mobile”:“07987654321”,

“email”: null

{

“client_ref”:“ACCREFC”,

“name”:“Jane Doe”,

“mobile”: null,

“email”:“testing@testing3.com”

}

]

Field	Data Type	Description	Required
client_ref	string	identifies the customer account on your system.	Yes
name	string	identifies the account name	Yes
email	string	identifies the email address of the account	Key is required but you may pass a null value
mobile	string	identifies the mobile number of the account. Please use international number format for any non-UK numbers.	Key is required but you may pass a null value

Response JSON Example

{

“status”: true,

“count_imported”: 1,

“count_updated”: 2,

“issues”: [

{

“client_ref”: “ACCREFC”,

“issue”: “Mobile provided is not a valid phone number.”

}

]

}

Field	Data Type	Description
status	boolean	This will be either true or false depending on the success of receiving the request.
count_imported	integer	Identifies the number of customer accounts created.
count_updated	integer	Identifies the number of customer accounts that already existed in the system and have been updated.
issues	array	Array of any issues identified when processing the request
client_ref	string	The client reference of the account which has identified an issue.
issue	string	A description of the issue encountered.

POST customerAccountSyncBalances

This method is used to bulk update customer account balances and due dates.

Request JSON Example

[

{

“client_ref”:“ACCREFA”,

“balance”:6.45,

“due_by”:“2022-12-30”

{

“client_ref”:“ACCREFB”,

“balance”:12.50,

“due_by”:“2022-12-30”

{

“client_ref”:“ACCREFC”,

“balance”:42.40,

“due_by”:“none”

}

]

Field Description

Field	Data Type	Description	Required
client_ref	string	This should be a value that identifies the customer account on your system.	Yes
balance	decimal	The amount to be paid by your customer. This must be greater than or equal to zero and no more than 2 decimal places.	Yes
due_by	date	The last day by which you should receive payment. Provided in the format yyyy-mm-dd and be a date in the future. To remove a due_by value from an account, please pass the string “none” as the value.	No

Response JSON Example

{

“status”: true,

“count_processed”: 2,

“issues”: [

{

“client_ref”: “ACCREFD”,

“issue”: “No customer account exists with this reference.”

}

]

}

POST customerAccountBalances

This method is used to request balance and account information for specific or all active and suspended accounts.

Request JSON Example – All Accounts

{“client_ref”:[]}

Request JSON Example – Specific Accounts

{“client_ref”:[“TEST123”,“ACCREFA”]}

Field Description

Field	Data Type	Description	Required
client_ref	array of string	An array of the account references that you want to return. Send an empty array to return all results.	Yes

Response JSON Example

{

“status”: true,

“count”: 2,

“accounts”: [

{

“client_ref”: “TEST123”,

“name”: “Test Account”,

“email”: “name@domain.com”,

“mobile”: “+447999999999”,

“balance”: “12.50”,

“status”: “ACTIVE”,

“due_by”: “2022-11-24”,

“created”: “2022-11-16 00:16:00”,

“modified”: “2022-11-23 12:11:00”

{

“client_ref”: “ACCREFA”,

“name”: “Joe Bloggs”,

“email”: “testing@testing.com”,

“mobile”: “+447888888888”,

“balance”: “0.00”,

“status”: “ACTIVE”,

“due_by”: null,

“created”: “2022-11-23 16:07:00”,

“modified”: “2022-11-23 16:19:00”

}

]

}

Field	Data Type	Description
status	boolean	This will be either true or false depending on the success of the request.
count	integer	Identifies the number of accounts found that meet the criteria.
accounts	array	An array of the accounts found
client_ref	string	identifies the customer account on your system.
name	string	identifies the account name
email	string	identifies the email address of the account
mobile	string	identifies the mobile number of the account
balance	decimal	identifies the balance due to the merchant
status	string	identifies if the account is currently ACTIVE or SUSPENDED
due_by	date	identifies the last date by which the balance should be paid. If empty, no due date has been set. Provided in format yyyy-mm-dd
created	datetime	identifies the date and time the account was first created on the TriggerPay system. Provided in format yyyy-mm-dd hh:mm:ss GMT
modified	datetime	identifies the date and time the account was last modified on the TriggerPay system. Provided in format yyyy-mm-dd hh:mm:ss GMT

POST customerAccountAudits

This method is used to request the audit trail for all or specific customer accounts for within a specified period. The maximum date range for requests is 90 days.

Request JSON Example

{

“client_ref”:[“TEST123”,“ACCREFA”],

“type”:[“SYNC_BALANCE_EDIT”,“EMAIL_CHANGE_SYNC”],

“start_date”:“2022-11-12”,

“end_date”:“2022-11-23”

}

Field Description

Field	Data Type	Description	Required
client_ref	array of strings	An array of the account references that you want to return. Send an empty array to return all results.	Yes
type	array of strings	An array of the record types you want to return. Send an empty array to return all results. See Appendix 1 for a full list of options.	Yes
start_date	date	The start date of the date range (inclusive) in format yyyy-mm-dd	Yes
end_date	date	The end date of the date range (inclusive) in format yyyy-mm-dd	Yes

Response JSON Example

{

“status”: true,

“count”: 2,

“accounts”: {

“TEST123”: [

{

“type”: “SYNC_BALANCE_EDIT”,

“description”: “Balance updated via automatic synchronisation with merchant system.”,

“balance_before”: “130.00”,

“balance_after”: “12.50”,

“created”: “2022-11-22 13:19:00”

}

“ACCREFA”: [

{

“type”: “EMAIL_CHANGE_SYNC”,

“description”: “Email number changed from testing@testing.com to testing2@testing.com via automatic synchronisation with merchant system.”,

“balance_before”: “0.00”,

“balance_after”: “0.00”,

“created”: “2022-11-23 16:07:00”

}

]

}

Field	Data Type	Description
status	boolean	This will be either true or false depending on the success of the request
count	integer	Identifies the number of customer accounts returned.
accounts	array	Index of array is the account reference followed by an array of audit entries that match the request.
type	string	The type of action that has been recorded. See Appendix 1 for a full list of possible values.
description	string	A more full description of the action that took place.
balance_before	decimal	The balance before the action.
balance_after	decimal	The balance after the action.
created	datetime	The date and time that the record was created with the format yyyy-mm-dd hh:mm:ss GMT

POST customerAccountRequestPayment

This method is used to notify customer account owners of an outstanding balance which is due to be paid. An email and/or SMS message is sent to each customer account specified with a link to initiate the payment of their account balance.

Request JSON Example – All Accounts

{“client_ref”:[]}

Request JSON Example – Specific Accounts

{“client_ref”:[“TEST123”,“ACCREFA”]}

Field Description

Field	Data Type	Description	Required
client_ref	array of string	An array of the account references that you want to return. Send an empty array to return all results.	Yes

Response JSON Example

{

“status”: true,

“count”: 3,

“issues”: [

{

“client_ref”: “ACCREFB”,

“issue”: “No phone number provided.”

{

“client_ref”: “ACCREFC”,

“issue”: “No email provided.”

}

]

}

Field	Data Type	Description
status	boolean	This will be either true or false depending on the success of the request.
count	integer	Identifies the number of accounts that meet the criteria of having a balance greater than zero and a status other than ARCHIVED.
issues	array	Array of any issues identified when processing the request
client_ref	string	The client reference of the account which has identified an issue.
issue	string	A description of the issue encountered.

}

Refund Rejected

This event will be triggered should a refund change status to Refund Rejected. The following JSON data will be communicated by POST to the URL you specified:

{

“event”:“REFUND_REJECTED”,

“refund_id”:12345,

“timestamp”: “2022-11-03 14:22:33”

}

Appendix 1 – Audit Types

‘ACCOUNT_CREATED’
‘MANUAL_BALANCE_EDIT’
‘SYNC_BALANCE_EDIT’
‘PAYMENT_RECEIVED
‘FINE_APPLIED’
‘ACCOUNT_SUSPENDED’
‘ACCOUNT_ACTIVATED
‘ACCOUNT_ARCHIVED’
‘NAME_CHANGE_SYNC’
‘NAME_CHANGE_MANUAL’
‘EMAIL_CHANGE_SYNC’
‘EMAIL_CHANGE_MANUAL’
‘MOBILE_CHANGE_SYNC’
‘MOBILE_CHANGE_MANUAL’
‘DUE_DATE_CHANGE_MANUAL’
‘CLIENT_REFERENCE_CHANGE’

TriggerPay Client API

Quick Links

Overview

Authentication

End Points

Message Flow

TriggerPay Client API

POST createPayment

GET getPayment

POST refundPayment

GET getRefund

POST customerAccountImport

POST customerAccountSyncBalances

POST customerAccountBalances

POST customerAccountAudits

POST customerAccountRequestPayment

Webhooks from TriggerPay System to Client

Account Suspended

Account Activated

Payment Authorised

Payment Settled

Payment Cancelled

Refund Settled

Refund Rejected

Appendix 1 – Audit Types