Payment API
Following are descriptions of all available entities in OnlineFundraising v4.0 onwards and their properties, however you may prefer starting with our guide for a simple integration.
1.0 Contact
Changes committed to a Contact can be retrieved via the ChangeLog entity.
Properties
Name | Type | Mandatory | Default | Example | Description |
---|---|---|---|---|---|
contactGuid | STRING | - | Unique GUID | ||
merchantId | STRING | - | Readable ID of the merchant | ||
name | STRING | NO | OnlineFundraising ApS | Full name of Contact | |
birthDate | DATE | NO | Birthday of Contact (YYYY-MM-DD) | ||
nationalId | STRING | NO | National ID (i.e. CPR in Denmark provided without dashes) | ||
address | STRING | NO | Finsensvej 6E, 2. | Address | |
address2 | STRING | NO | Address line 2 | ||
postCode | STRING | NO | 2000 | Postcode | |
city | STRING | NO | Frederiksberg | City | |
countryCode | STRING | NO | DK | ISO formatted Country Code (wiki) | |
msisdn | STRING | NO | 4535294855 | Phone with Country Code (wiki on Country Code) with 1-3 digits reserved for country code without prefixes, such as 00 (wiki on MSISDN). | |
STRING | NO | support@onlinefundraising.dk | Email of the Contact | ||
firstName | STRING | NO | First name | ||
lastName | STRING | NO | Last name | ||
companyName | STRING | NO | OnlineFundraising ApS | Company name | |
businessCode | STRING | NO | 37273457 | Business Code (i.e. VAT, CVR in Denmark) | |
contactType | STRING | NO | individual, business | Type of Contact. Please note the value is not restricted to the examples given, however our form field will use these. | |
createdTs | TIMESTAMP | - | Timestamp of Contact creation | ||
updatedTs | TIMESTAMP | - | Timestamp of last update | ||
anonymizedTs | TIMESTMAP | - | Timestamp of anonymisation. | ||
archivedTs | TIMESTAMP | - | Timestamp of archivation after which the Contact is hidden from queries. | ||
externalId | STRING | NO | An external ID | ||
externalLink | STRING | NO | An external URL to e.g. CRM | ||
originTs | TIMESTAMP | NO | Timestamp of origin, useful when importing data | ||
mergeTargetGuid | STRING | - | A GUID of that contact that this has been merged into. | ||
mergeTs | TIMESTAMP | - | Timestamp of the merge operation. |
The contactType property
As stated above the contactType property is not restricted to either "individual" or "business", however please note our form field will use these and show/hide the relevant fields upon selection.
individual | business | |
---|---|---|
name | v | x |
firstName | v | v |
lastName | v | v |
companyName | x | v |
nationalId | v | x |
businessCode | x | v |
address | v | v |
postCode | v | v |
city | v | v |
countryCode | v | v |
msisdn | v | v |
GET /contacts?pageNumber={x}&pageSize={y}&archived=false|true
Get a list of Contacts at a given size by a given offset. Use "archived" (defaults to false) to focus your query. All parameters are optional.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
{ "pageNumber": {x}, "pageSize": {y}, "list": [ { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "contactGuid": "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx", "...": "..." } ] }
GET /contacts?search={email|msisdn}
Get an array of Contacts by a given search string matching either email or msisdn (phone).
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
[ { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "contactGuid": "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx", "...": "..." } ]
GET /contact/{guid}
Get a single Contact.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Contact was not found |
HTTP 200 Example
{ "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "merchantId": "your-organisation", "name": "Jens Jensen", "birthDate": "2005-07-10", "nationalId": "1007059995", "address": "Store Kongensgade 59B", "address2": "", "postCode": "1264", "city": "København K", "countryCode": "DK", "msisdn": "4535294855", "email": "", "firstName": "Jens", "lastName": "Jensen", "companyName": "", "businessCode": "", "createdTs": "2019-12-31 15:59:59 +0100", "updatedTs": "", "archivedTs": "", "externalId": "", "externalLink": "" }
POST /contact
Insert a single Contact.
Please note our API accepts the given properties as is, and will not validate e.g. email, msisdn, nationalId, businessCode, address, birthDate, (full)name against given firstName and lastName.
Request
The following may be provided as the request body:
{ "name": "Jens Jensen", "birthDate": "2005-07-10", "nationalId": "1007059995", "address": "Store Kongensgade 59B", "address2": "", "postCode": "1264", "city": "København K", "countryCode": "DK", "msisdn": "4535294855", "email": "", "firstName": "Jens", "lastName": "Jensen", "companyName": "", "businessCode": "", "externalId": "", "externalLink": "" }
Response
HTTP | Description |
---|---|
201 | Created |
400 | Something's wrong with request body. |
HTTP 201 Example
{ "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }
PUT /contact/{guid}
Replace a single Contact.
Request
The following may be provided as the request body:
{ "name": "Jens Jensen", "birthDate": "2005-07-10", "nationalId": "1007059995", "address": "Store Kongensgade 59B", "address2": "", "postCode": "1264", "city": "København K", "countryCode": "DK", "msisdn": "4535294855", "email": "", "firstName": "Jens", "lastName": "Jensen", "companyName": "", "businessCode": "", "externalId": "", "externalLink": "" }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Contact was not found |
HTTP 200 Example
{ "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }
PATCH /contact/{guid}
Update a single Contact using add, replace or remove operations.
Request
The following must be provided as the request body:
[ { "op": "add|replace|remove", "path": "/address", "value": "Store Kongensgade 59A" } ]
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Contact was not found |
POST /contact/{guid}/Anonymise
Anonymising a Contact will delete all properties revealing personal information, and then mark it archived to hide it from queries. This means the entity will as such be kept as it ties Subscriptions, Payment Methods and Payments together, which might be relevant later for accounting purposes.
Response
HTTP | Description |
---|---|
200 | OK |
400 | Contact cannot be archived, most likely due to active Subscriptions |
404 | Contact was not found |
POST /contact/{guid}/Archive
Archiving a Contact will hide it from queries.
Response
HTTP | Description |
---|---|
200 | OK |
400 | Contact cannot be archived, most likely due to active Subscriptions |
404 | Contact was not found |
POST /contact/{guid}/Merge
Merge two Contacts: a duplicate Contact defined in the endpoint URL and a target Contact defined in the request body.
A callback will be sent on a successful merge for the duplicate Contact being merged. Nothing is sent for the target Contact.
After a successful merge, the property mergeTargetGuid is set on the archived duplicate Contact.
Request
The following must be provided as the request body:
{ "mergeTargetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx" }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body |
404 | Either the duplicate or target guid was not found |
POST /contact/{guid}/Unmerge
Unmerge two Contacts that were previously merged by specifying the guid of the Archived Contact. The endpoint will restore the archived Contact to its previous state with references to related entities.
Webhooks with type “Updated” will be sent for the unmerged Contact.
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body or the specified Contact has not been merged |
404 | Contact not found |
GET /contact/{guid}/paymentMethods
Get a list of Payment Methods for a single Contact.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Contact was not found |
HTTP 200 Example
[ { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /contact/{guid}/subscriptions
Get a list of Subscriptions for a single Contact.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Contact was not found |
HTTP 200 Example
[ { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /contact/{guid}/agreements
Get a list of Agreements for a single Contact.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Contact was not found |
HTTP 200 Example
[ { "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /contact/{guid}/addOns
Get a list of AddOns for a single Contact.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Contact was not found |
HTTP 200 Example
[ { "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /contact/{guid}/payments
Get a list of Payments for a single Contact at a given size by a given offset.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Contact was not found |
HTTP 200 Example
[ { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /contact/{guid}/log?limit={limit}
Get a list of changes to an Contact.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
[ { "changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx", "createdTs": "2021-01-01 00:00:00 +0100", "entityType": "Contact", "entityGuid": "9a7c3665-5be0-4a5c-9641-xxxxxxxxxxxx", "changeTs": "2021-01-01 00:00:00 +0100", "oldEntityJson": "{ .. }", "changeDescription": "Updated by PUT request", "requester": "", "systemRequest": false, "changes": [ { "newValue": "John Arne", "oldValue": "John", "fieldName": "name" } ] } ]
2.0 Agreement
Changes committed to an Agreement can be retrieved via the ChangeLog entity.
Properties
Name | Type | Mandatory | Default | Example | Description |
---|---|---|---|---|---|
agreementGuid | STRING(64) | - | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | Unique GUID | |
createdTs | TIMESTAMP | - | Timestamp of Agreement creation | ||
merchantId | STRING | - | Readable ID of the merchant | ||
name | STRING(30) | YES | Name of Agreement | ||
description | STRING(60) | NO | Invoice description | ||
agreementType | STRING | YES | Personal / Shared | Agreements can either be Personal or Shared. Shared agreements are used by many Contacts, such as memberships with a certain frequency and amount, whereas personal agreements are unique to each individual Contact, such as a recurring donation of a specific frequency and amount. | |
contactGuid | STRING(64) | NO | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | GUID of Contact | |
communicationCollectionGuid | STRING(64) | NO | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | GUID of Communication Collection | |
defaultQuantity | INTEGER | NO | 1 | Default quantity | |
unit | STRING | YES | pcs | Unit | |
unitPrice | DOUBLE | YES | 100.0 | The price of a single unit | |
amount | DOUBLE | YES | 100.0 | Summarized amount excluding VAT | |
amountVat | DOUBLE | YES | 25.0 | Amount VAT | |
amountTotal | DOUBLE | YES | 125.0 | Total amount including VAT used when charging | |
taxDeductable | BOOLEAN | YES | true | Defines basis for tax deductibility | |
vatPercentage | DOUBLE | YES | 25.0 | VAT percentage | |
currencyCode | STRING | YES | DKK | ISO formatted Currency Code (wiki) | |
state | STRING | - | Please see list of Agreement States below. | ||
paymentRequired | BOOLEAN | YES | true | Are Payments required for the Agreement's Subscriptions to be valid? | |
scheduleType | STRING | YES | Monthly | Please see list of Agreement Schedule Types below. | |
scheduleBaseTier | INTEGER | YES | The offset in relation to the chosen calendarUnit. | ||
scheduleFixedDay | INTEGER | YES | 1-28 | A fixed day of the chosen calendarUnit. | |
scheduleEveryOther | INTEGER | YES | Please see description below. | ||
scheduleCalendarUnit | STRING | NO | Month | Month | Calculate due date based on the chosen calendarUnit. Please see list of Schedule Calendar Units below. |
scheduleSelectedSet | STRING | NO | "[1,2,3,4,5,6]" | Only calculate due dates when due date based on calendarUnit is in provided set of integers. | |
archivedTs | TIMESTAMP | - | Timestamp of archivation | ||
externalId | STRING | NO | An external ID | ||
originTs | TIMESTAMP | NO | Timestamp of origin, useful when importing data | ||
purposeAccountingCode | STRING(32) | NO | Accounting Code defined by Merchant used to identify the receiving part of transactions | ||
dataSetGuid | STRING(64) | NO | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | A DataSet GUID containing metadata |
GET /agreements?pageNumber={x}&pageSize={y}&state={z}
Get a list of Shared Agreements at a given size by a given offset and availability type. Use "state" (see list of states below) to focus your query. All parameters are optional.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
{ "pageNumber": {x}, "pageSize": {y}, "list": [ { "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ] }
GET /agreement/{guid}
Get a single Agreement.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Agreement not found |
HTTP 200 Example
{ "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "createdTs": "2019-01-01 00:00:00 +0100", "merchantId": "your-organisation", "name": "Youth Membership", "description": "", "agreementType": "Shared", "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "communicationCollectionGuid": "", "defaultQuantity": 1, "unit": "pcs", "unitPrice": 100.0, "amount": 100.0, "amountVat": 25.0, "amountTotal": 125.0, "taxDeductable": false, "vatPercentage": 25.0, "currencyCode": "DKK", "state": "", "paymentRequired": true, "scheduleType": "Monthly", "scheduleBaseTier": 1, "scheduleFixedDay": 1, "scheduleEveryOther": 1, "scheduleCalendarUnit": "Month", "scheduleSelectedSet": "[1,2,3,4,5,6]", "purposeAccountingCode": "", "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx" }
POST /agreement
Insert a single Agreement.
Request
The following must be provided as the request body:
{ "name": "Youth Membership", "description": "", "agreementType": "Shared/Personal", "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "defaultQuantity": 1, "unit": "pcs", "unitPrice": 100.0, "amount": 100.0, "amountVat": 25.0, "amountTotal": 125.0, "taxDeductable": false, "vatPercentage": 25.0, "currencyCode": "DKK", "paymentRequired": true, "scheduleType": "Monthly", "scheduleBaseTier": 1, "scheduleFixedDay": 1, "scheduleEveryOther": 1, "scheduleCalendarUnit": "Month", "scheduleSelectedSet": "[1,2,3,4,5,6]", "purposeAccountingCode": "", "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx" }
Response
HTTP | Description |
---|---|
201 | Created |
400 | Something's wrong with request body. |
HTTP 200 Example
{ "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }
PUT /agreement/{guid}
Replace a single Agreement.
Request
The following must be provided as the request body:
{ "name": "Youth Membership", "description": "", "agreementType": "Shared/Personal", "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "defaultQuantity": 1, "unit": "pcs", "unitPrice": 100.0, "amount": 100.0, "amountVat": 25.0, "amountTotal": 125.0, "taxDeductable": false, "vatPercentage": 25.0, "currencyCode": "DKK", "paymentRequired": true, "scheduleType": "Monthly", "scheduleBaseTier": 1, "scheduleFixedDay": 1, "scheduleEveryOther": 1, "scheduleCalendarUnit": "Month", "scheduleSelectedSet": "[1,2,3,4,5,6]", "purposeAccountingCode": "", "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx" }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Agreement not found |
HTTP 200 Example
{ "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }
PATCH /agreement/{guid}
Update a single Agreement. The following fields are patchable: name, description, defaultQuantity, unit, taxDeductable, paymentRequired, externalId, purposeAccountingCode and communicationCollectionGuid
Request
The following must be provided as the request body:
[ { "op": "replace", "path": "/name", "value": "New agreement name" } ]
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Agreement was not found |
POST /agreement/{guid}/ChangeAmount
Change amount of a single Agreement.
Request
The following must be provided as the request body:
{ "unitPrice": 100.0, "quantity": 1, "amount": 100.0, "amountVat": 25.0, "amountTotal": 125.0, "vatPercentage": 25.0 }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Agreement was not found |
POST /agreement/{guid}/ChangeFrequency
Change frequency of a single Agreement.
Request
The following must be provided as the request body:
{ "scheduleType": "Monthly", "scheduleBaseTier": 1, "scheduleFixedDay": 1, "scheduleEveryOther": 1, "scheduleCalendarUnit": "Month", "scheduleSelectedSet": "[1,2,3,4,5,6]" }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Agreement was not found |
POST /agreement/{guid}/Archive
Archives a single Agreement.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Agreement was not found |
GET /agreement/{guid}/payments?pageNumber={x}&pageSize={y}
Get a list of Payments at a given size by a given offset.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
{ "pageNumber": {x}, "pageSize": {y}, "list": [ { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ] }
GET /agreement/{guid}/subscriptions?pageNumber={x}&pageSize={y}
Get a list of Agreements at a given size by a given offset.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
{ "pageNumber": {x}, "pageSize": {y}, "list": [ { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ] }
GET /agreement/{guid}/log?limit={limit}
Get a list of changes to an Agreement.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
[ { "changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx", "createdTs": "2021-01-01 00:00:00 +0100", "entityType": "Agreement", "entityGuid": "9a7c3665-5be0-4a5c-9641-xxxxxxxxxxxx", "changeTs": "2021-01-01 00:00:00 +0100", "oldEntityJson": "{ .. }", "changeDescription": "Updated by PUT request", "requester": "", "systemRequest": false, "changes": [ { "newValue": "Membership", "oldValue": "Donation", "fieldName": "name" } ] } ]
Schedule Types
Following is a list of allowed schedule types:
scheduleType | Description |
---|---|
Manual | Payment occurs only when manually initiated |
Custom | Uses provided baseTier, fixedDay, everyOther, calendarUnit and selectedSet to calculate next dueDate |
Daily | Daily occurrence |
Weekly | Weekly occurrence (~52 per year) |
Monthly | Monthly occurrence (12 per year) |
Quarterly | Quarterly occurrence (4 per year) |
Halfyearly | Biannual occurrence (2 per year) |
Yearly | Annual occurrence (1 per year) |
MonthlyFirst | Monthly occurrence on the 1st of given month |
QuarterlyFirst | Quarterly occurrence on the 1st of given month |
HalfyearlyFirst | Biannual occurrence on the 1st of given month |
YearlyFirst | Annual occurrence on the 1st of given month |
Schedule Calendar Units
Following is a list of allowed schedule calendar units:
scheduleCalendarUnit | Description |
---|---|
Day | One day |
Week | One week |
Month | One month |
Examples of schedules
All the following examples, assumes that the start date of the related subscription is the 1st of January.
Agreement States
Following is a list of Agreement states:
State | Description |
---|---|
Available | Agreement is available for Subscriptions. |
Archived | Agreement was archived and is hidden from queries. |
3.0 AddOn
Properties
Name | Type | Mandatory | Default | Example | Description |
---|---|---|---|---|---|
addOnGuid | STRING | - | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | Unique GUID | |
merchantId | STRING | - | Readable ID of the merchant | ||
createdTs | TIMESTAMP | - | Timestamp of AddOn creation | ||
subscriptionGuid | STRING | YES | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | Unique GUID of Subscription | |
contactGuid | STRING | YES | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | Unique GUID of Contact | |
dataGuid | STRING | NO | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | Unique GUID of DataSet holdning metaData | |
name | STRING | YES | Gift | Name of AddOn | |
description | STRING | NO | Invoice description | ||
quantity | INTEGER | NO | 1 | 1 | Quantity |
unit | STRING | YES | pcs | Unit | |
unitPrice | DOUBLE | YES | 100.0 | Unit price of a single AddOn | |
amount | DOUBLE | YES | 100.0 | Summarized amount excluding VAT | |
amountVat | DOUBLE | YES | 0.0 | Amount VAT | |
amountTotal | DOUBLE | YES | 100.0 | Total amount including VAT | |
vatPercentage | DOUBLE | YES | 0.0 | VAT percentage | |
taxDeductable | BOOLEAN | YES | Defines basis for tax deductibility | ||
state | STRING | - | Please see list of AddOn States below | ||
externalId | STRING | NO | An external ID | ||
purposeAccountingCode | STRING(32) | NO | Accounting code provided by Merchant | ||
startDate | DATE | NO | Start of Add On | ||
expiresAfterDate | DATE | NO | Date of expiration | ||
cancelledTs | TIMESTAMP | - | Timestamp of cancellation | ||
archivedTs | TIMESTAMP | - | Timestamp of archivation | ||
includeImplicitInAgreement | BOOLEAN | NO | Looking at the invoice, is the Add On amount included in the Agreement amount? |
GET /addOn/{guid}
Get a single Add On.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Add On not found |
HTTP 200 Example
{ "addOnGuid": "", "name": "", "description": "", "createdTs": "", "subscriptionGuid": "", "dataSetGuid": "", "quantity": "", "unit": "", "unitPrice": "", "amount": "", "amountVat": "", "amountTotal": "", "vatPercentage": "", "taxDeductable": "", "state": "", "externalId": "", "purposeAccountingCode": "", "expiresAfterDate": "", "archivedTs": "", "includeImplicitInAgreement": "" }
POST /addOn
Insert a single AddOn.
Request
The following must be provided as the request body:
{ "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "name": "Gift", "description": "A small gift", "quantity": 1, "unit": "pcs", "unitPrice": 10.0, "amount": 10.0, "amountVat": 0.0, "amountTotal": 10.0, "vatPercentage": 0.0, "taxDeductable": true, "externalId": "xyz", "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "purposeAccountingCode": "gift", "expiresAfterDate": "2020-01-01", "includeImplicitInAgreement": false }
Response
HTTP | Description |
---|---|
201 | Created |
400 | Something's wrong with request body. |
HTTP 200 Example
{ "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }
PUT /addOn/{guid}
Update a single AddOn.
Request
The following must be provided as the request body:
{ "name": "Gift", "description": "A small gift", "quantity": 1, "unit": "pcs", "unitPrice": 10.0, "amount": 10.0, "amountVat": 0.0, "amountTotal": 10.0, "vatPercentage": 0.0, "taxDeductable": true, "externalId": "xyz", "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "purposeAccountingCode": "gift", "expiresAfterDate": "2020-01-01", "includeImplicitInAgreement": false }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | AddOn was not found |
HTTP 200 Example
{ "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }
POST /addOn/{guid}/Cancel
Cancels a single AddOn.
Response
HTTP | Description |
---|---|
200 | OK |
400 | Bad request |
404 | Not found |
POST /addOn/{guid}/Archive
Archives a single AddOn.
Response
HTTP | Description |
---|---|
200 | OK |
400 | Bad request |
404 | Not found |
AddOn States
Following is a list of AddOn states:
State | Description |
---|---|
Active | Subscription is active and will result in future Payments. |
Inactive | Subscription is inactive. |
Archived | Subscription was archived and is therefore hidden from queries. |
4.0 Subscription
Changes committed to a Subscription can be retrieved via the ChangeLog entity.
Properties
Name | Type | Mandatory | Default | Example | Description |
---|---|---|---|---|---|
subscriptionGuid | STRING | - | Unique GUID | ||
merchantId | STRING | - | Readable ID of the merchant | ||
contactGuid | STRING | YES | |||
agreementGuid | STRING | YES | |||
state | STRING | YES | Please see list of Subscription States below | ||
paymentMethodType | STRING | - | Please see list of Payment Method Types under Payment Method | ||
paymentMethodGuid | STRING | YES | GUID of Payment Method | ||
createdTs | DATETIME | - | Timestamp of Subscription creation | ||
startDate | DATETIME | YES | "2020-01-01", but most commonly the current date. | Date from which OnlineFundraising should begin charging the Subscription. | |
expiresAfterDate | DATETIME | NO | Date of expiration | ||
cancelledTs | DATETIME | - | Timestamp of cancellation | ||
cancelCode | INTEGER | - | Please see list of Cancel Codes below | ||
cancelDescription | STRING | NO | User friendly description of cancellation or custom string provided by Merchant | ||
holdDescription | STRING | NO | Custom string provided by Merchant | ||
archivedTs | DATETIME | - | Timestamp of archiving | ||
inactivatedTs | DATETIME | - | Timestamp of deactivation | ||
quantity | INTEGER | NO | 1 | Defaults to 1 | |
errorCode | INTEGER | - | Please see list of Subscription Error Codes below | ||
errorDescription | STRING | - | User friendly description of the provided error | ||
nextDueDate | DATETIME | - | Date of next planned charge calculated by Agreement schedule configuration | ||
externalId | STRING | NO | An external ID | ||
externalLink | STRING | NO | An external URL to e.g. CRM | ||
originTs | DATETIME | NO | Non-operational timestamp of origin, useful when importing data. | ||
dataSetGuid | STRING | NO | The DataSet GUID used to create the Contact |
GET /subscriptions?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}&state={z}
Get a list of Subscriptions at a given size by a given offset and date limitation. Use "state" (see list of states below) to focus your query. All parameters are optional.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
{ "pageNumber": {x}, "pageSize": {y}, "startDate": { yyyy-mm-dd }, "endDate": { yyyy-mm-dd }, "list": [ { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ] }
GET /subscription/{guid}
Get a single Subscription.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Subscription not found |
HTTP 200 Example
{ "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "version": 1, "contactGuid": "", "agreementGuid": "", "state": "", "paymentMethodType": "", "paymentMethodGuid": "", "createdTs": "2019-01-01 00:00:00 +0100", "startDate": "", "expiresAfterDate": "", "cancelledTs": "", "cancelCode": "", "cancelDescription": "", "holdDescription": "", "archivedTs": "", "quantity": 1, "errorCode": "", "errorDescription": "", "nextDueDate": "", "externalId": "", "externalLink": "", "dataSetGuid": "" }
POST /subscription
Insert a single Subscription.
Request
The following must be provided as the request body:
{ "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "paymentMethodType": "", "paymentMethodGuid": "", "startDate": "", "expiresAfterDate": "", "quantity": 1, "externalId": "", "externalLink": "" }
Response
HTTP | Description |
---|---|
201 | Created |
400 | Something's wrong with request body. |
HTTP 201 Example
{ "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }
PATCH /subscription/{guid}
Update a single Subscription. The following fields are patchable: expiresAfterDate, holdDescription, quantity, externalId and externalLink.
Request
The following must be provided as the request body:
[ { "op": "add|replace|remove", "path": "/externalId", "value": "1001" } ]
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Subscription was not found |
GET /subscription/{guid}/schedule
Get an array of five scheduled payment due dates, after the nextDueDate, for a single Subscription.
The example below correlates to a Monthly Subscription with the nextDueDate: 2019-05-01.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Subscription was not found |
HTTP 200 Example
[ "2019-06-01", "2019-07-01", "2019-08-01", "2019-09-01", "2019-10-01" ]
GET /subscription/{guid}/payments
Get a list of Payments for a single Subscription.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Subscription was not found |
HTTP 200 Example
[ { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /subscription/{guid}/singleCosts
Get a list of /wiki/spaces/OFpublic/pages/4816985 for a single Subscription.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Subscription was not found |
HTTP 200 Example
[ { "singleCostGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "singleCostGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /subscription/{guid}/singleDiscounts
Get a list of /wiki/spaces/OFpublic/pages/327885 for a single Subscription.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Subscription was not found |
HTTP 200 Example
[ { "singleDiscountGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "singleDiscountGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /subscription/{guid}/addOns
Get a list of Add Ons for a single Subscription.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Subscription was not found |
HTTP 200 Example
[ { "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "addOnGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
POST /subscription/{guid}/Hold
Hold a Subscription.
Request
The following can be provided as the request body:
{ "holdDescription": "..." }
Response
HTTP | Description |
---|---|
200 | OK |
404 | Subscription was not found |
POST /subscription/{guid}/Restart
Restart a Subscription from Hold state.
Request
The following can be provided as the request body:
{ "startDate": "2019-01-01 00:00:00 +0100", "expiresAfterDate": "2019-12-31 00:00:00 +0100" }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Subscription was not found |
POST /subscription/{guid}/Cancel
Cancel a Subscription, but please note this does affect neither the Payment Method nor Pending Payments.
Request
The following can be provided as the request body:
{ "cancelDescription": "..." }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Subscription was not found |
POST /subscription/{guid}/Archive
Archive a Subscription.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Subscription was not found |
POST /subscription/{guid}/ChangeAgreement
Change the Agreement of a Subscription. A new startDate and nextDueDate is calculated for the Subscription based on the new Agreement.
Triggers a Subscription updated webhook.
Request
The following must be provided as the request body:
{ "agreementGuid": "a6195e22-f9c3-xxxx-9da6-4cb4d1fff778" }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body |
404 | Subscription was not found |
HTTP 200 Example
{ "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "createdTs": "2021-06-10 13:43:10", "agreementGuid": "a6195e22-f9c3-xxxx-9da6-4cb4d1fff778", ... : ... }
POST /subscription/{guid}/UpdatePaymentMethod
Update the PaymentMethod of a Subscription. A new startDate and nextDueDate is calculated for the Subscription based on the new PaymentMethod.
Triggers a Subscription updated webhook.
Request
The following must be provided as the request body:
{ "paymentMethodGuid": "71209531-xxxx-xxxx-xxxx-49c0f59f1bfc" }
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body |
404 | Subscription was not found |
HTTP 200 Example
{ "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "createdTs": "2021-06-10 13:43:10", "paymentMethodGuid": "71209531-xxxx-xxxx-xxxx-49c0f59f1bfc", ... : ... }
GET /subscription/{guid}/log?limit={limit}
Get a list of changes to a Subscription.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
[ { "changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx", "createdTs": "2021-01-01 00:00:00 +0100", "entityType": "Subscription", "entityGuid": "9a7c3665-5be0-4a5c-9641-xxxxxxxxxxxx", "changeTs": "2021-01-01 00:00:00 +0100", "oldEntityJson": "{ .. }", "changeDescription": "Updated by PUT request", "requester": "", "systemRequest": false, "changes": [ { "newValue": "Inactive", "oldValue": "Active", "fieldName": "state" } ] } ]
Subscription States
Following is a list of Subscription states:
State | Description |
---|---|
Pending | Waiting for PaymentMethod to become active. |
Active | Subscription is active and will result in future Payments. |
Inactive | Subscription is inactive and is therefore not in consideration for future Payments. |
Expired | Subscription has passed expiration date. |
Archived | Subscription was archived and is therefore hidden from queries. |
Error | Subscription has errorCode and errorDescription. |
Subscription State Diagram
Subscription Error Codes and Descriptions
For further examples and ties to other entities, please see: Error and Cancel Codes
Error Code | Description | State |
---|---|---|
100001 | Subscription has no active Payment Method, but Payments are required by the Agreement. | Active |
100002 | Subscription has no active Payment Method, and Payments are not required. | Inactive |
100003 | Subscription Payment Method not found at the time of scheduling. | Inactive |
Subscription Cancel Codes
For further examples and ties to other entities, please see: Error and Cancel Codes
Cancel Code | Description | State |
---|---|---|
100101 | Cancelled by Debtor. | Inactive |
100102 | Cancelled by Creditor in either UI or API integration. | Inactive |
100103 | Expired due to the defined expiresAfterDate. | Inactive |
100104 | Cancelled by System at the time of charge. Due to the Payment Method being cancelled at payment gateway. | Inactive |
5.0 Payment Method
Properties
Name | Type | Description |
---|---|---|
paymentMethodGuid | STRING | Unique GUID |
paymentSessionGuid | STRING | GUID of Payment Session used internally |
contactGuid | STRING | GUID of Contact |
state | STRING | Please see list of Payment Method States below |
paymentMethodType | STRING | Please see list of Payment Method Types below |
paymentMethodAccountingCode | STRING | Accounting Code defined by Payment Method. Please see list below |
paymentGatewayProvider | STRING | Please see list of Payment Gateway Providers below |
paymentGatewayGuid | STRING | GUID of Payment Gateway used internally |
paymentGatewaySubscriptionReferenceId | STRING | A token from the chosen Payment Gateway used for recurring payments |
metaData | JSON Object | Contains metadata such as card type, masked card number etc. |
createdTs | DATE | Timestamp of Payment Method creation |
cancelledTs | DATE | Timestamp of cancellation |
cancelCode | INTEGER | Please see list of Cancel Codes below |
cancelDescription | STRING | User friendly description of cancellation |
expireTs | DATE | Timestamp of expiration |
errorCode | INTEGER | Please see list of Payment Method Error Codes below |
errorDescription | STRING | User friendly description of the provided error |
gatewayErrorCode | INTEGER | Error code from Payment Gateway. Please see: Error and Cancel Codes |
gatewayErrorDescription | STRING | Error description from Payment Gateway. Please see: Error and Cancel Codes |
rawErrorString | STRING | Uninterpreted error response provided by Payment Gateway |
GET /paymentMethod/{guid}
Get a single Payment Method.
Response
HTTP 200 Example
{ "paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "paymentSessionGuid": "", "contactGuid": "", "state": "", "paymentMethodType": "", "paymentMethodAccountingCode": "", "paymentGatewayProvider": "", "paymentGatewayGuid": "", "paymentGatewaySubscriptionToken": "", "createdTs": "", "cancelledTs": "", "cancelCode": "", "cancelDescription": "", "expireTs": "", "errorCode": "", "errorDescription": "", "metaData": { "card": { "type": "Dankort", "expiresTs": "2020-01", "cardNumber": "457150XXXXXX7478", "acquirer": "Nets/Teller" }, "bs": { "mandate": "956964XXX", "customerNumber": "605XXX" }, "mps": { "externalId": "1568581537XXX" }, "sms": { "msisdn": "4512345678" } } }
POST /paymentMethod PLANNED
Since creation of Payment Methods usually requires interaction with the chosen Payment Gateway it is essentially not possible to create a Payment Method at distance.
GET /paymentMethod/{guid}/subscriptions
Get a list of Subscriptions for a single Payment Method.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Payment Method was not found |
HTTP 200 Example
[ { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
POST /paymentMethod/{guid}/Cancel
Cancel a Payment Method, but please note this does not affect the Subscription and is not allowed if Pending Payments exists.
Request
The following must be provided as the request body:
{ "cancelCode": "...", "cancelDescription": "..." }
Response
HTTP | Description |
---|---|
202 | Accepted |
400 | Bad Request |
404 | Payment Method not found |
A callback is sent when the cancel operation either fails or succeeds.
Payment Gateway Providers
Payment Gateway Provider | Description |
---|---|
ePay | Delivers payments methods: Dankort, Visa, MasterCard, MobilePay Online etc. (recently bought by Bambora) |
MobilePay | MobilePay Subscriptions |
Betalingsservice | Betalingsservice (Basis and Total Solution) |
LinkMobility | Delivers SMS payment method |
SMSCPH | Delivers SMS payment method |
Test | Used for testing purposes |
Log | Only used in Sandbox for testing purposes |
Payment Method Types
Payment Method | Description |
---|---|
Card | Single and Recurring payments via Dankort, Visa, MasterCard etc. |
MobilePayOnline | Single payments via MobilePay Online |
MobilePaySubscriptions | OneOff and Recurring payments via MobilePay Subscriptions |
Betalingsservice | Recurring payments via Betalingsservice, inclusive Payment Slips (Indbetalingskort) |
SMS | Single payments via SMS keywords |
Test | Single and Recurring payments as Test |
Log | Only used in Sandbox for testing purposes |
Payment Method Accounting Codes (examples)
Payment Method Accounting Code | Description |
---|---|
BetalingsserviceMandate | Betalingsservice by bank |
BetalingsservicePaymentSlip | Betalingsservice by payment slip (giro / FI-card) |
Dankort | Dankort |
Forbrugsforeningen | Forbrugsforeningen |
Maestro (foreign) | Maestro from countries other than Denmark |
Mastercard | Mastercard |
Mastercard (foreign) | Mastercard from countries other than Denmark |
MobilePay | MobilePay |
Visa | Visa |
Visa Electron | Visa Electron |
Visa/Dankort | Visa or Dankort |
Visa/Electron (foreign) | Visa/Electron from countries other than Denmark |
Payment Method States
Following is a list of Payment Method states with a state diagram below:
State | Description |
---|---|
New | A Payment Method that has been created, but not yet sent to the payment gateway. |
Pending | The request has been sent to chosen Payment Gateway |
SessionExpired | Used for MobilePay Subscriptions that was not accepted in time. |
Active | The Payment Method is active |
Expired | The Payment Method is expired. Primarily used for cards. |
Rejected | The Payment Method was rejected by the End User prior to activation. |
Cancelled | The Payment Method was cancelled by the End User or Merchant. |
Failed | The Payment Method reaches failed, if none of the above applies. |
Inactive | The Payment Method is inactive |
Payment Method State Diagram
Payment Method Error Codes and Descriptions
For further examples and ties to other entities, please see: Error and Cancel Codes
Error Code | Description | Examples | State |
---|---|---|---|
200001 | Payment Method signup failed | Invalid data provided for either National ID, Business Number, Sort Code or Account Number with Betalingsservice. | Failed |
200002 | Payment Method was rejected during sign up | Involves Debtor rejection of a request i.e. in a mobile app. | Rejected |
200003 | Payment Method signup expired | Debtor did not approve request in mobile app in time. | SessionExpired |
200004 | Payment Method has expired | Involves expiration of Card or requirement of new SCA. | Expired |
200005 | Payment Method has failed | Errors with the Gateway without options to retry or reactive. | Failed |
Payment Method Cancel Codes and Descriptions
For further examples and ties to other entities, please see: Error and Cancel Codes
Cancel Code | Description | State |
---|---|---|
200101 | Cancelled by Debtor | Cancelled |
200102 | Cancelled by Creditor | Cancelled |
200103 | Cancelled by System | Cancelled |
6.0 Payment
Properties
Name | Type | Example | Description |
---|---|---|---|
paymentGuid | STRING | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | Unique GUID |
createdTs | DATETIME | 2019-01-01 00:00:00 +0100 | Timestamp of Payment creation |
paymentType | STRING | Single | Please see list of Payment Types below |
contactGuid | STRING(64) | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | GUID of Contact |
amount | DOUBLE | 100.0 | Amount charged |
amountPaid | DOUBLE | 100.0 | The actual amount paid by the end user. It may diverse from amount on rare occasions. |
state | STRING | Charged | Please see list of Payment States below |
paymentMethodType | STRING | Please see list of Payment Method Types below | |
paymentRequired | BOOLEAN | false | Is the Payment required for the Subscription to be valid? |
taxDeductable | BOOLEAN | true | Defines basis for tax deductibility |
dueDateTs | DATETIME | 2019-01-01 00:00:00 +0100 | Timestamp of expected charge |
chargedTs | DATETIME | 2019-01-01 00:00:00 +0100 | Timestamp of successful charge |
failedTs | DATETIME | 2019-01-01 00:00:00 +0100 | Timestamp of charge failure |
rejectedTs | DATETIME | 2019-01-01 00:00:00 +0100 | Timestamp of charge rejection |
refundedTs | DATETIME | 2019-01-01 00:00:00 +0100 | Timestamp of successful refund |
cancelledTs | DATETIME | 2019-01-01 00:00:00 +0100 | Timestamp of cancellation |
errorCode | STRING | 10001 | Please see list of Payment Error Codes below |
errorDescription | STRING | This is a friendly description | User friendly description of the provided error |
currencyCode | STRING | DKK | ISO formatted Currency Code (wiki) |
paymentGatewayProvider | STRING | Betalingsservice | Please see list of Payment Gateway Providers below |
paymentGatewayReferenceId | STRING | Gateway reference GUID | |
paymentGatewayTransactionId | STRING | Gateway transaction ID (only relevant for ePay/Bambora) | |
metaData | JSON Object | Contains metadata such as card type, masked card number etc. | |
purposeAccountingCode | STRING(32) | A code that identifies the purpose of this agreement, with respect to accounting. | |
paymentMethodAccountingCode | STRING(32) | Accounting Code defined by Payment Method. Please see example list under Payment Method. | |
amountRefunded | DOUBLE | 0.0 | Amount refunded |
agreementGuid | STRING(64) | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | GUID of Agreement |
subscriptionGuid | STRING(64) | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | GUID of Subscription |
paymentMethodGuid | STRING(64) | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | GUID of Payment Method |
paymentSessionGuid | STRING(64) | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | GUID of Payment Session used internally to identify the initial payment session |
dataSetGuid | STRING(64) | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | A DataSet GUID containing metadata |
externalId | STRING | An external ID to eg. CRM | |
externalLink | STRING | An external URL to e.g. CRM |
GET /payments?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}&state={z}
Get a list of Payments with a given state, at a given size by a given offset and date limitation. All parameters are optional.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
{ "pageNumber": {x}, "pageSize": {y}, "startDate": {yyyy-mm-dd}, "endDate": {yyyy-mm-dd}, "list": [ { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ] }
GET /payments?search={paymentGatewayReferenceId}
Get an array of Payments by a given search string matching the paymentGatewayReferenceId.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
[ { "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /payment/{guid}
Get a single Payment.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Payment not found |
HTTP 200 Example
{ "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "createdTs": "2019-01-01 00:00:00 +0100", "paymentType": "", "contactGuid": "", "agreementGuid": "", "amount": 100.0, "taxDeductable": true, "state": "", "dueDateTs": "", "chargedTs": "", "failedTs": "", "errorCode": "", "errorDescription": "", "currencyCode": "DKK", "paymentGateway": "", "paymentGatewayReferenceId": "", "paymentGatewayTransactionId": "", "purposeAccountingCode": "", "paymentMethodAccountingCode": "", "amountRefunded": 0.0, "paymentMethodGuid": "", "subscriptionGuid": "", "paymentRequired": true, "paymentSessionGuid": "", "dataSetGuid": "", "externalLink": "", "metaData": { "card": { "type": "Dankort", "cardNumber": "457150XXXXXX7478", "acquirer": "Nets/Teller", "orderId": "4200xxxxx", "transactionId": "88821321" }, "bs": { "customerNumber": "605XXX", "mandate": "956964XXX", "ocr": "1231352356235", "dataSupplierReferenceId": "GSFDGSERG", "paymentSlipDispatchMethod": "195", "transactionCode": "297" }, "mps": { "externalId": "1568581537XXX" }, "sms": { "msisdn": "4512345678" } } }
GET /payment/{guid}/receipt
Get a single Payment's Receipt PLANNED
Response
HTTP | Description |
---|---|
200 | OK |
404 | Payment not found |
HTTP 200 Example
{ "receiptGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }
GET /payment/{guid}/transactions
Get a list of Transactions for a single Payment.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Payment not found |
HTTP 200 Example
[ { "transactionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "transactionType": "charge", "amount": 100.0, "...": "..." }, { "transactionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "transactionType": "refund", "amount": 100.0, "...": "..." } ]
GET /payment/{guid}/chargeAttempts
Get a list of Charge Attempts for a single Payment.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Payment not found |
HTTP 200 Example
[ { "chargeAttemptGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "chargeAttemptGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
GET /payment/{guid}/orderLines
Get a list of Order Lines for a single Payment PLANNED
Response
HTTP | Description |
---|---|
200 | OK |
404 | Payment not found |
HTTP 200 Example
[ { "orderLineGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "orderLineGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ]
PATCH /payment/{guid}
Update a single Payment using add, replace or remove operations.
Request
The following must be provided as the request body:
[ { "op": "add|replace|remove", "path": "/externalId", "value": "1001" } ]
Response
HTTP | Description |
---|---|
200 | OK |
400 | Something's wrong with request body. |
404 | Payment was not found |
POST /payment/{guid}/Refund
Refund a Payment.
Request
The following must be provided as the request body:
{ "amount": 100.0, "callbackUrl": "https://yourdomain.tld/" }
Response
HTTP | Description |
---|---|
202 | Accepted |
400 | Bad Request |
404 | Payment not found |
A callback is sent when the refund operation either fails or succeeds. Please see Refund for entity properties.
POST body example
{ "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "transactionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "refundGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx" }
POST /payment/{guid}/Cancel
Cancel a Pending Payment.
Response
HTTP | Description |
---|---|
202 | Accepted |
400 | Bad Request |
404 | Payment not found |
A callback is sent when the cancel operation either fails or succeeds.
Payment Gateway Providers
Payment Gateway Provider | Description |
---|---|
ePay | Delivers payments methods: Dankort, Visa, MasterCard, MobilePay Online etc. (recently bought by Bambora) |
MobilePay | MobilePay Subscriptions |
Betalingsservice | Betalingsservice (Basis and Total Solution) |
LinkMobility | Delivers SMS payment method |
SMSCPH | Delivers SMS payment method |
Test | Used for testing purposes |
Log | Only used in Sandbox for testing purposes |
Payment Types
Payment Type | Description |
---|---|
Single | A single Payment without connection to any Subscription |
Recurring | A recurring Payment adjacent to a Subscription |
OneOff | An initial Payment adjacent to a Subscription |
Payment Method Types
Payment Method | Description |
---|---|
Card | Single and Recurring payments via Dankort, Visa, MasterCard etc. |
MobilePayOnline | Single payments via MobilePay Online |
MobilePaySubscriptions | OneOff and Recurring payments via MobilePay Subscriptions |
Betalingsservice | Recurring payments via Betalingsservice, inclusive Payment Slips (Indbetalingskort) |
SMS | Single payments via SMS keywords |
Test | Single and Recurring payments as Test |
Log | Only used in Sandbox for testing purposes |
Payment States
Following is a list of Payment states:
State | Description | Release |
---|---|---|
Ready | Result from processing of a pending Subscription. | |
AwaitingRetry | Charge attempt failed. Will retry if possible. | |
AwaitingCharge | Charge attempt has been created, but not yet sent to Payment Gateway | |
Pending | Request sent to Payment Gateway. | |
SessionExpired | Payment is expired. Used for MobilePay Subscriptions one-off that was not accepted in time. | |
Charged | Payment was successfully charged. | |
Failed | Payment failed. | |
Rejected | Payment request was rejected by Contact. | |
Cancelled | Payment was cancelled by Merchant after the payment request is sent to Payment Gateway and prior to the expected due date with Payment Gateway limitations in mind. | |
Refunded | Payment was successfully refunded. |
Payment State Diagram for recurring payments
Payment State Diagram for single payments
Payment Cancel Codes
For further examples and ties to other entities, please see: Error and Cancel Codes
Error Code | Description | State |
---|---|---|
200101 | Cancelled by Debtor | Cancelled |
200102 | Cancelled by Creditor | Cancelled |
Payment Error Codes
For further examples and ties to other entities, please see: Error and Cancel Codes
Error Code | Description | Examples | State |
---|---|---|---|
200001 | Payment Method signup failed | Invalid data provided for either National ID, Business Number, Sort Code or Account Number with Betalingsservice. | Failed |
200002 | Payment Method was rejected during sign up | Involves Debtor rejection of a request i.e. in a mobile app. | Rejected |
200003 | Payment Method signup expired | Debtor did not approve request in mobile app in time. | SessionExpired |
200004 | Payment Method has expired | Involves expiration of Card or requirement of new SCA. | Expired |
200005 | Payment Method has failed | Errors with the Gateway without options to retry or reactive. | Failed |
7.0 Charge Attempt
Properties
Name | Type | Example | Description |
---|---|---|---|
chargeAttemptGuid | STRING | Unique GUID | |
createdTs | TIMESTAMP | Timestamp of Charge Attempt creation | |
paymentGuid | STRING | Unique GUID of Payment | |
paymentMethodGuid | STRING | Unique GUID of Payment Method | |
paymentGatewayGuid | STRING | Unique GUID of Payment Gateway | |
paymentGatewayProvider | STRING | Such as ePay, MobilePaySubscriptions, Betalingsservice, LinkMobility, Test | |
state | STRING | Current state of Charge Attempt | |
paymentGatewaySubscriptionReferenceId | STRING | Subscription token at Payment Gateway | |
paymentGatewayPaymentReferenceId | STRING | Payment token at Payment Gateway | |
attemptTs | TIMESTAMP | Timestamp of charge attempt | |
chargedTs | TIMESTAMP | Timestamp of successful charge | |
failedTs | TIMESTAMP | Timestamp of failure | |
rejectedTs | TIMESTAMP | Timestamp of Contact rejection | |
cancelledTs | TIMESTAMP | Timestamp of Merchant declination | |
expiredTs | TIMESTAMP | Timestamp of expiration | |
gatewayErrorCode | INTEGER | Error code from Payment Gateway. Please see: Error and Cancel Codes | |
gatewayErrorDescription | STRING | Error description from Payment Gateway. Please see: Error and Cancel Codes | |
rawErrorString | STRING | Uninterpreted error response provided by Payment Gateway |
8.0 Transaction
Properties
Name | Type | Example | Description |
---|---|---|---|
transactionGuid | STRING | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | Unique GUID |
createdTs | TIMESTAMP | Timestamp of Transaction creation | |
paymentGuid | STRING | Unique GUID of Payment | |
amount | DOUBLE | Transaction amount | |
paymentGatewayProvider | STRING | Such as ePay, MobilePaySubscriptions, Betalingsservice, LinkMobility, Test | |
paymentGatewayGuid | STRING | Unique GUID of Payment Gateway | |
paymentGatewaySubscriptionReferenceId | STRING | Subscription token at Payment Gateway | |
paymentGatewayPaymentReferenceId | STRING | Payment token at Payment Gateway | |
transactionTs | TIMESTAMP | Timestamp of transaction | |
transactionType | STRING | Charge, Refund | Type of transaction |
paymentMethodAccountingCode | STRING | Accounting Code defined by Payment Method | |
chargeAttemptGuid | STRING | Unique GUID of Charge Attempt | |
paymentMethodGuid | STRING | Unique GUID of Payment Method |
GET /transactions?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}
Get a list of Transactions at a given size by a given offset and date limitation.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
{ "pageNumber": {x}, "pageSize": {y}, "startDate": {yyyy-mm-dd}, "endDate": {yyyy-mm-dd}, "list": [ { "transactionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." }, { "transactionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "...": "..." } ] }
GET /transaction/{guid}
Get a single Transaction.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Transaction not found |
HTTP 200 Example
{ "transactionGuid": "8386b0c8-8210-4b12-a8df-xxxxxxxxxxxx", "merchantId": "merchant-name", "createdTs": "2020-01-10 14:51:23 +0100", "paymentGuid": "269916c5-bf4e-4fda-acf0-xxxxxxxxxxxx", "paymentMethodGuid": "24820946-9f48-4132-a8c5-xxxxxxxxxxxx", "chargeAttemptGuid": "d606d586-8abb-41d3-bbe0-xxxxxxxxxxxx", "amount": 100.0, "paymentGatewayProvider": "Test", "paymentGatewayGuid": "bfc19988-348d-4f40-b003-xxxxxxxxxxxx", "paymentGatewaySubscriptionReferenceId": "xxxxxxxxxxxx", "paymentGatewayPaymentReferenceId": "xxxxxxxxxxxx", "transactionTs": "2020-01-10 14:51:23 +0100", "transactionType": "Charge" }
9.0 Refund
Properties
Name | Type | Mandatory | Default | Example | Description |
---|---|---|---|---|---|
refundGuid | STRING | a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx | Unique GUID | ||
paymentGuid | STRING | Unique GUID of Payment | |||
transactionGuid | STRING | Unique GUID of Transaction | |||
createdTs | TIMESTAMP | Timestamp of Refund creation | |||
state | STRING | See list LIST | |||
paymentGateway | STRING | See list LIST | |||
amount | DOUBLE | Amount of be refunded | |||
refundedTs | TIMESTAMP | Timestamp of refunded amount | |||
failedTs | TIMESTAMP | Timestamp of failure |
GET /refund/{guid}
Get a single Refund.
Response
HTTP | Description |
---|---|
200 | OK |
404 | Refund not found |
HTTP 200 Example
{ "refundGuid": "", "paymentGuid": "", "transactionGuid": "", "createdTs": "", "state": "", "paymentGateway": "", "amount": "", "refundedTs": "", "failedTs": "" }
10.0 Webhooks
When the listed events are triggered a HTTP POST payload is sent to the configured webhook URL from IPs listed here: https://s3.eu-central-1.amazonaws.com/dk.onlinefundraising.info/webhooks.json
Please note that webhooks may be delivered twice in rare occasions, if connection problems, bad timings etc. is experienced. Please also see delivery attempts below.
Please also note webhooks currently can only be configured by sending an email to support@onlinefundraising.dk, including your webhook URL. Thanks
Event types
Below is a list of events triggering webhooks:
Entity | Event type | Description |
---|---|---|
contact | created | The Contact was created. |
updated | The Contact was updated. | |
archived | The Contact was archived. | |
merged | The Contact was merged into a target Contact. This callback will be sent for the Contact that is being archived. | |
agreement | created | The Agreement was created. |
updated | The Agreement was updated. | |
archived | The Agreement was archived. | |
paymentMethod | created | The Payment Method was created. |
activated | The Payment Method was accepted by Contact | |
updated | The Payment Method was updated by Merchant | |
rejected | The Payment Method was rejected by Contact | |
cancelled | The Payment Method was cancelled by Merchant or Contact | |
failed | The Payment Method failed. Please see error description | |
expired | The Payment Method expired | |
sessionExpired | The Payment Method was expired. Used for MobilePay Subscriptions one-off that was not accepted in time. | |
subscription | created | The Subscription was created. |
activated | The Subscription was set active. | |
updated | The Subscription was updated by Merchant. | |
expired | The Subscription period ended. | |
cancelled | The Subscription was cancelled by Merchant or Contact. | |
onHold | The Subscription was paused by Merchant. | |
restarted | The Subscription was restarted by Merchant. | |
payment | created | The Payment was created. |
charged | The Payment was charged. | |
sessionExpired | The Payment was expired. Used for MobilePay Subscriptions one-off that was not accepted in time. | |
rejected | The Payment was rejected by Contact. | |
cancelled | The Payment was cancelled by Merchant. | |
refunded | The Payment was refunded by Merchant. | |
failed | The Payment failed. | |
addOn | created | The AddOn was created. |
updated | The AddOn was updated. | |
cancelled | The AddOn was cancelled. | |
archived | The AddOn was archived. | |
dataSet | created | The DataSet was created. |
updated | The DataSet was updated. |
Webhook payload
One or more webhook objects may be delivered in a single request.
Example of POST delivery
[ { "merchantId": "fundraisingbureauet", "webhookEventGuid": "22ce6765-461f-4dd2-a3eb-xxxxxxxxxxxx", "webhookGuid": "592d0752-dfda-46b8-aeec-xxxxxxxxxxxx", "webhookAttemptGuid": "029b8cb0-9825-466d-a9db-xxxxxxxxxxxx", "entityGuid": "b1123c69-cb84-4adf-98cf-xxxxxxxxxxxx", "entityType": "contact", "eventType": "created" }, { "merchantId": "fundraisingbureauet", "webhookEventGuid": "a1dfb689-3273-49b7-9f5f-xxxxxxxxxxxx", "webhookGuid": "07a05b9b-a699-4bee-9afe-xxxxxxxxxxxx", "webhookAttemptGuid": "89efde72-4c01-4dd7-89c6-xxxxxxxxxxxx", "entityGuid": "8e449c62-9b9d-4776-a2da-xxxxxxxxxxxx", "entityType": "payment", "eventType": "updated" } ]
Webhook delivery attempts
Should your integration not respond or respond with a HTTP code other than 200 OK we will resend the webhook by an exponential backoff algorithm with the following seconds interval per attempt:
10
1800
3600
5400
7200
9000
10800
12600
14400
16200
11.0 ChangeLog
ChangeLogs can be of the following types:
Contact
Subscription
Agreement
AddOn
Properties
Name | Type | Example | Description |
---|---|---|---|
changeGuid | STRING(64) | c003d62e-b13b-4651-9b7b-xxxxxxxxxxxx | Unique GUID |
createdTs | TIMESTAMP | Timestamp of ChangeLog creation | |
entityType | ENUM | Contact | The type of entity that has been changed. |
entityGuid | STRING(64) | bd63f62e-d55a-4651-9b7b-xxxxxxxxxxxx | Unique GUID of the entity that has been changed |
changeTs | TIMESTAMP | Timestamp of when the entity was changed | |
oldEntityJson | JSON | JSON representation of the entity before any of the changes were applied to it | |
changeDescription | STRING | “Subscription processed” | Textual description of the change |
changeMetaData | JSON | Meta data of changes | |
requester | STRING | “individual@your-ngo.org” or “API” | Description of the person or system that triggered the change. |
requesterIp | STRING | 18.195.xx.xxx | The IP address of whomever responsible for triggering the change. |
systemRequest | BOOLEAN | Boolean denoting whether the change was triggered by OnlineFundraising | |
keysOnly | BOOLEAN | Boolean denoting whether only the keys of an entity should be logged. Utilized when anonymizing contacts. | |
changes | JSON | JSON representation of the changes that were applied to the entity. Only contains the fields that were changed. Has data on both the old and new values. |
Endpoints
For each entity type that supports logging changes there exist an endpoint for which the ChangeLogs of a specific entity can be retrieved.
Entity | Operation | Endpoint | QueryParam (Optional) |
---|---|---|---|
Contact | GET | https://payment.api.v3.onlinefundraising.dk/contact/{contactGuid}/log | ?limit=x |
Subscription | GET | https://payment.api.v3.onlinefundraising.dk/subscription/{subscriptionGuid}/log | ?limit=x |
Agreement | GET | https://payment.api.v3.onlinefundraising.dk/agreement/{agreementGuid}/log | ?limit=x |
By specifiying the query parameter “limit” it can be controlled how many ChangeLogs to retrieve. Default is no limit. ChangeLogs are returned sorted with the most recent first.
Response
HTTP | Description |
---|---|
200 | OK |
HTTP 200 Example
[ { "changeGuid": "16b48073-xxxx-xxxx-xxxx-0a337c4ba4dc", "createdTs": "2021-04-23 10:26:07 +0200", "entityType": "Subscription", "entityGuid": "1222ac4a-xxxx-xxxx-xxxx-bb9df2b9ab53", "changeTs": "2021-04-23 10:26:07 +0200", "oldEntityJson": "{\"subscriptionGuid\":\"1222ac4a-xxxx-xxxx-xxxx-bb9df2b9ab53\",\"merchantId\":\"your-ngo\", ...}", "changeDescription": "Cancel subscription", "changeMetaData": "{}", "requester": "individual@your-ngo.org", "systemRequest": false, "changes": [ { "newValue": 100102, "fieldName": "cancelCode" }, { "newValue": "anden årsag", "fieldName": "cancelDescription" }, { "newValue": "2021-04-23 10:26:06 +0200", "fieldName": "cancelledTs" }, { "newValue": "2021-04-23 10:26:06 +0200", "fieldName": "inactivatedTs" }, { "newValue": "Inactive", "oldValue": "Active", "fieldName": "state" } ], "keysOnly": false, "requesterIp": "18.195.xx.xxx" } ]