Skip to content

Instantly share code, notes, and snippets.

@dobromir-bogatev

dobromir-bogatev/apiary.md

Created September 28, 2017 10:52
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save dobromir-bogatev/7ab8de885c1433764ba575dc9cf64a2b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save dobromir-bogatev/7ab8de885c1433764ba575dc9cf64a2b to your computer and use it in GitHub Desktop.
Download ZIP
Raw
apiary.md

FORMAT: 1A HOST: https://api.ecollect.org/

eCollect

The easiest way to start collecting with eCollect is to integrate with our RESTful API. The API allows you to create and update new customers, submit claims as well as payments, upload and download documents and send and retrieve messages.

To make our API as explorable as possible, accounts have test mode and live mode API keys. There are no different endpoints for live mode and test mode, just use the appropriate key to perform live or test transactions. Requests made with test credentials do not create customers or claims in the Live-environment.

 

API Endpoint:

https://api.ecollect.org/v2

 

 

Definitions

Customer

Claim

File

Payment

Refund

Message

Document

Event

Account

Statement

Authentication

Before transmitting any data to the eCollect API, you will need to authenticate yourself with your secret API key.

We are working with different Webtokens. A token consists of three parts separated by dots (.), which are:

Header

Payload

Signature

 

The Token consists of

  • Username

  • Password

  • Serial

  • Environment

 

The output is three Base64 strings separated by dots that can be easily be passed in HTML and HTTP environments, while being more compact when compared to XML-based standards such as SAML.

You will find your personal keys in your https://manage.ecollect.org account preferences. All API requests must be HTTPS. Calls made over plain HTTP or without authentification will fail.

You can manage your API keys in your account preferences. There is one key for our live-system and one for our test-system. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys externally or outside key stakeholders within your business.

The API uses conventional HTTP codes to respond to your API request. You will find different codes to indicate the success or failure of your request.

Errors

Response
200 Everything is fine!
400 Errors occured: Please check the Error-enum for further details.
401 Authorization failed.
404 The requested URL was not found.
500 The server encountered an error processing your request.
501 The requested method is not implemented.

Webhooks

Webhooks are custom HTTP callbacks from the eCollect system to any URL you specify. They are initiated in the moment the specific event occurs.

  • Events (payments + basically all communication events between eCollect and your customer)

  • Status changes/updates of claims & customers

  • Messages

  • Documents

  • Balance postings

  • Statements

If you need help to implement our webhooks, please get in touch.

https://en.wikipedia.org/wiki/Webhook

Expanding Objects

Some objects contain the ID of a related object in their response properties. For example, a event may have an associated customer ID. Those objects can be expanded inline with the expand request parameter. This parameter is available on all GET API requests, and applies to the response of that request only.

You can expand multiple objects at once by identifying multiple items in the expand array.

Example:

In the example your response contains the complete customer and file objects instead of the IDs.

/v2/statements/sta_*********?expand[]=customer&expand[]=file

Group Customers

The customer object represents the key object in eCollect's system, the customer. Creating a customer allows you to submit claims, credits, payments, messages and documents. The customer object has multiple child objects. The customer can be either a person or an organisation. The eCollect API allows you to create and update your customers. You can retrieve individual customers as well as a list of all your customers.

The customer object [/v2/customers]

  • Attributes
    • customer (CUSTOMER-RESPONSE)

Create a customer [POST]

  • Request (application/json)

    • Attributes (CUSTOMER)

  • Response 200 (application/json)

    • Attributes (CUSTOMER-RESPONSE)

Retrieve a customer [GET /v2/customers/{id}]

  • Parameters

    • id: cus_u7r7Reo1c (required)

  • Response 200 (application/json)

    • Attributes (CUSTOMER-RESPONSE)

List customers [GET /v2/customers?customer.id={customer.id}&customer.your_reference={customer.your_reference}&limit={limit}&offset={offset}]

  • Parameters

    • customer.id: cu_u7r7Reo1c (optional, string)
    • customer.your_reference: 12345678 (optional, string)
    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[CUSTOMER-RESPONSE])

Update a customer [/v2/customers/{id}]

In order to update a customer you can add additional information like metadata or contacts. The response includes alyways the complete customer object.

Add metadata to a customer [POST /v2/customers/{id}/metadata]

  • Parameters

    • id: cus_u7r7Reo1c (required)

  • Request (application/json)

    • Attributes (CUSTOMERMETADATA)

  • Response 200 (application/json)

    • Attributes (CUSTOMER-RESPONSE)

Add a address to a customer [POST /v2/customers/{id}/addresses]

  • Parameters

    • id: cus_u7r7Reo1c (required)

  • Request (application/json)

    • Attributes (ADDRESS)

  • Response 200 (application/json)

    • Attributes (CUSTOMER-RESPONSE)

Add a contact to a customer [POST /v2/customers/{id}/contacts]

  • Parameters

    • id: con_u7r7Reo1c (required)

  • Request (application/json)

    • Attributes (CONTACT)

  • Response 200 (application/json)

    • Attributes (CUSTOMER-RESPONSE)

Add a relation to a customer [POST /v2/customers/{id}/relations]

  • Parameters

    • id: cus_u7r7Reo1c (required)

  • Request (application/json)

    • Attributes (RELATION)

  • Response 200 (application/json)

    • Attributes (CUSTOMER-RESPONSE)

Group Claims

The claim object [/v2/claims]

  • Attributes (CLAIM-RESPONSE)

Create a claim [POST]

  • Request (application/json)

    • Attributes (CLAIM)

  • Response 200 (application/json)

    • Attributes (CLAIM-RESPONSE)

Retrieve a claim [GET /v2/claims/{id}]

  • Parameters

    • id: cla_e7p1R1o1c (required)

  • Response 200 (application/json)

    • Attributes (CLAIM-RESPONSE)

Retrieve all claims [GET /v2/claims?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[CLAIM-RESPONSE])

Update a claim [/v2/claims/{id}]

In order to update a claim you can add payments and refunds. The response includes alyways the complete claim object.

