Esenda 3rd Party Integration Guide
Contents
Overview
Esenda offers an easy-to-implement solution for CRMs and MISs to add payment functionality to their platform. To collect payments on behalf of your customers:
- Authenticate
- Create an Esenda transaction, by making a payment request
- Store the request_id and redirect the user to the payment_link
- Receive payment webhooks to update the payment status within your platform.
Authentication
Make a request to the authorisation endpoint using your client_id and client_secret keys. The response will return a token which will be used in the following requests to our API.
Production Authentication Request
curl --request POST \
--url https://api.esenda.com/oauth/token \
--header 'content-type: application/json' \
--data '{"client_id":"ABC","client_secret":"XYZ","audience":"organisation","grant_type":"client_credentials"}'
Sandbox Authentication Request
curl --request POST \
--url https://api-dev.esenda.com/oauth/token \
--header 'content-type: application/json' \
--data '{"client_id":"ABC","client_secret":"XYZ","audience":"organisation","grant_type":"client_credentials"}'
Payment request
Once authenticated, you can make a request to start a new transaction within Esenda. This will generate a payment link which you will redirect the user to and provide you with a request ID so that you can track the status of the payment.
https://api.esenda.com/v1/partner/payment-links/one-time-use
https://api-dev.esenda.com/v1/partner/payment-links/one-time-use
POST
/v1/partner/payment-links/one-time-use
Headers
Accept-Language: <LANGUAGE> (optional, default en-GB)
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
You will need to pass the parameters below as the request’s payload.
| Parameter name | Type | Required | Description | Example |
|---|---|---|---|---|
| shortcode | String | Yes | Your Esenda identifier | example_school |
| email_address | String | Yes | The payer's email address | [email protected] |
| description | String | Yes | The payment purpose | admissions payment |
| amount | Integer | Yes | Payment amount in the lowest denomination of client currency (eg. pence) | 100 |
| country | String | No | Country code in the ISO 3166-1 alpha-2 format | GB |
| payor_first_name | String | No | The payor's first name | John |
| payor_last_name | String | No | The payor's last name | Smith |
| address_line_1 | String | No | The first line of the payor's address | 1 Test House |
| address_line_2 | String | No | The second line of the payor's address | Test Street |
| city | String | No | The payor's city | London |
| state | String | No | The payor's state | unsure |
| postal_code | String | No | The payor's postal_code | LL33 0SN |
| custom_data | Object | No | Any additional data used to identify the transaction |
{
"additionalProp1": "prop",
"additionalProp2": "PROP",
"additionalProp3": "pRoP",
}
|
| return_url | String | No | An URL used to redirect the payor after completing the payment | https://your-site.com |
| notification_url | String | No | An URL used by Esenda to send a POST request with a transaction status update | https://webhooks.com |
| link_expiry_date | String | No | An expiry date is assigned to a payment link, rendering the link unusable once the expiry date has passed. If no expiry date is set, the link will automatically expire 48 hours after its creation. | 2024-07-24 |
Payload Example
{
"shortcode": "example_school",
"email_address": "[email protected]",
"description": "admissions payment",
"amount": 100, // lowest denomination of client currency (eg. pence)
"country": "GB", // ISO 3166-1 alpha-2
"payor_first_name": "John",
"payor_last_name": "Smith",
"address_line_1": "somestreet",
"address_line_2": "someplace",
"city": "London",
"state": "unsure",
"postal_code": "LL33 0SN",
"custom_data": {
"additionalProp1": "prop",
"additionalProp2": "PROP",
"additionalProp3": "pRoP",
},
"return_url": "https://your-site.com", // user sent here post payment
"notification_url": "https://webhooks.com", // webhook endpoint
"link_expiry_date": "2024-07-24"
}
You will receive one of the following responses. You will need to store the request_id and redirect the user to the payment_link.
200 Response
{
"payment_link": "https://epay.esenda.com/shortcode/b768c458-1f83-41c9-8147-6ac4ad153dfa",
"request_id": "6c6b77ba-fc4a-4a18-a1d9-5b2cdc2f8cdf"
}
400 Response
{
"error": "Bad request",
"message": "No organisation with shortcode {GBC-1234}"
}
Once a user makes a payment using the one-time link, if a return_url
was included in your request, we'll redirect the user to that URL. We'll also add two
query parameters to the URL: referenceId (which is a UUID payment
identifier) and paymentType (which indicates the payment method used
and can be either open_banking, card or bank_transfer). For example, the resulting URL
might look
like this:
https://your-site.com?referenceId=b768c458-1f83-41c9-8147-6ac4ad153dfa&paymentType=card
Multi Payment request
Once authenticated, you can make a request to start multiple new transaction within Esenda. This will generate a collection of payment links which you will use to redirect the user to and provide you with a request ID so that you can track the status of the payment.
https://api.esenda.com/v1/partner/payments/{shortcode}/payment-links
https://api-dev.esenda.com/v1/partner/payments/{shortcode}/payment-links
POST
/v1/partner/payments/{shortcode}/payment-links
Headers
Accept-Language: <LANGUAGE> (optional, default en-GB)
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
You will need to pass the parameters below, within one or many objects, inside of an array for the request's payload.
| Parameter name | Type | Required | Description | Example |
|---|---|---|---|---|
| shortcode | String | Yes | Your Esenda identifier | example_school |
| email_address | String | Yes | The payer's email address | [email protected] |
| reference | String | Yes | The payment reference. Must be unqiue. Max 18 ASCII chars | abc123 |
| description | String | Yes | The payment purpose | admissions payment |
| amount | Integer | Yes | Payment amount in the lowest denomination of client currency (eg. pence) | 100 |
| country | String | No | Country code in the ISO 3166-1 alpha-2 format | GB |
| payor_first_name | String | No | The payor's first name | John |
| payor_last_name | String | No | The payor's last name | Smith |
| address_line_1 | String | No | The first line of the payor's address | 1 Test House |
| address_line_2 | String | No | The second line of the payor's address | Test Street |
| city | String | No | The payor's city | London |
| state | String | No | The payor's state | unsure |
| postal_code | String | No | The payor's postal_code | LL33 0SN |
| custom_data | Object | No | Any additional data used to identify the transaction |
{
"additionalProp1": "prop",
"additionalProp2": "PROP",
"additionalProp3": "pRoP",
}
|
| return_url | String | No | An URL used to redirect the payor after completing the payment | https://your-site.com |
| notification_url | String | No | An URL used by Esenda to send a POST request with a transaction status update | https://webhooks.com |
| link_expiry_date | String | No | An expiry date is assigned to a payment link, rendering the link unusable once the expiry date has passed. If no expiry date is set, the link will automatically expire 48 hours after its creation. | 2024-07-24 |
Payload Example
[{
"shortcode": "example_school",
"email_address": "[email protected]",
"reference": "abc",
"description": "admissions payment",
"amount": 100, // lowest denomination of client currency (eg. pence)
"country": "GB", // ISO 3166-1 alpha-2
"payor_first_name": "John",
"payor_last_name": "Smith",
"address_line_1": "somestreet",
"address_line_2": "someplace",
"city": "London",
"state": "unsure",
"postal_code": "LL33 0SN",
"custom_data": {
"additionalProp1": "prop",
"additionalProp2": "PROP",
"additionalProp3": "pRoP",
},
"return_url": "https://your-site.com", // user sent here post payment
"notification_url": "https://webhooks.com", // webhook endpoint
"link_expiry_date": "2024-07-26"
}]
You will receive one of the following responses. You will need to store the request_id and redirect the user to the payment_link.
200 Response
{
"abc": {
"payment_link": "https://epay.esenda.com/shortcode/b768c458-1f83-41c9-8147-6ac4ad153dfa",
"request_id": "6c6b77ba-fc4a-4a18-a1d9-5b2cdc2f8cdf"
}
}
400 Response
{
"error": "Bad request",
"message": "No organisation with shortcode {GBC-1234}"
}
Once a user makes a payment using the one-time link, if a return_url
was included in your request, we'll redirect the user to that URL. We'll also add two
query parameters to the URL: referenceId (which is a UUID payment
identifier) and paymentType (which indicates the payment method used
and can be either open_banking, card or bank_transfer). For example, the resulting URL
might look
like this:
https://your-site.com?referenceId=b768c458-1f83-41c9-8147-6ac4ad153dfa&paymentType=card
Payment webhooks
If a webhook URL is provided in the payload for the payment request, Esenda will trigger a webhook, either:
- Whenever a transaction is updated (processing, accepted)
- Whenever a translation hits a terminal state (success, failed, refunded, cancelled)
When Esenda sends a webhook to your webhook URL, it expects to receive a response with a status code of 200 - OK. If it doesn't receive this response, Esenda will retry sending the webhook 4 more times. If no response is received after the 5 attempts to send the webhook, we will stop further attempts.
An example of the webhook message:
Webhook Response
{
"created_at":"2024-01-23 14:42:19.999462",
"data": {
"payment_id":"2d6586da-b5ad-4417-901a-c499dbdac774",
"payment_method": "card",
"status": "success",
"payment_reference": "reference",
"request_id": "6c6b77ba-fc4a-4a18-a1d9-5b2cdc2f8cdf"
},
"event_type":"payment.updated",
"id":"36bd6eea-9bad-4101-b3de-35389d348f9f",
"shortcode": "test-school"
}
| Parameter name | Description | Example |
|---|---|---|
| created_at | Created at timestamp | 2024-01-23 14:42:19.999462 |
| data | Object containing the payment id (UUID payment identifier) and the payment status |
{
"payment_id":"2d6586da-b5ad-4417-901a-c499dbdac774",
"payment_method": "card",
"status": "success",
"payment_reference": "reference",
"request_id": "6c6b77ba-fc4a-4a18-a1d9-5b2cdc2f8cdf"
},
|
| event_type | The webhook type | payment.updated |
| id | Unique webhook identifier (UUID) | 36bd6eea-9bad-4101-b3de-35389d348f9f |
| shortcode | Shortcode of the organisation that the payment is linked to | test-school |
When you receive a webhook from Esenda, it will include a header value called hmac_signature. This value can be used to verify that the webhook was sent by Esenda. The hmac_signature is encrypted using a Secure Hash Algorithm 512 (SHA-512), with the secret_key being your client ID and the webhook message. The encoded message uses UTF-8 as the default encoding.
Webhook Headers
Headers
Content-Type: application/json
X-Hmac-Signature: <hmac_signature>
Payment status information
The payment status that is shown after making transactions and returned via webhooks can be interpreted as below.
| Payment status | Key | Description | Payment types this status can occur for |
|---|---|---|---|
| Success | success | The payment was made successfully. This is a terminal status. | All |
| Failed | failed | The payment failed. This is a terminal status. | All |
| Cancelled | cancelled | The payment was cancelled. The payment was not completed. This is a terminal status. | Card |
| Refunded | refunded | The payment was a refund of an earlier payment. This is a terminal status. | All |
| Accepted | accepted | The payment has been accepted by the bank. The payment will update to be successful within two hours unless a fraud check is triggered. | Open banking |
| Processing | processing | The payment is still processing. This can take up to two hours for open banking payments and can take up to several days for bank transfers. | All |
Payments list
To retrieve a list of payments from a specific date, call the following endpoint:
GET
/v1/partner/payments/{shortcode}?since=2024-06-14&page=2&per_page=3
Headers
Accept-Language: <LANGUAGE> (optional, default en-GB)
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
You will need to pass the following query parameters to the request.
| Parameter name | Type | Required | Description | Example |
|---|---|---|---|---|
| shortcode | String | Yes | Your Esenda identifier | example_school |
| since | String | Yes | A string in the format YYYY-MM-DD, representing the start date for querying payments. | 2024-06-12 |
| page | Integer | Optional. Default: 1 | Specifies the page number of the paginated results to retrieve. | 2 |
| per_page | Integer | Optional. Default: 10. Max: 100 | Limits the number of payments returned per page. | 3 |
Example response:
Request Response
{
"shortcode": "test-school",
"total_payments": 9,
"total_pages": 3,
"current_page": 2,
"next": "?since=2024-06-12&page=3&per_page=3",
"previous": "?since=2024-06-12&page=1&per_page=3",
"data": [
{
"payment_id": "cb03882b-25a0-45e8-b6f1-aa5cd303f88d",
"request_id": "6c6b77ba-fc4a-4a18-a1d9-5b2cdc2f8cdf",
"payment_method": "open_banking",
"status": "failed",
"date_created": "2024-03-15 13:33:09.131483"
},
{
"payment_id": "7447faf5-40e4-44fb-b415-9dda7c5b1063",
"request_id": "f7266fc5-26da-40de-9879-f4dfcc980b63",
"payment_method": "card",
"status": "success",
"date_created": "2024-05-29 13:33:09.158329"
},
],
}
| Parameter name | Description | Example |
|---|---|---|
| shortcode | Shortcode of the organisation that the payment is linked to | test-school |
| total_payments | The total number of payments returned in the data object list | 1 |
| total_pages | The total number of pages based on the per_page parameter and the total number of payments. | 3 |
| current_page (optional) | The current page number of the paginated results returned in the response. | 2 |
| next (optional) | Contains query parameters for retrieving the next page of results. | ?since=2024-06-12&page=3&per_page=3 |
| previous (optional) | Contains query parameters for retrieving the previous page of results. | ?since=2024-06-12&page=1&per_page=3 |
| data | Object containing the list of payments |
[
{
"payment_id": "cb03882b-25a0-45e8-b6f1-aa5cd303f88d",
"request_id": "6c6b77ba-fc4a-4a18-a1d9-5b2cdc2f8cdf",
"payment_method": "open_banking",
"status": "created",
"date_created": "2024-03-15 13:33:09.131483",
"date_updated": "2024-03-15 13:33:09.131483"
},
]
|
Test Cards
You can use any of the card details below to process your test transaction.
Test address details
Use these address details for the fraud prevention checks:
Address Line 1: 88
Postcode: 412
Test 3D Secure password & response
If 3-D Secure is active on your account you will also be required to enter a password to complete the process.
Password (case sensitive): password
| Card type | Card number | CVV |
|---|---|---|
| Visa Credit | 4929000000006 | 123 |
| Visa Corporate | 4484000000002 | 123 |
| Visa Debit | 4462000000000003 | 123 |
| MasterCard Credit | 5186150660000009 | 123 |
| MasterCard Debit | 5185690060000001 | 123 |
| American Express | 374200000000004 | 1234 |
| Diners Club / Discover | 36000000000008 | 123 |
| JCB | 3569990000000009 | 123 |