Payment API

Payment API v1

The Payment API can be used to initialize web payments using the Enviso Payment Widget and verify if the payment was successful.

Principles

The Payment API is a REST API solution and attempts to conform to the RESTful design principles.

Important to know

All connections must be made over HTTPS, not HTTP.
All the query parameters are to be passed in lower case.
All date and time data in the API request passed/response received are in the UTC-00:00 format.
- yyyy-MM-ddTHH:mm:ssZ (Eg.: 1994-11-05T13:15:30Z)

Response status codes

The following HTTP status codes are used within the Payment API.

Code	Description
200	OK The request was successful, resulting in everything working as expected.
201	Created The request was successful, resulting in the creation of new resource.
202	Accepted The server has successful received the request and will start processing it.
400	Bad Request The server was unable to understand the request. The request is most likely malformed or a mandatory parameter is missing. Tip It is recommended to make modifications in the current request and repeat the request.
401	Unauthorised The request has not been processed because it lacks valid authentication credentials for the target resource. If the request included valid authentication credentials, then the 401 response indicates that authorisation has been refused for the target resource.
403	Forbidden The server understood the request but refuses to authorize it. This probably means you did not pass the API Key (x-api-key) in your request headers.
404	Not Found The requested resource does not exist. However, the resource may be available in the future. Subsequent requests by the client are permissible.
410	Gone The received request is already processed.
422	Unprocessable Entity The server understands the content type of the request entity, but was unable to process the contained instructions. For example, this error condition may occur if validation rules to process the entity failed.
429	Too Many Requests The server received too many request in a given amount of time.
500	Internal Server Error The server encountered an unexpected error, which prevented it from fulfilling the request.
502	Bad Gateway The server, while acting as a gateway or proxy, received an invalid response from the upstream server.
503	Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Request headers

The request and response data is sent as JSON.
- content-type: application/json
The API Key is required to be passed in the HTTP Request Headers.
- x-api-key: your_api_key
The Tenant Key is required to be passed in the HTTP Request Headers.
- x-tenantsecretkey: your_tenant_key

Warning

All the Requests made towards the Payment API must have a correct API Key and Tenant Key in the header.

Integration

Integration Summary

The following sequence schema shows a high-level overview of the payment process when integrating Enviso Pay.

Refund Integration Summary

The following sequence schema shows a high-level overview of the refund process when integrating Enviso Pay.

Pay by link Integration Summary

The following sequence schema shows a high-level overview of the Pay by Link process when integrating Enviso Pay:

Settings

It is possible to enable automatic retries in case a payment fails when integrating Enviso Pay using the 'Drop-in'.

The setting is located in the Enviso Admin > Settings > tab Enviso Pay.

Note

The option to retry payment is disabled by default.

Authentication

Contact Vintia support to obtain the Tenant key, API key and API secret key, which you need to start communicating to the API.

Once you have the needed information, you need to authenticate first before you'll be able to call the Payment API.

For this, you'll need to use the Authentication API.

Going live

When going from the staging environment to the production environment:

Use the production environment API key and API secret key of the Authentication API.
Use the production environment API Key and Tenant key of the Payment API.
Note
Contact GANTNER support to get your production environment keys of the Authentication API and Payment API.
Change the base URL from the staging environment to the production environment.
- Production environment: https://api.enviso.io/paymentapi
- Staging environment: https://api.staging-enviso.io/paymentapi

Common models

Amount

Details

Property	Type	Nullable	Description
currency	string	false	The amount of the payment (as a floating point number).
value	number	false	The currency code of the payment.

json

{
  "currency": "string",
  "value": number
}

Status

Details

Property	Type	Nullable	Description
tentative	bool	false	Defines whether or not the payment is in the final status.
value	string	false	The payment status can be: open requested success partialsuccess failed cancelled For open and requested, the payment is awaiting action from the end user. Success and failed are reached after feedback from the payment provider. PartialSuccess means that the payment has been partially refunded or not yet fully paid. Cancelled usually means the payment has expired (by default, after 60 minutes). For internal Enviso orders, the payment is also cancelled when the order is cancelled.

Property

Type

Nullable

Description

tentative

bool

false

Defines whether or not the payment is in the final status.

value

string

false

The payment status can be:

open
requested
success
partialsuccess
failed
cancelled

For open and requested, the payment is awaiting action from the end user.

Success and failed are reached after feedback from the payment provider.

PartialSuccess means that the payment has been partially refunded or not yet fully paid.

Cancelled usually means the payment has expired (by default, after 60 minutes). For internal Enviso orders, the payment is also cancelled when the order is cancelled.

json

{
  "tentative": bool,
  "value": "string"
}

Topic

Details

Property	Type	Nullable	Description
type	bool	false	The topic to which the payment is linked. For the moment only one topic is supported - order. Note This is only filled for internal Enviso payments and not for third-party payments.
id	string	false	The unique id/reference of the topic to which the payment is linked, for example, order ID. Note This is only filled for internal Enviso payments and not for third-party payments.

json

{
  "type": "bool",
  "id": "string"
}

Refund

Details

Property	Type	Nullable	Description
refundReference	string	false	An identifier for this refund. Guaranteed to be unique among all refunds for a particular payment. Useful for the postback integration to correlate the feedback to this refund. Only included if the payment will be refunded (not just cancelled). Note This is only filled for internal Enviso payments and not for third-party payments.
amount	Refer Amount
status	string	false	Equivalent to the payment status (refer the model Status), only without a `tentative`-flag because a refund doesn't have a finalized state.
createdDate	string (date)	false	The date and time the refund was created.

json

{
	"refundReference": "string",
	"amount": {
		"currency": "string",
		"value": number
	},
	"status": "string",
	"createdDate": "datetime"
}

Payments

Initiate web payment

Parameters

Parameter	Type	Required	Description
amount	Number	Yes	The amount of this payment, as a floating-point number. Eg: 10.23 Note The currency is determined by the tenant settings in Enviso.
originUrl	String	Yes	The URL of the web origin where the web payment is taking place. It is required for security reasons. Eg: https://my-webshop.com (not: http://mywebshop.com/tickets/pay.html?...) Note The origin does not include any path or query string.
returnUrl	String	Yes	The URL of the page (including path + query string) where the visitor should be redirected, after completing the payment with a payment method that involves redirects. Eg: https://my-webshop.com/tickets/paymentcomplete.html
countryCode	String	Yes	The ISO 3166 2-letter country code of the person who is making the payment. This determines the available payment methods. Eg: BE
language	String	Yes	The ISO 639 2-letter language code of the preferred language of the person who is making the payment. This will result in the proper localization of the Payment widget. Eg: nl
email	String	No (but recommended)	The e-mail address of the person who is making the payment. It is required by some payment methods. Eg: someshopper@gmail.com
postbackUrl	String	Yes	An https endpoint pointing to the integrator's web server, to which Enviso Pay can postback the final result of the payment (using http POST). Eg: https://my-webshop.com/envisopayresult
expiresOn	String (date)	No	A DateTime (in UTC) that indicates when the payment expires. If not specified, it is 2 days from the request. An expired payment cannot be completed. If authorization of the payment happens beyond this time, it will automatically be refunded. It is recommended to use an ISO 8601 format to pass the date. Eg: 2021-06-21T11:25:47.000Z

Response

Success response code: 200 OK

Response details:

Parameter	Type	Description
reference	string	The unique payment reference (ID) in Enviso.
sessionToken	string	The token that is used to initialize the Enviso Payment widget

Request