Add metadata to a claim [POST /v2/customers/{id}/metadata]

  • Parameters

    • id: cla_e7p1R1o1c (required)

  • Request (application/json)

    • Attributes (CLAIMMETADATA)

  • Response 200 (application/json)

    • Attributes (CLAIM-RESPONSE)

Add payment to a claim [POST /v2/claims/{id}/payments]

  • Parameters

    • id: cla_e7p1R1o1c (required)

  • Request (application/json)

    • Attributes (PAYMENT)

  • Response 200 (application/json)

    • Attributes (CLAIM-RESPONSE)

Add refund to a claim [POST /v2/claims/{id}/refunds]

  • Parameters

    • id: cla_e7p1R1o1c (required)

  • Request (application/json)

    • Attributes (REFUND)

  • Response 200 (application/json)

    • Attributes (CLAIM-RESPONSE)

Add event to a claim [POST /v2/claims/{id}/events]

  • Parameters

    • id: cla_e7p1R1o1c (required)

  • Request (application/json)

    • Attributes (EVENT)

  • Response 200 (application/json)

    • Attributes (EVENT-RESPONSE)

Group Files

The file object [/v2/files]

  • Attributes (FILE-RESPONSE)

Retrieve a file [GET /v2/files/{id}]

  • Parameters

    • id: file_a1p1v114c (required)

  • Response 200 (application/json)

    • Attributes (FILE-RESPONSE)

Retrieve all files [GET /v2/files?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[FILE-RESPONSE])

Group Payments

Payment objects allow you to submit and retrieve the information about incoming payments. It can be used to:

  • Submit previously received payments (partial payments) for one or more claims while you create a new delivery

  • Submit the information that you received a payment made for a claim that has previously been submitted to eCollect

  • Retrieve the information of incoming customer payments from eCollect

The payment object [/v2/payments]

  • Attributes (PAYMENT-RESPONSE)

Retrieve a payment [GET /v2/payments/{id}]

  • Parameters

    • id: pay_17p1R1o1c (required)

  • Response 200 (application/json)

    • Attributes (PAYMENT-RESPONSE)

Retrieve all payments [GET /v2/payments?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[PAYMENT-RESPONSE])

Group Refunds

Credit refunds allow you to credit claims that have been previously submitted to eCollect.

The refund object [/v2/refunds]

  • Attributes (REFUND-RESPONSE)

Retrieve a refund [GET /v2/refunds/{id}]

  • Parameters

    • id: ref_27pbR1o1c (required)

  • Response 200 (application/json)

    • Attributes (REFUND-RESPONSE)

Retrieve all refunds [GET /v2/refunds?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[REFUND-RESPONSE])

Group Messages

The message object is designed to exchange customer and/or claim related information between eCollect and the creditor. Messages can contain documents.

The message object [/v2/message]

  • Attributes (MESSAGE-RESPONSE)

Create a message [POST]

  • Attributes (MESSAGE)

  • Response 200 (application/json)

    • Attributes (MESSAGE-RESPONSE)

Retrieve a message [GET /v2/messages/{id}]

  • Parameters

    • id: mes_4rftOgaeR (required, string)

  • Response 200 (application/json)

    • Attributes (MESSAGE-RESPONSE)

Retrieve all messages [GET /v2/messages?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[MESSAGE-RESPONSE])

Group Documents

Document objects allow you to exchange documents files with eCollect. Files can be related to customers as well as principal claims, additional charges, credits, payments and messages. The API allows you to create and retrieve documents. You can retrieve individual documents as well as a list of all documents. We deliver and accept .PDF files and various image file formats such as .JPG and .PNG.

The document object [/v2/documents]

  • Attributes (DOCUMENT-RESPONSE)

Create a document [POST /v2/documents]

  • Attributes (DOCUMENT)

    • document (DOCUMENT)

  • Response 200 (application/json)

    • Attributes (DOCUMENT-RESPONSE)

Retrieve a document [GET /v2/documents/{id}]

  • Parameters

    • id: doc_******** (required, string)

  • Response 200 (application/json)

    • Attributes (DOCUMENT-RESPONSE)

