Please wait ...


Loading...

API for payment requests

Description of webservice 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

createpaymentrequest creates a payment request.

Input fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora account.
Yes
referenceStringpaymentrequestReference to the payment request. It's a reference that you create and assign to the payment request.Yes
exactclosedateDatetimetransactionSpecify a closing date for the payment request.No
closeafterxpaymentsIntegertransactionSpecify the number of payments to be completed before the payment request closes.No
You can add parameters to the payment request - click here to see all parameters (JSON body).
The technical documentation for parameters is available here.
parameters
languageStringIndicate in which language you want to receive error messages. No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
paymentrequestidLongThe unique number identifying the payment request.
key (paymentrequest)StringKey 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)StringURL for the payment request
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum
requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora account.Yes
paymentrequestidLongpaymentrequestThe unique number identifying the payment request.
Yes
languageStringIndicate in which language you want to receive error messages. No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
closeafterxpayments (paymentrequest)IntegerThe number of payments that can be completed before the payment request will close.
exactclosedate (paymentrequest)DatetimeThe date when the payment request will close.
key (paymentrequest)StringKey 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)StringURL for the payment request
referenceStringReference to the payment request
statusEnum1 = Open
2 = Closed
3 = Archived

parameters - click here to see all parameters (JSON body).
The technical documentation for parameters is available here.


resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum
requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora account.Yes
sortingEnumsorting0 = ascending
1 = descending
State which sort order to use on the list, based on the date of creation. No
exclusivestartkeyLongpagingThe paymentrequestid from which the fetch should start. 
Note: This is not included in the fetch.
No
pagesizeIntegerpaging20-100The size of the list to be fetched.No
languageStringIndicate in which language you want to receive error messages.No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
paymentrequestid (paymentrequestlist)LongThe unique number identifying the payment.
amount (transactionlist)InteherThe amount of the payment request
created (transactionlist)DatetimeDate of creation
currency (transactionlist)StringThe currency of the payment request
numberoftransactions (transactionlist)IntegerThe 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
lastevaluatedkeyLong
The transactionid which was added most recently.
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error
requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora account.Yes
paymentrequestidLongpaymentrequestThe unique number identifying the payment request.Yes

Output fields are returned by the API.

OutputTypeValuesDescription
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error

requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora accountYes
nameStringrecipient
The name of the recipient of the payment requestYes
emailaddressStringrecipientValid email
The recipient's email addressYes
requesterStringemail
Specify to add a "sent from" name in the emailNo
commentStringemail
Specify to add a comments field in the email
No
nameStringreplyto
Specify a name to be used when replying to the email with the payment requestNo
emailaddressStringreplytoValid emailSpecify an email address to be used when replying to the email with the payment requestNo
paymentrequestidLongpaymentrequestThe unique number identifying the payment request. Yes

Output fields are returned by the API.

OutputTypeValuesDescription
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error

requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora accountYes
paymentrequestidLongpaymentrequestThe unique number identifying the payment request.Yes

Output fields are returned by the API.

OutputTypeValuesDescription
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error

requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 form

The following section describes the methods for handling forms on the payment request.

createform

createform creates an html form on the payment request.

Input fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora accountYes
nameStringformThe name of the formYes
nameStringinputlistMax 255 charactersThe name of the fieldYes
descriptionStringinputlistMax 40 charactersPlaceholder text for the fieldNo
validationStringinputlistMax 1024 charactersRegular expression to validate the field typeNo
sortorderIntegerinputlist0 = ascending
1 = descending
Define the sort order of the fieldsNo
typeEnumtype1 = text
2 = checkbox
3 = select
Define the type of the fieldNo
valueStringoptionlistMax 100 charactersList which is used if you choose the select typeNo
termsurlStringformValid URL. Max 4096 charactersURL for your termsNo
languageStringIndicate in which language you want to receive error messages. No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
formidIntegerID of the form
resultBooleanSee description of output values
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error

requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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.

deleteform

deleteform deletes an html form on the payment request.

Input fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora accountYes
formidLongformThe ID of the form to be deletedYes
languageStringIndicate in which language you want to receive error messages. No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
resultBooleanSee description of output values
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error

requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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.

getform

getform fetches an html form for the payment request based on formid.

Input fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora accountYes
formidLongformThe ID of the form to be fetched.Yes
languageStringIndicate in which language you want to receive error messages. No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
description (input)StringDescription of the field
name (input)StringThe name of the field
value (option)StringThe value of the field
type (input)EnumDefine the field type
validation (input)StringShows the regular expression
termsurlStringThe URL for your terms
name
The name of the form
resultBooleanSee description of output values
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error
requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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.

listform

listform fetches a list containing html fomrs for the payment request based on formid.

