API for payment requests

A payment request is a link which opens the payment window. You can insert the link into an email and send the email directly to customers. As such, you request a payment from them.

This section describes our API for payment requests. All functions, methods, input and output values are outlined here.

You can find our webservice for payment requests here: https://paymentrequest.api.epay.eu/v1/

How to read the documentation

Every description of a function consists of input and output fields. Input fields are all the fields the web service expects you to set as you call it. Mandatory fields must be entered - the rest can be empty values. The output fields are the ones returned by the web service.

The flow of a payment request

A payment request will normally pass through these four steps.

• Step 1: You create a payment request using createpaymentrequest.

Notice

To add forms to the payment request, you have to call createform first and attach the formid that's returned to the payment request by sending it as a parameter when you call createpaymentrequest.

• Step 2: You can send the payment request with sendpaymentrequest, or you can send the link that's returned from createpaymentrequest to the customer by other means.

• Step 3: The customer completes the payment.

• Step 4: The transaction ID of the payment (transactionid) is automatically connected to the ID of the payment request (paymentrequestid) if you use our payment window or send the link directly to the customer. You can use gettransaction to see all transactions carried out on the payment request.

If you use another means, you can use addtransaction to connect the transaction ID to the payment request ID.

Methods for paymentrequest

The following section describes the methods for managing payment requests.

createpaymentrequest

This is an overview of available parameters.

You'll find detailed specifications for each parameter under Specifications

You can find the API reference here: https://paymentrequest.api.epay.eu/v1/Operations.aspx?uri=createpaymentrequest

Input

Input	Values	Description	Mandatory
authentication.merchantnumber	Type: string	Your unique merchant number. You can find it on your merchant agreement.	Yes
authentication.password	Type: string	Your password. Find it on your ePay account.	Yes
language	Type: string	Indicate in which language you want to receive error messages.	No
localtimezone	Type: boolean	True = local time	No
paymentrequest.exactclosedate	Type: Datetime	Specify a closing date for the payment request.	No
paymentrequest.closeafterxpayments	Type: integer	Specify the number of payments to be completed before the payment request closes.	No
reference	Type: string	Reference to the payment request. It's a reference that you create and assign to the payment request	Yes
paymentrequest.parameters	Type: Parameters (PaymentRequest)	An object containing the attributes to the Payment Window.	Yes

Output

Output	Values	Description
paymentrequestid	Type: long	The unique number identifying the payment request.
key (paymentrequest)	Type: string	Key which is used for finding the payment request. This is a security measurement to avoid that payment requests can be found using only paymentrequestid.
link (paymentrequest)	Type: string	URL for the payment request
result	Type: boolean	See description of output values.
message	Type: string	If result is false, message will show a detailed error description.
reason	Type: enum
requestresponselogid	Type: long	This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.

getpaymentrequest

getpaymentrequest fetches information about a payment request based on paymentrequestid.

Input

Input	Type	Objecttype	Values	Description	Mandatory
merchantnumber	String	authentication		Your unique merchant number. You can find it on your merchant agreement.	Yes
password	String	authentication		Your password. Find it on your ePay account.	Yes
paymentrequestid	Long	paymentrequest		The unique number identifying the payment request.	Yes
language	String			Indicate in which language you want to receive error messages.	No
localtimezone	Boolean		True/false	True = local time	No

Output

Output	Type	Values	Description
closeafterxpayments (paymentrequest)	Integer		The number of payments that can be completed before the payment request will close.
exactclosedate (paymentrequest)	Datetime		The date when the payment request will close.
key (paymentrequest)	String		Key which is used for finding the payment request. This is a security measurement to avoid that payment requests can be found using only paymentrequestid.
link (paymentrequest)	String		URL for the payment request
reference	String		Reference to the payment request
status	Enum	1 = Open 2 = Closed 3 = Archived
parameters - click here to see all parameters (JSON body). The technical documentation for parameters is available here.
result	Boolean		See description of output values.
message	String		If result is false, message will show a detailed error description.
reason	Enum
requestresponselogid	Long		This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.

listpaymentrequest

listpaymentrequest fetches a list containing information about payment requests.

Input

Input	Type	Objecttype	Values	Description	Mandatory
merchantnumber	String	authentication		Your unique merchant number. You can find it on your merchant agreement.	Yes
password	String	authentication		Your password. Find it on your ePay account.	Yes
sorting	Enum	sorting	0 = ascending 1 = descending	State which sort order to use on the list, based on the date of creation.	No
exclusivestartkey	Long	paging		The paymentrequestid from which the fetch should start. Note: This is not included in the fetch.	No
pagesize	Integer	paging	20-100	The size of the list to be fetched.	No
language	String			Indicate in which language you want to receive error messages.	No
localtimezone	Boolean		True/false	True = local time	No

Output

Output	Type	Values	Description
paymentrequestid (paymentrequestlist)	Long		The unique number identifying the payment.
amount (transactionlist)	Inteher		The amount of the payment request
created (transactionlist)	Datetime		Date of creation
currency (transactionlist)	String		The currency of the payment request
numberoftransactions (transactionlist)	Integer		The number of transactions on the payment request
key (transactionlist)	String		Key which is used for finding the payment request. This is a security measurement to avoid that payment requests can be found using only paymentrequestid.
link (transactionlist)	String		URL for the payment request
reference (transactionlist)	String		Reference to the payment request
pagesize (paging)	Integer		The size of the fetched list
lastevaluatedkey	Long		The transactionid which was added most recently.
result	Boolean		See description of output values.
message	String		If result is false, message will show a detailed error description.
reason	Enum	0 = OK 1 = Error
requestresponselogid	Long		This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.

