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
This is an overview of available parameters. Default values are set in bold.
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
| Name | Values | Description | Required |
| 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 Bambora 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 |
Response
| 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 fields are fields you need to include when you call the API.
| 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 Bambora 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 fields are returned by the API.
| 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 fields are fields you need to include when you call the API.
| 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 Bambora 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 fields are returned by the API.
| 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 fields are fields you need to include when you call the API.
| 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 Bambora account. | Yes |
| paymentrequestid | Long | paymentrequest | | The unique number identifying the payment request. | Yes |
Output fields are returned by the API.
| 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 fields are fields you need to include when you call the API.
| 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 Bambora 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 fields are returned by the API.
| 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 fields are fields you need to include when you call the API.
| 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 Bambora account | Yes |
| paymentrequestid | Long | paymentrequest | | The unique number identifying the payment request. | Yes |
Output fields are returned by the API.
| 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 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.
| 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 Bambora account | Yes |
| name | String | form | | The name of the form | Yes |
| name | String | inputlist | Max 255 characters | The name of the field | Yes |
| description | String | inputlist | Max 40 characters | Placeholder text for the field | No |
| validation | String | inputlist | Max 1024 characters | Regular expression to validate the field type | No |
| sortorder | Integer | inputlist | 0 = ascending
1 = descending | Define the sort order of the fields | No |
| type | Enum | type | 1 = text
2 = checkbox
3 = select | Define the type of the field | No |
| value | String | optionlist | Max 100 characters | List which is used if you choose the select type | No |
| termsurl | String | form | Valid URL. Max 4096 characters | URL for your terms | No |
| language | String | | | Indicate in which language you want to receive error messages. | No |
| localtimezone | Boolean | | True/false | True = local time | No |
Output fields are returned by the API.
| Output | Type | Values | Description |
| formid | Integer | | ID of the form |
| 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. |
deleteform
deleteform deletes an
html form on the payment request.
Input fields are fields you need to include when you call the API.
| 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 Bambora account | Yes |
| formid | Long | form | | The ID of the form to be deleted | Yes |
| language | String | | | Indicate in which language you want to receive error messages. | No |
| localtimezone | Boolean | | True/false | True = local time | No |
Output fields are returned by the API.
| 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. |
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.
| 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 Bambora account | Yes |
| formid | Long | form | | The ID of the form to be fetched. | Yes |
| language | String | | | Indicate in which language you want to receive error messages. | No |
| localtimezone | Boolean | | True/false | True = local time | No |
Output fields are returned by the API.
| Output | Type | Values | Description |
| description (input) | String | | Description of the field |
| name (input) | String | | The name of the field |
| value (option) | String | | The value of the field |
| type (input) | Enum | | Define the field type |
| validation (input) | String | | Shows the regular expression |
| termsurl | String | | The URL for your terms |
| name |
| | The name of the form |
| 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. |
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.
| 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 Bambora account | Yes |
| sorting | Enum | sorting | 0 = stigende
1 = faldende | State which sort order to use on the list | No |
| exclusivestartkey | Long | paging | | State the formid from which the fetch should start. Notice: This is not included. | No |
| pagesize | Integer | paging | 20-100 | The size of the list | No |
| language | String | | | Indicate in which language you want to receive error messages. | No |
| localtimezone | Boolean | | True/false | True = local time | No |
Output fields are returned by the API.
| Output | Type | Values | Description |
| formid | Integer | | The ID of the form |
| name | String | | The name of the form |
| pagesize (paging) | Integer | | The size of the list |
| lastevaluatedkey | Long | | The formid 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. |
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.
| 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 Bambora account | Yes |
| requestresponselogid | Long | requestresponselog | | The unique number identifying the logid | Yes |
Output fields are returned by the API.
| Output | Type | Values | Description |
| processingtimeinms | Integer | | The time the call took in milliseconds
|
| requestapimethod | String | | The name of the method |
| requestcontentencoding | String | | Encodingtype of the request |
| requestcontenttype | String | Example: "application/json", "text/xml; charset=utf-8” | Contenttype of the request |
| requestcreated | Datetime | | Date of request |
| requesthttpmethod | String | PUT, POST, GET | Http method |
| requestinputstream | String | | Input stream
|
| requestip | String | | The IP address from which the request came
|
| requestrawurl | String | | URL på den aktuelle forespørgsel |
| requestresponselogid | Long | | Det unikke nummer, der identificerer logid'et. |
| responsecontentencoding | String | | Encodingtype of the response
|
| responsecontenttype | String | | Contenttype of the response |
| responsecreated | Datetime | | Date of the response |
| responseoutputstream | String | | Responseoutputstream on the response |
| responseresult | Boolean | | See description of output values. |
| 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.
|
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.
| 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 Bambora account | Yes |
| exclusivestartkey | Long | paging | | The requestresponselogid from which the fetch should start.
Note: This is not included in the fetch.
| No |
| pagesize | Integer | paging | | 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 = local time | No |
Output fields are returned by the API.
| Output | Type | Values | Description |
| processingtimeinms | Integer | | The time the call took in milliseconds |
| requestapimethod | String | | The name of the method |
| requestcontentencoding | String | | Encodingtype of the request |
| requestcontenttype | String | Example: "application/json", "text/xml; charset=utf-8” | Contenttype of the request |
| requestcreated | Datetime | | Date of the request |
| requesthttpmethod | String | PUT, POST, GET | Http method |
| requestip | String | | The IP address from which the request came |
| requestrawurl | String | | The URL of the payment requst |
| requestresponselogid | Long | | The unique number identifying the logid |
| responsecontentencoding | String | | Encodingtype of the response |
| responsecontenttype | String | | Contenttype of the response |
| responsecreated | Datetime | | Date of the response |
| responseresult | Boolean | | See description of output values
|
| 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. |
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.
| 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 Bambora 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 fields are returned by the API.
| 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 fields are fields you need to include when you call the API.
| 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 Bambora 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 fields are returned by the API.
| 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 fields are fields you need to include when you call the API.
| 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 Bambora account. | Yes |
| paymentrequestid | Long | paymentrequest | | The unique number identifying the payment request.
| Yes |
| sorting | Enum | sorting | 0 = stigende
1 = faldende | 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 fields are returned by the API.
| 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. |