Input fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora accountYes
sortingEnumsorting0 = stigende 
1 = faldende
State which sort order to use on the listNo
exclusivestartkeyLongpagingState the formid from which the fetch should start. Notice: This is not included.No
pagesizeIntegerpaging20-100The size of the listNo
languageStringIndicate in which language you want to receive error messages. No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
formid IntegerThe ID of the form
name StringThe name of the form
pagesize (paging)IntegerThe size of the list
lastevaluatedkeyLongThe formid which was added most recently
resultBooleanSee description of output values
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error
requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 requestresponselog

The following section describes the methods for handling requests/responses based on logid.

getrequestresponselog

getrequestresponselog fetches information about requests/responses based on logid.

Input fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora accountYes
requestresponselogidLongrequestresponselogThe unique number identifying the logidYes

Output fields are returned by the API.

OutputTypeValuesDescription
processingtimeinmsIntegerThe time the call took in milliseconds
requestapimethodStringThe name of the method
requestcontentencodingStringEncodingtype of the request
requestcontenttypeStringExample: "application/json", "text/xml; charset=utf-8”Contenttype of the request
requestcreatedDatetimeDate of request
requesthttpmethodStringPUT, POST, GETHttp method
requestinputstreamStringInput stream
requestipStringThe IP address from which the request came
requestrawurlStringURL på den aktuelle forespørgsel
requestresponselogidLongDet unikke nummer, der identificerer logid'et.
responsecontentencodingStringEncodingtype of the response
responsecontenttypeStringContenttype of the response
responsecreatedDatetimeDate of the response
responseoutputstreamStringResponseoutputstream on the response
responseresultBooleanSee description of output values.
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error

requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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.

listrequestresponselog

listrequestresponselog fetches a list containing information about requests/responses based on logid.

Input fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora accountYes
exclusivestartkeyLongpagingThe requestresponselogid from which the fetch should start. 
Note: This is not included in the fetch.
No
pagesizeIntegerpagingThe size of the list to be fetched.No
languageString
Indicate in which language you want to receive error messages. No
localtimezoneBoolean
True = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
processingtimeinmsIntegerThe time the call took in milliseconds
requestapimethodStringThe name of the method
requestcontentencodingStringEncodingtype of the request
requestcontenttypeStringExample: "application/json", "text/xml; charset=utf-8”Contenttype of the request
requestcreatedDatetimeDate of the request
requesthttpmethodStringPUT, POST, GETHttp method
requestipStringThe IP address from which the request came
requestrawurlStringThe URL of the payment requst
requestresponselogidLongThe unique number identifying the logid
responsecontentencodingStringEncodingtype of the response
responsecontenttypeStringContenttype of the response
responsecreatedDatetimeDate of the response
responseresultBooleanSee description of output values
pagesize (paging)IntegerThe size of the fetched list
lastevaluatedkeyLongThe transactionid which was added most recently.
resultBooleanSee description of output values
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error
requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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

The following describes the methods for managing transactions in connection with payment requests.

addtransaction

addtransaction adds a transaction to the payment request.

Input fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthentication
Your unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthentication
Your password. Find it on your Bambora account.
Yes
paymentrequestidLongpaymentrequest

The unique number identifying the payment request. 
Yes
transactionid
Longtransaction
The unique number identifying the transaction.
Yes
language
String

Indicate in which language you want to receive error messages.No
localtimezone
Boolean
True/falseTrue = local time
No

Output fields are returned by the API.

OutputTypeValuesDescription
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error

requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora account.Yes
paymentrequestidLongpaymentrequestThe unique number identifying the payment request. Yes
transactionidLongtransactionThe unique number identifying the transaction.
Yes
languageStringIndicate in which language you want to receive error messages.No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
transactionidIntegerThe unique number identifying the transaction.
createdDatetimeDate of creation
name (inputlist)StringInput name
value (inputlist)StringInput value
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error

requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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 fields are fields you need to include when you call the API.

InputTypeObjectTypeValuesDescriptionMandatory
merchantnumberStringauthenticationYour unique merchant number. You can find it on your merchant agreement.Yes
passwordStringauthenticationYour password. Find it on your Bambora account.Yes
paymentrequestidLongpaymentrequestThe unique number identifying the payment request. 
Yes
sortingEnumsorting0 = stigende
1 = faldende
State which sort order to use on the list, based on the date of creation. No
exclusivestartkeyLongpagingThe transactionid from which the fetch should start. 
Note: This is not included in the fetch.
No
pagesizeIntegerpaging20-100The size of the list to be fetched.No
languageStringIndicate in which language you want to receive error messages.No
localtimezoneBooleanTrue/falseTrue = local timeNo

Output fields are returned by the API.

OutputTypeValuesDescription
transactionid (transactionlist)IntegerThe unique number identifying the payment.
created (transactionlist)DatetimeDate of creation
name (inputlist)StringInput name
value (inputlist)StringInput value
pagesize (paging)IntegerThe size of the fetched list.
lastevaluatedkeyLong
The transactionid which was added to the list most recently.
resultBooleanSee description of output values.
messageStringIf result is false, message will show a detailed error description.
reasonEnum0 = OK
1 = Error
requestresponselogidLongThis is only included for test accounts or if an error occured (result is false).
Output valuesIf 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.