deletepaymentrequest

deletepaymentrequest deletes a payment request.

Input

Input	Type	Objecttype	Values	Description	Mandatory
merchantnumber	String	authentication		Your unique merchant number. You can find it on your merchant agreement.	Yes
password	String	authentication		Your password. Find it on your ePay account.	Yes
paymentrequestid	Long	paymentrequest		The unique number identifying the payment request.	Yes

Output

Output	Type	Values	Description
result	Boolean		See description of output values.
message	String		If result is false, message will show a detailed error description.
reason	Enum	0 = OK 1 = Error
requestresponselogid	Long		This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.

sendpaymentrequest

sendpaymentrequest sends the payment request.

Input

Input	Type	Objecttype	Values	Description	Mandatory
merchantnumber	String	authentication		Your unique merchant number. You can find it on your merchant agreement.	Yes
password	String	authentication		Your password. Find it on your ePay account	Yes
name	String	recipient		The name of the recipient of the payment request	Yes
emailaddress	String	recipient	Valid email	The recipient's email address	Yes
requester	String	email		Specify to add a "sent from" name in the email	No
comment	String	email		Specify to add a comments field in the email	No
name	String	replyto		Specify a name to be used when replying to the email with the payment request	No
emailaddress	String	replyto	Valid email	Specify an email address to be used when replying to the email with the payment request	No
paymentrequestid	Long	paymentrequest		The unique number identifying the payment request.	Yes

Output

Output	Type	Values	Description
result	Boolean		See description of output values.
message	String		If result is false, message will show a detailed error description.
reason	Enum	0 = OK 1 = Error
requestresponselogid	Long		This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.

closepaymentrequest

closepaymentrequest closes the payment request.

Input

Input	Type	Objecttype	Values	Description	Mandatory
merchantnumber	String	authentication		Your unique merchant number. You can find it on your merchant agreement.	Yes
password	String	authentication		Your password. Find it on your ePay account	Yes
paymentrequestid	Long	paymentrequest		The unique number identifying the payment request.	Yes

Output

Output	Type	Values	Description
result	Boolean		See description of output values.
message	String		If result is false, message will show a detailed error description.
reason	Enum	0 = OK 1 = Error
requestresponselogid	Long		This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.

Methods for transaction

addtransaction

addtransaction adds a transaction to the payment request.

Input

Input	Type	Objecttype	Values	Description	Mandatory
merchantnumber	String	authentication		Your unique merchant number. You can find it on your merchant agreement.	Yes
password	String	authentication		Your password. Find it on your ePay account.	Yes
paymentrequestid	Long	paymentrequest		The unique number identifying the payment request.	Yes
transactionid	Long	transaction		The unique number identifying the transaction.	Yes
language	String			Indicate in which language you want to receive error messages.	No
localtimezone	Boolean		True/false	True = local time	No

Output

Output	Type	Values	Description
result	Boolean		See description of output values.
message	String		If result is false, message will show a detailed error description.
reason	Enum	0 = OK 1 = Error
requestresponselogid	Long		This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.

gettransaction

gettransaction fetches transaction information based on paymentrequestid and transactionid.

Input

Input	Type	Objecttype	Values	Description	Mandatory
merchantnumber	String	authentication		Your unique merchant number. You can find it on your merchant agreement.	Yes
password	String	authentication		Your password. Find it on your ePay account.	Yes
paymentrequestid	Long	paymentrequest		The unique number identifying the payment request.	Yes
transactionid	Long	transaction		The unique number identifying the transaction.	Yes
language	String			Indicate in which language you want to receive error messages.	No
localtimezone	Boolean		True/false	True = local time	No

Output

Output	Type	Values	Description
transactionid	Integer		The unique number identifying the transaction.
created	Datetime		Date of creation
name (inputlist)	String		Input name
value (inputlist)	String		Input value
result	Boolean		See description of output values.
message	String		If result is false, message will show a detailed error description.
reason	Enum	0 = OK 1 = Error
requestresponselogid	Long		This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.

listtransaction

listtransaction fetches a list containing information about payment requests based on paymentrequestid.

Input

Input	Type	Objecttype	Values	Description	Mandatory
merchantnumber	String	authentication		Your unique merchant number. You can find it on your merchant agreement.	Yes
password	String	authentication		Your password. Find it on your ePay account.	Yes
paymentrequestid	Long	paymentrequest		The unique number identifying the payment request.	Yes
sorting	Enum	sorting	0 = ascending 1 = descending	State which sort order to use on the list, based on the date of creation.	No
exclusivestartkey	Long	paging		The transactionid from which the fetch should start. Note: This is not included in the fetch.	No
pagesize	Integer	paging	20-100	The size of the list to be fetched.	No
language	String			Indicate in which language you want to receive error messages.	No
localtimezone	Boolean		True/false	True = local time	No

Output

Output	Type	Values	Description
transactionid (transactionlist)	Integer		The unique number identifying the payment.
created (transactionlist)	Datetime		Date of creation
name (inputlist)	String		Input name
value (inputlist)	String		Input value
pagesize (paging)	Integer		The size of the fetched list.
lastevaluatedkey	Long		The transactionid which was added to the list most recently.
result	Boolean		See description of output values.
message	String		If result is false, message will show a detailed error description.
reason	Enum	0 = OK 1 = Error
requestresponselogid	Long		This is only included for test accounts or if an error occured (result is false).
Output values	If the call was successful, result is returned as true. If not, the returning value is false. When false is returned, please use message to detect the source of error.