List all documents [GET /v2/documents?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes
      • number_found: 1 (number)
      • results (array[DOCUMENT-RESPONSE])

Group Notifications

The notification object [/v2/notifications]

  • Attributes (NOTIFICATION-RESPONSE)

Retrieve a notification [GET /v2/notifications/{id}]

  • Parameters

    • id: ntf_54pbR1o1c (required)

  • Response 200 (application/json)

    • Attributes (NOTIFICATION-RESPONSE)

Retrieve all notifications [GET /v2/notifications?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[NOTIFICATION-RESPONSE])

Group Account

The account and the transaction object [/v2/account]

  • Attributes (ACCOUNT-RESPONSE)

Retrieve account summary [GET /v2/account]

  • Response 200 (application/json)
    • Attributes (ACCOUNT-RESPONSE)

Retrieve a transaction [GET /v2/account/transactions/{id}]

  • Parameters

    • id: tra_14pbR1o1c (required)

  • Response 200 (application/json)

    • Attributes (TRANSACTION-RESPONSE)

Retrieve all transactions [GET /v2/account/transactions?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[TRANSACTION-RESPONSE])

Group Statements

The statement object [/v2/statements]

  • Attributes (STATEMENT-RESPONSE)

Retrieve a statement [GET /v2/statements/{id}]

  • Parameters

    • id: sta_94pbM1o1c (required)

  • Response 200 (application/json)

    • Attributes (STATEMENT-RESPONSE)

Retrieve all statements [GET /v2/statements?limit={limit}&offset={offset}]

  • Parameters

    • limit: 100 (optional, number)
    • offset: 0 (optional, number)

  • Response 200 (application/json)

    • Attributes (object)
      • number_found: 1 (number)
      • results (array[STATEMENT-RESPONSE])

Data Structures

CUSTOMER-RESPONSE (object)

  • id: cus_******** (string) - Our unique identifier of the customer.
  • object: customer (string) - Value is customer.
  • creation: 2016-09-01 12:22:11 (string) - The creation datetime of the customer.
  • your_reference: 123456789 (string) - Your customer reference, if available.
  • ecollect_reference: 123456789 (string) -
  • metadata (array[CUSTOMERMETADATA-RESPONSE]) - The metadata object allows you to submit additional relevant information related to the customer as type/value pairs. You can submit an unlimited number of metadata sets.
  • entity (ENTITY-RESPONSE)

CUSTOMER (object)

  • your_reference: 123456789 (required, string) - Your customer reference, if available.
  • metadata (array[CUSTOMERMETADATA]) - The metadata object allows you to submit additional relevant information related to the customer as type/value pairs. You can submit an unlimited number of metadata sets.
  • entity (ENTITY)

ENTITY-RESPONSE (object)

  • person (PERSON-RESPONSE) - If entity is a person / individual. A entity can be either a person or an organisation. The set of personal data used by eCollect is guided by the international standards for Machine-readable passports.
  • organisation (ORGANISATION-RESPONSE) - If entity is an organisation (e.g. company). A entity can be either a person or an organisation.
  • addresses (array[ADDRESS-RESPONSE]) - The address information of the customer contains different attributes, e.g. address lines for street names and numbers, zip codes and cities. You can submit an unlimited number of addresses.
  • contacts (array[CONTACT-RESPONSE]) - The contact object allows you to submit various contact records of the costumer, e.g. phone numbers, eMail adresses, website URLs, messenger IDs, social media profiles. You can submit an unlimited number of contact records.
  • bank_accounts (array[BANKACCOUNT-RESPONSE]) -
  • relations (array[RELATION-RESPONSE]) -

ENTITY (object)

  • person (PERSON) - If entity is a person / individual. A entity can be either a person or an organisation. The set of personal data used by eCollect is guided by the international standards for Machine-readable passports.
  • organisation (ORGANISATION) - If entity is an organisation (e.g. company). A entity can be either a person or an organisation.
  • addresses (array[ADDRESS]) - The address information of the customer contains different attributes, e.g. address lines for street names and numbers, zip codes and cities. You can submit an unlimited number of addresses.
  • contacts (array[CONTACT]) - The contact object allows you to submit various contact records of the costumer, e.g. phone numbers, eMail adresses, website URLs, messenger IDs, social media profiles. You can submit an unlimited number of contact records.
  • bank_accounts (array[BANKACCOUNT]) -
  • relations (array[RELATION]) -

RELATION-RESPONSE (object)

  • creation: 2016-09-01 12:22:11 (string) - The creation datetime of the relation.
  • relationTypes: (required, array[RELATION-TYPE]) -
  • entity: (object)
    • person (PERSON-RESPONSE) - If entity is a person / individual. A entity can be either a person or an organisation. The set of personal data used by eCollect is guided by the international standards for Machine-readable passports.
    • organisation (ORGANISATION-RESPONSE) - If entity is an organisation (e.g. company). A entity can be either a person or an organisation.
    • addresses (array[ADDRESS-RESPONSE]) - The address information of the customer contains different attributes, e.g. address lines for street names and numbers, zip codes and cities. You can submit an unlimited number of addresses.
    • contacts (array[CONTACT-RESPONSE]) - The contact object allows you to submit various contact records of the costumer, e.g. phone numbers, eMail adresses, website URLs, messenger IDs, social media profiles. You can submit an unlimited number of contact records.
    • bank_accounts (array[BANKACCOUNT-RESPONSE]) -

RELATION (object)

  • relationTypes: (required, array[RELATION-TYPE]) -

  • entity: (object)

    • person (PERSON) - If entity is a person / individual. A entity can be either a person or an organisation. The set of personal data used by eCollect is guided by the international standards for Machine-readable passports.
    • organisation (ORGANISATION) - If entity is an organisation (e.g. company). A entity can be either a person or an organisation.
    • addresses (array[ADDRESS]) - The address information of the customer contains different attributes, e.g. address lines for street names and numbers, zip codes and cities. You can submit an unlimited number of addresses.
    • contacts (array[CONTACT]) - The contact object allows you to submit various contact records of the costumer, e.g. phone numbers, eMail adresses, website URLs, messenger IDs, social media profiles. You can submit an unlimited number of contact records.
    • bank_accounts (array[BANKACCOUNT]) -

RELATION-TYPE (object)

  • type: is:boardMember-of:organisation (enum) -
    • is:boardMember-of:organisation
    • is:chairman-of:organisation
    • is:executive-of:organisation
    • is:managingDirector-of:organisation
    • is:procurator-of:organisation
    • is:shareholder-of:organisation
    • is:beneficialOwner-of:organisation
    • is:generalPartner-of:generalPartner
    • is:generalPartner-of:limitedPartner
    • is:limitedPartner-of:limitedPartner
    • is:employer-of:employee
    • is:member-of:organisation
    • is:lawyer-of:client
    • is:consumerProtector-of:client
    • is:debtAdvisor-of:client
    • is:insolvencyAdministrator-of:insolvencyDebtor
    • is:interpreter-of:client
    • is:spouse-of:spouse
    • is:divorcee-of:divorcee
    • is:parent-of:child
    • is:grandparent-of:grandchild
    • is:sibling-of:sibling
    • is:relative-of:relative
    • is:lifePartner-of:lifePartner

PERSON-RESPONSE (object)

  • given_names: John Alan (string) - First name(s) / Given name(s) of the person.
  • surname: Doe (string) - Last name / Surname of the person.
  • sex: m (enum) - Sex, please use u if the sex of the person is unknown.
    • m
    • f
    • x
    • u
  • title: Dr. (string) - The title of the person, if applicable (e.g. titles of nobility, professional titles / academic degrees, honours and decorations).
  • date_of_birth: 1970-01-01 (string) - Date of birth of the person.
  • place_of_birth: Zürich (string) - Place of birth of the person.
  • nationality: CH (string) - The country of residence of the person. The format must be ISO-3166-1 alpha-2 standard.
  • country_of_residence: CH (string) - The country of residence of the person. The format must be ISO-3166-1 alpha-2 standard.
  • acting_as: consumer, business (enum) - + Default: consumer

PERSON (object)

  • given_names: John Alan (required, string) - First name(s) / Given name(s) of the person.
  • surname: Doe (required, string) - Last name / Surname of the person.
  • sex: m (required, enum) - Sex, please use u if the sex of the person is unknown.
    • m
    • f
    • x
    • u
  • title: Dr. (string) - The title of the person, if applicable (e.g. titles of nobility, professional titles / academic degrees, honours and decorations).
  • date_of_birth: 1970-01-01 (string) - Date of birth of the person.
  • place_of_birth: Zürich (string) - Place of birth of the person.
  • nationality: CH (string) - The country of residence of the person. The format must be ISO-3166-1 alpha-2 standard.
  • country_of_residence: CH (string) - The country of residence of the person. The format must be ISO-3166-1 alpha-2 standard.
  • acting_as: consumer, business (enum) - + Default: consumer

ORGANISATION-RESPONSE (object)

  • name: ACME International (string) - Legal name of the organisation, in most cases a company. We expect the legal name WITHOUT the type of legal entity / legal form.
  • type: Inc. (string) - The type of legal entity / legal form of the organisation (e.g. CIC, Ltd., PLC, AG, GmbH, e.V.).
  • acting_as: business, consumer (enum) - + Default: business

ORGANISATION (object)

  • name: ACME International (required, string) - Legal name of the organisation, in most cases a company. We expect the legal name WITHOUT the type of legal entity / legal form.
  • type: Inc. (string) - The type of legal entity / legal form of the organisation (e.g. CIC, Ltd., PLC, AG, GmbH, e.V.).
  • acting_as: business, consumer (enum) - + Default: business

ADDRESS-RESPONSE (object)

  • id: add_******** - Our unique identifier of the address.
  • creation: 2016-09-01 12:22:11 (string) - The creation datetime of the address.
  • address_line1: 123 McLean Avenue (string) - Street name and number of the address.
  • address_line2: Apt 2B (string) - Address line 2 of the address.
  • address_line -n (string) - Additional lines, there are no limitations by quantity.
  • district: Staten Island (string) - District of the address.
  • zip: 10311 (string) - ZIP code (postal code) of the address.
  • city: New York (string) - City or town of the address.
  • state: NY (string) - Federated entity of the address (State, Canton, Province, Bundesland, etc.)
  • country: US (string) - The country of the address. The format must be ISO-3166-1 alpha-2 standard.
  • type: not_specified (enum) - The type of the address record.
    • Default: not_specified
    • not_specified -
    • billing -
    • mailing -
    • delivery -
    • residence -

ADDRESS (object)

  • address_line1: 123 McLean Avenue (required, string) - Street name and number of the address.
  • address_line2: Apt 2B (string) - Address line 2 of the address.
  • address_line -n: (string) - Additional lines, there are no limitations by quantity.
  • district: Staten Island (string) - District of the address.
  • zip: 10311 (required, string) - ZIP code (postal code) of the address.
  • city: New York (required, string) - City or town of the address.
  • state: NY (string) - Federated entity of the address (State, Canton, Province, Bundesland, etc.)
  • country: US (required, string) - The country of the address. The format must be ISO-3166-1 alpha-2 standard.
  • type: not_specified (enum) - The type of the address record.
    • Default: not_specified
    • not_specified -
    • billing -
    • mailing -
    • delivery -
    • residence -

CONTACT-RESPONSE (object)

  • id: con_******** (string) - Our unique identifier of the customer's contact record.
  • creation: 2016-09-01 12:22:11 (string) - The creation datetime of the contact record.
  • type: phone (enum) - The type of the contact record.
    • phone - Phone numbers
    • cellphone - Cellphone numbers
    • fax - Fax numbers
    • email - eMail addresses
    • skype - Skype IDs
    • facebook_messenger - Facebook Messenger IDs
    • imessage -
    • whatsapp -
    • viber -
    • facebook -
    • google+ -
    • twitter -
    • linkedin -
    • xing -
    • badoo -
    • social_various -
    • website_url -
    • web_various - Various websites containing contact details of the customer.
  • value: +41 41 12345678 (string) - The contact record.

CONTACT (object)

  • type: phone (required, enum) - The type of the contact record.
    • phone - Phone numbers
    • cellphone - Cellphone numbers
    • fax - Fax numbers
    • email - eMail addresses
    • skype - Skype IDs
    • facebook_messenger - Facebook Messenger IDs
    • imessage -
    • whatsapp -
    • viber -
    • facebook -
    • google+ -
    • twitter -
    • linkedin -
    • xing -
    • badoo -
    • social_various -
    • website_url -
    • web_various - Various websites containing contact details of the customer.
  • value: +41 41 12345678 (required, string) - The contact record.

BANKACCOUNT-RESPONSE (object)

  • id: bank_******** (string) - Our unique identifier of the bank account.
  • creation: 2016-09-01 12:22:11 (string) - The creation datetime of the bank account.
  • account_holder: eCollect AG (string) - The name of the bank account holder.
  • account_currency: EUR (string) - Currency of the bank account, according to ISO 4217.
  • iban: CH7304835162326942000` (string) - The IBAN of the bank account. It consists of: country code, control number, clearing number and account number.
  • bicswift: CRESCHZZ80A (string) - The BIC / Swift identifier of the bank account.
  • account_number: 1623269-42 (string) - The account number of the bank account.
  • clearing_number: 4835 (string) - The clearing number of the bank.
  • bank_country: CH (string) - We expect ISO-3166-1 alpha-2 standard.
  • bank_name: CREDIT SUISSE (Schweiz) AG (string) - The full legal name of the bank.
  • bank_address (ADDRESS-RESPONSE)

BANKACCOUNT (object)

  • account_holder: eCollect AG (required, string) - The name of the bank account holder.
  • account_currency: EUR (required, string) - Currency of the bank account, according to ISO 4217
  • iban: CH7304835162326942000 (required, string) - The IBAN of the bank account. It consists of: Country Code, Control number, Clearing Number, Account Number.
  • bicswift: CRESCHZZ80A (required, string) - The BIC of the bank account.
  • account_number: 1623269-42 (string) - Number of the bank account
  • clearing_number: 4835 (string) - Clearing number of the bank
  • bank_country: CH (required, string) - We expect ISO-3166-1 alpha-2 standard
  • bank_name: CREDIT SUISSE (Schweiz) AG (string) - The full legal name of the bank.
  • bank_address (ADDRESS)

AUTHORITYID (object)

CUSTOMERMETADATA-RESPONSE (object)

  • object: metadata
  • creation:2016-09-01 12:22:11 - Creation DateTime of the customer_metadata at eCollect
  • type: customer:reference (enum) - The type of additional information related to the customer.
    • customer:reference
    • user:reference
    • user:name
  • value: C-00001234 (string) - The actual data corresponding to the metadata type.

CUSTOMERMETADATA (object)

  • type: customer:reference (required, enum) - The type of additional information related to the customer.
    • customer:reference
    • user:reference
    • user:name
  • value: C-00001234 (required, string) - The actual data corresponding to the metadata type.

CLAIM-RESPONSE (object)

  • id: cla_******* (string)
  • object: claim (string)
  • your_reference: 123456789 (string) - Your unique reference of the claim
  • ecollect_reference: 123456789 (string) - eCollect's unique reference of the claim
  • creation: 2016-09-01 12:22:11 - Creation Datetime of the claim at eCollect
  • file: file_******* (string) - The unique identifier of the file the claim is bundled into in the eCollect System.
  • customer: cus_******** (string) - eCollect's unique identifier of the customer the claim is related to.
  • currency: EUR (string) - Currency of the claim, according to ISO 4217
  • amount: 123.45 (number) - Total amount of the principal claim including VAT or sales tax. Please use the following format: positive numeric characters, 2 decimals. Separating character is a dot.
  • occurrence_date: 2016-03-02 (string) - The date of emergence of the principal claim. It can be a the date when a contract with the customer came into force or the date of the delivery of goods or the date when services had been rendered. Please use the format YYYY—MM-DD.
  • due_date: 2016-02-01 (string) - The due date of the claim in format YYYY—MM-DD.
  • subject_matter_of_claim: Purchase from greatstuff.com, Invoice N° 123456 (string) - A detailed description of the delivery or service. Examples: “Purchase from greatstuff.com, Invoice N° 123456” or “Monthly subscription fee bestdateever.com - Premium account, September 2016”
  • contractual_item (enum) - The contractual item upon which the legal relationship between you (the creditor) and your customer is based.
    • medical_care - Medical care
    • service_agreement - Service agreement
    • loan_repayment - Loan repayment
    • tradesmens_services - Tradesmen's services
    • purchase_agreement - Purchase agreement
    • leasing_agreement - Leasing agreement
    • rental_agreement - Rental agreement
    • delivery_of_goods - Delivery of goods
    • contract_for_work - Labour Contract
    • interest - Interest in arrears
  • quality: regular (enum) - Describes the quality of the claim.
    • regular
    • special
    • second_placement
    • third_placement
  • metadata (array[CLAIMMETADATA-RESPONSE]) - The metadata object allows you to submit additional relevant information related to the claim as type/value pairs.
  • additional_charges (array[ADDITIONALCHARGE-RESPONSE])
  • refunds (array[REFUND-RESPONSE])
  • payments (array[PAYMENT-RESPONSE])
  • notifications (array[NOTIFICATION-RESPONSE])
  • messages (array[MESSAGE-RESPONSE])
  • documents (array[DOCUMENT-RESPONSE])

CLAIM (object)

  • your_reference: 123456789 (string) - Your unique reference of the claim. It is not required to submit a reference for the claim, but we strongly recommend to do so.
  • customer: cus_******** (required, string) - eCollect's unique identifier of the customer the claim is related to.
  • currency: EUR (required, string) - Currency of the claim, according to ISO 4217
  • amount: 123.45 (required, number) - Total amount of the principal claim including VAT or sales tax. Please use the following format: positive numeric characters, 2 decimals. Separating character is a dot.
  • occurrence_date: 2016-03-02 (required, string) - The date of emergence of the principal claim. It can be a the date when a contract with the customer came into force or the date of the delivery of goods or the date when services had been rendered. Please use the format YYYY—MM-DD.
  • due_date: 2016-02-01 (required, string) - The due date of the claim in format YYYY—MM-DD.
  • subject_matter_of_claim: Purchase from greatstuff.com, Invoice N° 123456 (required, string) - A detailed description of the delivery or service. Examples: “Purchase from greatstuff.com, Invoice N° 123456” or “Monthly subscription fee bestdateever.com - Premium account, September 2016”
  • contractual_item (required, enum) - The contractual item upon which the legal relationship between you (the creditor) and your customer is based.
    • medical_care - Medical care
    • service_agreement - Service agreement
    • loan_repayment - Loan repayment
    • tradesmens_services - Tradesmen's services
    • purchase_agreement - Purchase agreement
    • leasing_agreement - Leasing agreement
    • rental_agreement - Rental agreement
    • delivery_of_goods - Delivery of goods
    • contract_for_work - Labour Contract
    • interest - Interest in arrears
  • quality: regular (enum) - Describes the quality of the claim.
    • regular
    • special
    • second_placement
    • third_placement
  • metadata (array[CLAIMMETADATA])
  • additional_charges (array[ADDITIONALCHARGE])
  • refunds (array[REFUND])
  • payments (array[PAYMENT])
  • events (array[EVENT])
  • messages (array[MESSAGE])
  • documents (array[DOCUMENT])

FILE-RESPONSE (object)

  • id:file_******** (string)
  • object:file (string)
  • ecollect_reference: 123456789 (string) - eCollect's unique reference of the file.
  • creation: 2016-09-01 12:22:11 (string) - Creation Datetime of the file at eCollect.
  • customer: cus_******** (string) - eCollect's unique identifier of the customer the file is related to.
  • status : cleared:full_payment (STATUS-RESPONSE) - The current status of the file.
  • data (array[PRINCIPALCLAIM-RESPONSE,ADDITIONALCHARGE-RESPONSE,REFUND-RESPONSE,PAYMENT-RESPONSE])

PRINCIPALCLAIM-RESPONSE (object)

  • id:cla_*******
  • object: principal_claim
  • your_reference: 123456789 (string) - Your unique reference of the claim
  • ecollect_reference: 123456789 (string) - eCollect's unique reference of the claim
  • creation:2016-09-01 12:22:11 - Creation DateTime of the claim at eCollect
  • file:file_********, -
  • customer: cus_******** (string) - eCollect's unique identifier of the customer.
  • currency: EUR (string) - Currency of the claim, according to ISO 4217
  • amount: 123.45 (number) - Total amount of the principal claim including VAT or sales tax. Please use the following format: positive numeric characters, 2 decimals. Separating character is a dot.
  • occurrence_date: 2016-03-02 (string) - The date of emergence of the principal claim. It can be a the date when a contract with the customer came into force or the date of the delivery of goods or the date when services had been rendered. Please use the format YYYY—MM-DD.
  • due_date: 2016-02-01 (string) - The due date of the claim in format YYYY—MM-DD.
  • subject_matter_of_claim: Purchase from greatstuff.com, Invoice N° 123456 (string) - A detailed description of the delivery or service. Examples: “Purchase from greatstuff.com, Invoice N° 123456” or “Monthly subscription fee bestdateever.com - Premium account, September 2016”
  • contractual_item (enum) - The contractual item upon which the legal relationship between you (the creditor) and your customer is based.
    • medical_care - Medical care
    • service_agreement - Service agreement
    • loan_repayment - Loan repayment
    • tradesmens_services - Tradesmen's services
    • purchase_agreement - Purchase agreement
    • leasing_agreement - Leasing agreement
    • rental_agreement - Rental agreement
    • delivery_of_goods - Delivery of goods
    • contract_for_work - Labour Contract
    • interest - Interest in arrears
  • quality:regular (enum) - Describes the quality of the claim.
    • regular
    • special
    • second_placement
    • third_placement

ADDITIONALCHARGE-RESPONSE (object)

  • id:cla_*******
  • creation: 2016-09-01 12:22:11 (string) -
  • object: additional_charge (string) - The type defines that this claim is an additional claim.
  • currency: EUR (string) - Currency of the additional charge, according to ISO 4217
  • amount: 123.45 (number) - Total amount of the additional charge. Please use the following format: positive numeric character, 2 decimals. Separating character is a dot.
  • additional_charge_type (enum) - Type of the additional charge, fee or expense.
    • reminder_fee
    • bank_charges
    • processing_fee
    • data_preparation
    • expenses
  • occurrence_date: 2016-02-01 (string) - Date the charge was initiated.

ADDITIONALCHARGE (object)

  • currency: EUR (required, string) - Currency of the additional charge, according to ISO 4217
  • amount: 123.45 (required, number) - Total amount of the additional charge. Please use the following format: positive numeric character, 2 decimals. Separating character is a dot.
  • additional_charge_type (required, enum) - Type of the additional charge, fee or expense.
    • reminder_fee
    • bank_charges
    • processing_fee
    • data_preparation
    • expenses
  • occurrence_date: 2016-02-01 (required, string) - Date the charge was initiated.

PAYMENT-RESPONSE (object)

  • id: pay_******** (string) - eCollect's unique identifier of the payment.
  • object: payment (string)
  • your_reference: 123456789 (string) - Your unique reference of the payment.
  • ecollect_reference: 123456789 (string) - eCollect's unique reference of the payment.
  • creation: 2016-09-01 12:22:11 (string) - Creation datetime of the payment at eCollect.
  • customer: cus_******** (string) - The ID of the customer the payment is attached to.
  • file: file_******** (string) - The ID of the file the payment is attached to.
  • claim: cla_******** (string) - The ID of the claim the payment is attached to.
  • currency: EUR (string) - Currency of the payment, according to ISO 4217.
  • amount: 123.45 (number) - The total amount of the payment. Please use the following format: positive numeric character, 2 decimals. Separating character is a dot.
  • value_date: 2016-05-08 (string) - The value date of the payment at the bank or payment service provider.
  • payee: ecollect (enum) - The Payee attribute contains the recipient of the payment.
    • ecollect
    • creditor
    • third_party
  • payee_label: BuyOnline Ltd. (string) - Name of the recipient of the payment.

PAYMENT (object)

  • your_reference: 123456789 (string) - Your unique reference of the payment.
  • One of
    • customer: cus_******** (required, string) - The ID of the customer the payment should be attached to.
    • claim: cla_******** (required, string) - The ID of the claim the payment the payment should be attached to.
  • currency: EUR (required, string) - Currency of the payment, according to ISO 4217.
  • amount: 123.45 (required, number) - The total amount of the payment. Please use the following format: positive numeric character, 2 decimals. Separating character is a dot.
  • value_date: 2016-05-08 (required, string) - The value date of the payment at the bank or payment service provider.
  • payee: creditor (enum) - The Payee defines the recipient of the payment. If you select third_party, please provide the name of the recipient.
    • Default: creditor
    • creditor
    • third_party
  • payee_label: BuyOnline Ltd. (string) - Name of the recipient of the payment. Required if payee: third_party.

REFUND-RESPONSE (object)

  • id: ref_******** (string) - eCollect's unique identifier of the refund.
  • object: refund (string)
  • your_reference: 123456789 (string) - Your unique reference of the refund.
  • ecollect_reference: 123456789 (string) - eCollect's unique reference of the refund.
  • creation: 2016-09-01 12:22:11 (string) - Creation datetime of the refund at eCollect.
  • customer: cus_******** (string) - ID of the customer the refunded claim is related to.
  • file: file_******** (string) - ID of the file the refunded claim belongs to.
  • claim: cla_******** (string) - ID of the claim that was refunded.
  • currency: EUR (string) - Currency of the refund, according to ISO 4217.
  • amount: 123.45 (number) - Total amount of the refund. Please use the following format: positive numeric character, 2 decimals. Separating character is a dot.
  • value_date: 2016-05-08 (string) - The date the refund was proceeded.

REFUND (object)

  • your_reference: 123456789 (string) - Your unique reference of the refund.
  • One of
    • customer: cus_******** (required, string) - ID of the customer to refund.
    • claim: cla_******** (required, string) - ID of the claim to refund.
  • currency: EUR (required, string) - Currency of the refund, according to ISO 4217.
  • amount: 123.45 (required, number) - Total amount of the refund. Please use the following format: positive numeric character, 2 decimals. Separating character is a dot.
  • value_date: 2016-05-08 (required, string) - The date the refund was proceeded.

CLAIMMETADATA-RESPONSE (object)

  • object: metadata
  • creation: 2016-09-01 12:22:11 - Creation datetime of the claim_metadata object at eCollect
  • type: invoice:reference (enum) - The type of additional information related to the claim.
    • invoice:reference
    • app:reference
    • app:name
    • app:description
    • shop:reference
    • shop:website_url
    • shop:key
    • website:url
    • website:country
    • website:language
    • pos:country
    • pos:language
    • account:reference
    • account:user
    • account:email_address
    • account:mobile
    • account:facebook_user
    • subscription:reference
    • subscription:period
  • value: IN-20160011 (string) - The actual data corresponding to the metadata type.

CLAIMMETADATA (object)

  • type: invoice:reference (required, enum) - The type of additional information related to the claim.
    • invoice:reference
    • app:reference
    • app:name
    • app:description
    • shop:reference
    • shop:website_url
    • shop:key
    • website:url
    • website:country
    • website:language
    • pos:country
    • pos:language
    • account:reference
    • account:user
    • account:email_address
    • account:mobile
    • account:facebook_user
    • subscription:reference
    • subscription:period
  • value: IN-20160011 (required, string) - The actual data corresponding to the metadata type.

MESSAGE-RESPONSE (object)

  • id: mes_******** (string) - The unique identifier of the message, provided by eCollect.
  • object: message (string)
  • sender: ecollect (enum) - The sender of the message.
    • ecollect
    • creditor
    • customer
  • recipient: creditor (enum) - The recipient of the message.
    • ecollect
    • creditor
    • customer
  • creation: 2016-09-01 12:22:11 (string) - The creation datetime of the message.
  • customer: cus_******** (string) - eCollect ID of the customer the message is related to, if available.
  • claim: cla_******** (string) - eCollect ID of the claim the message is related to, if available.
  • file: file_******** (string) - eCollect ID of the file the message is related to, if available.
  • payment: pay_******** (string) - eCollect ID of the payment the message is related to, if available.
  • refund: ref_******** (string) - eCollect ID of the refund the message is related to, if available.
  • statement: sta_********* (string) - eCollect ID of the statement the message is related to, if available.
  • subject: This is the subject of the message (string) - The subject of the message.
  • text: This is the text contained in the message. (string) - The text body of the message.
  • type: general (enum) - The various types of the purpose of a message.
    • general
    • cancellation
  • documents (array[DOCUMENT-RESPONSE]) - A message can contain one or many documents.

MESSAGE (object)

  • One of
    • customer: cus_******** (required, string) - eCollect ID of the customer the message is relating to.
    • claim: cla_******** (required, string) - eCollect ID of the claim the message is relating to.
    • file: file_******** (required, string) - eCollect ID of the file the message is relating to.
    • payment: pay_******** (required, string) - eCollect ID of the payment the message is relating to.
    • refund: ref_******** (required, string) - eCollect ID of the refund the message is relating to.
    • statement: sta_********* (required, string) - eCollect ID of the statement the message is relating to.
  • subject: This is the subject of the message (required, string) - The subject of the message.
  • text: This is the text contained in the message. (string) - The text body of the message.
  • type: general (required, enum) - The various types of the purpose of a message.
    • general
    • cancellation
  • documents (array[DOCUMENT-RESPONSE]) - A message can contain one or many documents.

DOCUMENT-RESPONSE (object)

  • id: doc_f7r7Reo1c (string) - The unique identifier of the document.
  • object: document (string) - Value is document.
  • creation: 2016-09-01 12:22:11 (string) - The creation timestamp of the document file.
  • customer: cus_******** (string) - If attached to a customer.
  • file: file_******** (string) - If attached to a file.
  • claim: cla_******** (string) - If attached to a claim.
  • refund: ref_******** (string) - If attached to a refund.
  • payment: pay_******** (string) - If attached to a payment.
  • message: mes_******** (string) - If attached to a message.
  • statement: sta_********* (string) - If attached to a statement.
  • content (string) - The document file as a base64 encoded string.
  • size: 1024 (number) - The size of the document.
  • type: invoice (enum) - The various types of the purpose of the document.
    • invoice
    • reminder
    • offer
    • delivery_note
    • credit_note
    • order_confirmation
    • proof_of_delivery
    • general_correspondence
    • dispute_letter
    • proof_of_payment
    • bank_statement
    • screenshot
    • purchase_contract
    • rental_contract
    • lease_contract
    • loan_contract
    • termination_notice
    • proof_of_termination
    • installment_contract
    • payment_plan
    • death_certificate
    • certificate_of_disability
    • proof_of_detention
    • power_of_attorney
    • id_card
    • passport
    • driving_license
    • registration
    • postal_return_content
    • postal_return_envelope
    • proof_of_guardianship
    • photo_debtor
    • court_decision
    • bankruptcy_decision
    • insolvency_application
    • affidavit
    • oath_of_disclosure
    • asset_disclosure
    • unspecified

DOCUMENT (object)

  • object: document (string) - Value is document.
  • customer: cus_******** (string) - If attached to a customer.
  • file: file_******** (string) - If attached to a file.
  • claim: cla_******** (string) - If attached to a claim.
  • refund: ref_******** (string) - If attached to a refund.
  • payment: pay_******** (string) - If attached to a payment.
  • message: mes_******** (string) - If attached to a message.
  • statement: sta_********* (string) - If attached to a statement.
  • content (string) - The document file as a base64 encoded string.
  • type: invoice (enum) - The various types of the purpose of the document.
    • invoice
    • reminder
    • offer
    • delivery_note
    • credit_note
    • order_confirmation
    • proof_of_delivery
    • general_correspondence
    • dispute_letter
    • proof_of_payment
    • bank_statement
    • screenshot
    • purchase_contract
    • rental_contract
    • lease_contract
    • loan_contract
    • termination_notice
    • proof_of_termination
    • installment_contract
    • payment_plan
    • death_certificate
    • certificate_of_disability
    • proof_of_detention
    • power_of_attorney
    • id_card
    • passport
    • driving_license
    • registration
    • postal_return_content
    • postal_return_envelope
    • proof_of_guardianship
    • photo_debtor
    • court_decision
    • bankruptcy_decision
    • insolvency_application
    • affidavit
    • oath_of_disclosure
    • asset_disclosure
    • unspecified

NOTIFICATION-RESPONSE (object)

  • id: ntf_********** (string) - The unique identifier of the notification.

  • object: notification (string) - Value is notification.

  • your_reference: 12345 (string) - Your event reference, if available.

  • creation: 2016-09-01 12:22:11 (string) - The creation timestamp of the event.

  • occurrence: 2016-09-01 12:22:11 (string) - The moment of emergence of the event

  • customer: cus_********* (string) - If attached to a customer.

  • claim: cla_********* (string) - If attached to a claim.

  • file: file_********* (string) - If attached to a file.

  • refund: ref_********* (string) - If attached to a refund.

  • payment: pay_********* (string) - If attached to a payment.

  • message: mes_********* (string) - If attached to a message.

  • statement: sta_********* (string) - If attached to a statement.

  • type: claim:created (enum) - Event type (category). Notification types contain subcategory text appendix in following form “type:{created|updated}”. Subcategory values are “created”, “updated”.

    • claim:{subcategory}
    • file:{subcategory}
    • file_status:{subcategory}
    • communication:{subcategory}
    • payment:{subcategory}
    • refund:{subcategory}
    • account_transaction:{subcategory}
    • statement:{subcategory}
    • customer:{subcategory}
    • event:{subcategory}

  • data (object) - The corresponding object like a claim or customer.

EVENT-RESPONSE (object)

  • id: evnt_f3r7Reo1c (string) - The unique identifier of the event.
  • object: event (string) - Value is event.
  • your_reference: 12345 (string) - Your event reference, if available.
  • creation: 2016-09-01 12:22:11 (string) - The creation timestamp of the event.
  • occurrence: 2016-09-01 12:22:11 (string) - The moment of emergence of the event
  • title: Customer registration (required, string) - The title of the event, limited to 256 characters.
  • description: Customer registration at internetshop.com (string) - The description of the event.
  • type: registration (enum) - The various types of the event.
    • registration
    • reminder
    • login
    • contract
    • invoice
    • contravention
    • transaction
    • purchase
    • download
    • subscription
    • renewal
    • order
    • booking
    • delivery
    • ticket
    • posting
    • mailing
    • payment
    • chargeback
    • cancellation

EVENT (object)

  • occurrence: 2016-09-01 12:22:11 (string) - The moment of emergence of the event
  • your_reference: 12345 (string) - Your event reference, if available.
  • title: Customer registration (required, string) - The title of the event, limited to 256 characters.
  • description: Customer registration at internetshop.com (string) - The description of the event.
  • type: registration (enum) - The various types of the event.
    • registration
    • reminder
    • login
    • contract
    • invoice
    • contravention
    • transaction
    • purchase
    • download
    • subscription
    • renewal
    • order
    • booking
    • delivery
    • ticket
    • posting
    • mailing
    • payment
    • chargeback
    • cancellation

ACCOUNT-RESPONSE (object)

  • object: account (string) - Value is account.
  • currency: EUR (string) - Currency of the account, according to ISO 4217
  • current_balance: 123.45 (number) - The current balance of your account.
  • transactions (array[TRANSACTION-RESPONSE])

TRANSACTION-RESPONSE (object)

  • id: tra_13r7Reo1c (string) - The unique identifier of the transaction.
  • object: transaction (string) - Value is transaction.
  • currency: EUR (string) - Currency of the transaction, according to ISO 4217
  • value: 123.45 (number) - The transaction value.
  • creation: 2016-09-01 12:22:11 (string) - The creation timestamp of the transaction.
  • customer: cus_********* (string) - If attached to a customer.
  • claim: cla_********* (string) - If attached to a claim.
  • file: file_********* (string) - If attached to a file.
  • refund: ref_********* (string) - If attached to a refund.
  • payment: pay_********* (string) - If attached to a payment.
  • statement: sta_********* (string) - If attached to a statement.
  • type: carry_over (enum) - The various types of the transaction.
    • carry_over
    • statement
    • payout
    • direct-payment
    • refund

STATEMENT-RESPONSE (object)

  • id: sta_13r7Reo1c (string) - The unique identifier of the statement.
  • object: statement (string) - Value is statement.
  • creation: 2016-09-01 12:22:11 (string) - The creation timestamp of the statement.
  • customer: cus_********* (string) - Attached customer.
  • file: file_********* (string) - Attached file.
  • documents (array[DOCUMENT-RESPONSE]) - Attached documents.
  • transactions (array[TRANSACTION-RESPONSE])

TST_object_in_data_structures (object)

  • tst_attribute_data_structures: test for data structures (required, string) - Description for tst_data_structures
  • Include DOCUMENT-RESPONSE

STATUS

STATUS-RESPONSE (object)

  • object: status
  • creation: 2016-09-01 12:22:11 - Datetime when the status was set.
  • status: cleared:full_payment (string) - The status (containing status group + status) that was set.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment