Payment API

Contact

API Documentation

Senest redigeret:

Introduction

A Contact represents the individual with whom we are dealing with and can either be a person or a business.

Changes committed to a Contact can be retrieved via the ChangeLog entity.

Endpoints

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": 1,
  "pageSize": 50,
  "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 a 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"
      }
    ]
  }
]

Schema

Property Format and Description
contactGuid string <uuid>

Unique Guid

merchantId string

Unique ID of merchant

name string

The full name of the Contact

birthDate string <yyyy-MM-dd>

Date of birth

nationalId string

National ID (i.e. CPR in Denmark provided without dashes)

address string

Address line 1

address2 string

Address line 2

postCode string

Postal code

city string

City

countryCode string

ISO formatted Country Code

msisdn string

Phone with Country Code consisting of 1-3 digits reserved for country code without prefixes, such as 00.

email string

Email of the contact

firstName string

First name of the contact

lastName string

Last name of the contact

companyName string

Company name

businessCode string

Business Code (i.e. VAT, CVR in Denmark)

contactType string

Type of Contact. Please note the value is not restricted to the examples given, however our form field will use these.

Enum: "individual", "business"
createdTs string <yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of creation

updatedTs string <yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of update

anonymizedTs string <yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of anonymization

archivedTs string <yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of archivation

externalId string

An external ID as provided by merchant

externalLink string

An external URL to e.g. CRM

originTs string <yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of origin, useful when importing data (e.g. if originated in external system)

mergeTargetGuid string <uuid>

Unique Guid of merge target

mergeTs string <yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of merge

 

Example

{
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"merchantId": "your-merchant",
"name": "John Doe",
"birthDate": "2019-12-31",
"nationalId": "061221xxxx",
"address": "Finsensvej 6E, 2.",
"address2": null,
"postCode": 1500,
"city": "Frederiksberg",
"countryCode": "DK",
"msisdn": 4535294855,
"email": "support@onlinefundraising.dk",
"firstName": "Jane",
"lastName": "Doe",
"companyName": "OnlineFundraising ApS",
"businessCode": 37273457,
"contactType": "business",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"anonymizedTs": "2019-12-31 15:59:59 +0100",
"archivedTs": "2019-12-31 15:59:59 +0100",
"externalId": "some-id",
"externalLink": "string",
"originTs": "2019-12-31 15:59:59 +0100",
"mergeTargetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"mergeTs": "2019-12-31 15:59:59 +0100"
}

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