var client = new RestClient("https://api.staging-enviso.io/paymentapi/v1/payments/web");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
request.AddParameter("application/json", "{\"amount\":0,\"originUrl\":\"string\",\"returnUrl\":\"string\",\"countryCode\":\"string\",\"language\":\"string\",\"email\":\"string\",\"postbackUrl\":\"string\",\"expiresOn\":\"2019-08-24T14:15:22Z\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.post("https://api.staging-enviso.io/paymentapi/v1/payments/web")
  .header("Content-Type", "application/json")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .body("{\"amount\":0,\"originUrl\":\"string\",\"returnUrl\":\"string\",\"countryCode\":\"string\",\"language\":\"string\",\"email\":\"string\",\"postbackUrl\":\"string\",\"expiresOn\":\"2019-08-24T14:15:22Z\"}")
  .asString();

Request

const data = JSON.stringify({
  "amount": 0,
  "originUrl": "string",
  "returnUrl": "string",
  "countryCode": "string",
  "language": "string",
  "email": "string",
  "postbackUrl": "string",
  "expiresOn": "2019-08-24T14:15:22Z"
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.staging-enviso.io/paymentapi/v1/payments/web");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io/paymentapi")

payload = "{\"amount\":0,\"originUrl\":\"string\",\"returnUrl\":\"string\",\"countryCode\":\"string\",\"language\":\"string\",\"email\":\"string\",\"postbackUrl\":\"string\",\"expiresOn\":\"2019-08-24T14:15:22Z\"}"

headers = {
    'Content-Type': "application/json",
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("POST", "/v1/payments/web", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
   "paymentReference": "string",
   "sessionToken": "string"
}

json

{
   "errors": [
      {
         "code": 0,
         "message": "string",
         "propertyName": "string",
         "trace": "string"
      }
   ]
}

'Pay by Link' Payment

Parameters

Parameter	Type	Required	Description
amount	Number	Yes	The amount of this payment, as a floating-point number. Eg: 10.23 Note The currency is determined by the tenant settings in Enviso.
originUrl	String	Yes	The URL of the web origin where the web payment is taking place. It is required for security reasons. Eg: https://my-webshop.com (not: http://mywebshop.com/tickets/pay.html?...) Note The origin does not include any path or query string.
returnUrl	String	Yes	Filter offers by a certain field. For now, it is only possible to filter on offer name. Eg: https://my-webshop.com/tickets/paymentcomplete.html
countryCode	String	Yes	The ISO 639 2-letter language code of the preferred language of the person who is making the payment. This will result in the proper localization of the Payment widget. Eg: BE
language	String	Yes	The ISO 639 2-letter language code of the preferred language of the person who is making the payment. This will result in the proper localization of the Payment widget. Eg: nl
email	String	false	The e-mail address of the person who is making the payment. It is required by some payment methods. Eg: someshopper@gmail.com Note We recommend to use the `email` parameter.
postbackUrl	String	Yes	An https endpoint pointing to the integrator's web server, to which Enviso Pay can postback the final result of the payment (using http POST). Eg: https://my-webshop.com/envisopayresult
expiresOn	String (date)	No	A DateTime (in UTC) that indicates when the payment expires. The expiration date must not exceed 70 days from the current date. If not specified, it is 2 days from the request. An expired payment cannot be completed. If authorization of the payment happens beyond this time, it will automatically be refunded. We recommend using an ISO 8601 format to pass the date. Eg: 2021-06-21T11:25:47.000Z

Response

Success response code: 200 OK

Response details:

Parameter	Type	Description
paymentReference	string	The unique payment reference (ID) in Enviso.
expiresOn	string (date)	A datetime (in UTC) that indicates when the payment expires.
paymentLink.url	string	The URL to the payment provider to pay the payment.

Possible error codes:

Code	Message
1001	`field_name` is required.
1003	`field_name` must not be empty.
1005	The provided value for `field_name` is not valid.
1110	Failed to initiate the payment.

Request

var client = new RestClient("https://api.staging-enviso.io/paymentapi/v1/payments/weblink");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
request.AddParameter("application/json", "{\"amount\":0,\"originUrl\":\"string\",\"returnUrl\":\"string\",\"countryCode\":\"string\",\"language\":\"string\",\"email\":\"string\",\"postbackUrl\":\"string\",\"expiresOn\":\"2019-08-24T14:15:22Z\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.post("https://api.staging-enviso.io/paymentapi/v1/payments/weblink")
  .header("Content-Type", "application/json")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .body("{\"amount\":0,\"originUrl\":\"string\",\"returnUrl\":\"string\",\"countryCode\":\"string\",\"language\":\"string\",\"email\":\"string\",\"postbackUrl\":\"string\",\"expiresOn\":\"2019-08-24T14:15:22Z\"}")
  .asString();

Request

const data = JSON.stringify({
  "amount": 0,
  "originUrl": "string",
  "returnUrl": "string",
  "countryCode": "string",
  "language": "string",
  "email": "string",
  "postbackUrl": "string",
  "expiresOn": "2019-08-24T14:15:22Z"
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.staging-enviso.io/paymentapi/v1/payments/weblink");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io/paymentapi")

payload = "{\"amount\":0,\"originUrl\":\"string\",\"returnUrl\":\"string\",\"countryCode\":\"string\",\"language\":\"string\",\"email\":\"string\",\"postbackUrl\":\"string\",\"expiresOn\":\"2019-08-24T14:15:22Z\"}"

headers = {
    'Content-Type': "application/json",
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("POST", "/v1/payments/weblink", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

json

{
	"paymentReference": "string",
	"expiresOn": "datetime",
	"paymentLinkUrl": "string"
}

json

{
    "errors": [{
        "message": "string",
        "code": "number"
    }]
}

Get payment

Response

Success response code: 200 OK

Response details:

Parameter	Type	Description
id	string	The unique payment reference.
amount	Refer model Amount
topic	Refer model Topic
status	Refer model Status
pspReference	string	The unique payment reference within the payment provider. Warning Obsolete Use the pspReference of split payments, in case of multiple split payments, this will only show the first one.
paymentMethod	string	The payment method that was used during the payment process Eg: BCMC, Visa, iDEAL, etc. Only available after the payment method was chosen & submitted by the end user. Warning Obsolete Use the paymentMethod of split payments, in case of multiple split payments, this will have the value 'multiple'.
postbackUrl	string	The URL is to be used for pushing notifications related to the payment. Warning This is only filled for third-party payments and not for internal Enviso payments.
lastNotificationDate	string (date)	The date and time of the last notification that updated the payment. Warning Obsolete This is no longer always up-to-date, as it is specific to Adyen.
lastModified	string (date)	The date and time that the payment was last modified.
expiresOn	string (date)	The date and time when the payment expires.
paymentLinkDetails.url	string	The payment link url of the payment.
refunds	Refer model Refund
splitPayments.id	string	The unique payment reference id.
splitPayments.paymentMethod	string	The payment method that was used during the payment process (for example: bcmc, visa, ideal, etc.). Only available after the payment method was chosen & submitted by the end user.
splitPayments.amount	Refer model Amount
splitPayments.status	Refer model Status
splitPayments.refunds	Refer model Refund

Request

var client = new RestClient("https://api.staging-enviso.io/paymentapi/v1/payments/string");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.get("https://api.staging-enviso.io/paymentapi/v1/payments/string")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .asString();

Request

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.staging-enviso.io/paymentapi/v1/payments/string");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io/paymentapi")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("GET", "/v1/payments/string", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
	"id": "string",
	"amount": {
		"currency": "string",
		"value": number
	},
	"topic": {
		"type": "string", 
		"id": number
	},
	"status": {
		"tentative": bool,
		"value": "string"
	},
	"pspReference": "string",
	"paymentMethod": "string",
	"postbackUrl": "string",
	"lastNotificationDate": "datetime",
	"lastModified": "datetime",
	"expiresOn": "datetime",
	"paymentLinkDetails": {
		"url": "string"
	},
	"refunds": [{
		"refundReference": "string",
		"amount": {
			"currency": "string",
			"value": number
		},
		"status": "string",
		"createdDate": "datetime"
	}],
	"splitPayments": [{
		"id": "string",
		"paymentMethod": "string",
		"amount": {
			"currency": "string",
			"value": number
		},
		"status": {
			"tenantive": "string",
			"value": "string"
		},
		"refunds": [{
			"refundReference": "string",
			"amount": {
				"currency": "string",
				"value": number
			},
			"status": "string",
			"createdDate": "datetime"
		}]
	}]
}

json

{
   "errors": [
      {
         "code": 0,
         "message": "string",
         "propertyName": "string",
         "trace": "string"
      }
   ]
}

Get payments in batch

Query parameter

Parameter	Type	Required	Description
ids	String	Yes	The amount of this payment, as a floating-point number. Eg: 10.23 Note The currency is determined by the tenant settings in Enviso.

Parameter

Type

Required

Description

ids

String

Yes

The amount of this payment, as a floating-point number.

Eg: 10.23

Note

The currency is determined by the tenant settings in Enviso.

Parameter	Type	Required	Description
ids	String	Yes	List of payment references (split by a comma ','). Eg: 12D14F8489404BB0B292E9FAC5841C87,345395C8BF66452AAA4138C498F53D6F Note A maximum of 50 payment references are supported. If more than 50 are passed, then the first 50 will be returned.

Parameter

Type

Required

Description

ids

String

Yes

List of payment references (split by a comma ',').

Eg: 12D14F8489404BB0B292E9FAC5841C87,345395C8BF66452AAA4138C498F53D6F

Note

A maximum of 50 payment references are supported.

If more than 50 are passed, then the first 50 will be returned.

Response

Success response code: 200 OK

Response details:

Parameter	Description
payments	Array of payment objects as described in Get payment.

Request

var client = new RestClient("https://api.staging-enviso.io/paymentapi/v1/payments");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.get("https://api.staging-enviso.io/paymentapi/v1/payments")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .asString();

Request

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.staging-enviso.io/paymentapi/v1/payments");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io/paymentapi")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("GET", "/v1/payments", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

json

{
	"payments":[{
		"id": "string",
		"amount": {
			"currency": "string",
			"value": number
		},
		"topic": {
			"type": "string", 
			"id": number
		},
		"status": {
			"tentative": bool,
			"value": "string"
		},
		"pspReference": "string",
		"paymentMethod": "string",
		"postbackUrl": "string",
		"lastNotificationDate": "datetime",
		"lastModified": "datetime",
		"expiresOn": "datetime",
		"paymentLinkDetails": {
			"url": "string"
		},
		"refunds": [{
			"refundReference": "string",
			"amount": {
				"currency": "string",
				"value": number
			},
			"status": "string",
			"createdDate": "datetime"
		}],
		"splitPayments": [{
			"id": "string",
			"paymentMethod": "string",
			"amount": {
				"currency": "string",
				"value": number
			},
			"status": {
				"tenantive": "string",
				"value": "string"
			},
			"refunds": [{
				"refundReference": "string",
				"amount": {
					"currency": "string",
					"value": number
				},
				"status": "string",
				"createdDate": "datetime"
			}]
		}]
	}]
}

{
	"errors": [{
		"message": "string",
		"code": "number"
	}]
}

Cancel ( or refund)

Request details

Parameter	Type	Description
postbackUrl	string	The URL for the postback integration (only relevant when the payment will be refunded and not just cancelled).
reason	string	The reason why the payment should be cancelled.

Response

Success response code:

202 Accepted
204 No Content

Response details:

Parameter	Type	Description
refundReference	string	An identifier for this refund. Guaranteed to be unique among all refunds for a particular payment.Useful for the postback integration to correlate the feedback to this refund. Only included if the payment will be refunded (not just cancelled). Warning Obsolete Use the refundReference for each split refund, in case of multiple splits, this will only show the first one.
refunds	Refer model Refund

Parameter

Type

Description

refundReference

string

An identifier for this refund. Guaranteed to be unique among all refunds for a particular payment.Useful for the postback integration to correlate the feedback to this refund.

Only included if the payment will be refunded (not just cancelled).

Warning

Obsolete

Use the refundReference for each split refund, in case of multiple splits, this will only show the first one.

refunds

Refer model Refund

Request

var client = new RestClient("https://api.staging-enviso.io/paymentapi/v1/payments/string/cancel");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
request.AddParameter("application/json", "{\"postbackUrl\":\"string\",\"reason\":\"string\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.put("https://api.staging-enviso.io/paymentapi/v1/payments/string/cancel")
  .header("Content-Type", "application/json")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .body("{\"postbackUrl\":\"string\",\"reason\":\"string\"}")
  .asString();

Request

const data = JSON.stringify({
  "postbackUrl": "string",
  "reason": "string"
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.staging-enviso.io/paymentapi/v1/payments/string/cancel");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("https://api.staging-enviso.io/paymentapi")

payload = "{\"postbackUrl\":\"string\",\"reason\":\"string\"}"

headers = {
    'Content-Type': "application/json",
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("PUT", "/v1/payments/string/cancel", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

json

{
    "refundReference": "string",
	"refunds": [{
		"refundReference": "string",
		"createdAt": "datetime",
		"amount": {
			"currency": "string",
			"value": number
		}
	}]
}

{
	"errors": [{
		"message": "string",
		"code": "number"
	}]
}

Refunds

Initiate full refund

Parameter

Parameter	Type	Required	Description
postbackUrl	string	Yes	The URL for the postback integration. Refer Postback integration

Type

Required

Description

postbackUrl

string

Yes

The URL for the postback integration.

Refer Postback integration

Response

Success response code: 202 Accepted

Response details:

Parameter	Type	Description
refundReference	string	An identifier for this refund. It is guaranteed to be unique among all refunds for a particular payment. It's useful for the postback integration to correlate the feedback to this refund. Only included if the payment will be refunded (not just cancelled). Warning Obsolete Use the refundReference for each split refund, in case of multiple splits, this will only show the first one.
refunds	Refer model Refund

Parameter

Type

Description

refundReference

string

An identifier for this refund. It is guaranteed to be unique among all refunds for a particular payment. It's useful for the postback integration to correlate the feedback to this refund.

Only included if the payment will be refunded (not just cancelled).

Warning

Obsolete

Use the refundReference for each split refund, in case of multiple splits, this will only show the first one.

refunds

Refer model Refund

Request

var client = new RestClient("https://api.staging-enviso.io/paymentapi/v1/payments/string/refund");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
request.AddParameter("application/json", "{\"postbackUrl\":\"string\",\"amount\":0}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.put("https://api.staging-enviso.io/paymentapi/v1/payments/string/refund")
  .header("Content-Type", "application/json")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .body("{\"postbackUrl\":\"string\",\"amount\":0}")
  .asString();

Request

const data = JSON.stringify({
  "postbackUrl": "string",
  "amount": 0
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.staging-enviso.io/paymentapi/v1/payments/string/refund");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io")

payload = "{\"postbackUrl\":\"string\",\"amount\":0}"

headers = {
    'Content-Type': "application/json",
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("PUT", "/v1/payments/string/refund", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
    "refundReference": "string",
	"refunds": [{
		"refundReference": "string",
		"createdAt": "datetime",
		"amount": {
			"currency": "string",
			"value": number
		}
	}]
}

{
    "errors": [{
        "message": "string",
        "code": "number"
    }]
}

Initiate partial refund

Parameters

Parameter	Type	Description
postbackUrl	string	The URL for the postback integration. Refer Postback integration
amount	number	The amount to refund as a floating-point number.

Response

Success response code: 202 Accepted

Response details:

Parameter	Type	Description
refundReference	string	An identifier for this refund. Guaranteed to be unique among all refunds for a particular payment.Useful for the postback integration to correlate the feedback to this refund. Only included if the payment will be refunded (not just cancelled). Warning Obsolete Use the refundReference for each split refund, in case of multiple splits, this will only show the first one.
refunds	Refer model Refund

Parameter

Type

Description

refundReference

string

An identifier for this refund. Guaranteed to be unique among all refunds for a particular payment.Useful for the postback integration to correlate the feedback to this refund.

Only included if the payment will be refunded (not just cancelled).

Warning

Obsolete

Use the refundReference for each split refund, in case of multiple splits, this will only show the first one.

refunds

Refer model Refund

Request

var client = new RestClient("https://api.staging-enviso.io/paymentapi/v1/payments/string/refunds");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
request.AddParameter("application/json", "{\"postbackUrl\":\"string\",\"amount\":0}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

HttpResponse<String> response = Unirest.post("https://api.staging-enviso.io/paymentapi/v1/payments/string/refunds")
  .header("Content-Type", "application/json")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .body("{\"postbackUrl\":\"string\",\"amount\":0}")
  .asString();

Request

const data = JSON.stringify({
  "postbackUrl": "string",
  "amount": 0
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.staging-enviso.io/paymentapi/v1/payments/string/refunds");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);

Request

import http.client

conn = http.client.HTTPSConnection("api.staging-enviso.io")

payload = "{\"postbackUrl\":\"string\",\"amount\":0}"

headers = {
    'Content-Type': "application/json",
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("POST", "/v1/payments/string/refunds", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
    "refundReference": "string",
	"refunds": [{
		"refundReference": "string",
		"createdAt": "datetime",
		"amount": {
			"currency": "string",
			"value": number
		}
	}]
}

{
    "errors": [{
        "message": "string",
        "code": "number"
    }]
}

Postback integration

When initializing a payment/refund, a postbackUrl is passed. This is an HTTPS endpoint on the calling system, to which the Enviso Pay system can post the authorization result of the payment.

Payments (Payment postback)

Parameters

Parameter	Type	Description
paymentReference	string	The identification of the payment, as received upon initializing the payment.
isSuccess	boolean	Indicates whether the payment was processed successfully.
paymentMethod	string	The payment method used to complete the payment.
reason	string	In case of non-successful payment, this property is present and contains an error message detailing the failure.

Request

{
    "paymentReference": "string",
    "isSuccess": boolean,
    "paymentMethod": "string",
    "reason": "string"
}

Refunds

Parameters

Parameter	Type	Description
paymentReference	string	The identification of the payment, as received upon initializing the payment.
refundReference	string	The identification of the refund, as received upon initializing the refund.
refundAmount	decimal	The amount that was refunded.
isSuccess	boolean	Indicates whether the refund was processed successfully.
reason	string	In case of an unsuccessful refund, this property is present and contains an error message detailing the failure.

Request

{
	"paymentReference": "string",
	"refundReference": "string",
	"refundAmount": decimal,
	"isSuccess": boolean,
	"reason": "string"
}

Accept

To ensure that your server is properly accepting the Enviso Pay postbacks, we require you to acknowledge every postback.

Warning

The postback mechanism has a fixed timeout of 15 seconds. If no valid response is received within this time frame, we will retry the postback later (refer Delivery attempts).

When your server receives a postback:

Store the postback data in your database.
Acknowledge the postback with a successful (2xx - eg. 200 OK) HTTP status.
Apply your business logic to process the postback data.

Warning

Make sure that you acknowledge the postback before applying any business logic, because a breakage in your business logic could otherwise prevent important updates from reaching your system.

Delivery attempts

The Enviso Payment system will keep trying to deliver the final payment result until a successful response code is received (2xx), during a reasonable time frame.

Currently, the system will do a total of 20 attempts, over a time frame of maximum 5 minutes (depending on HTTP timeouts occur or not).

Note

Fault tolerance improvements

We are aware this might not be sufficient in certain scenarios and we are looking to increase this in an upcoming release of the Payment API.

In the meantime, if the final postback could not be received, due to a network outage or service outage at the side of the integrator, it is always possible to query the payment status via the API (Get payment endpoint).