Back to top

Public Pair Finance API

This document outlines the public Pair Finance API in version 1.0. It is available using HTTPS only at app.pairfinance.com/api/v1.

Last updated: March 26th, 2019.

Authentication

The Pair Finance API uses Basic Authorization. You use the API credentials assigned to you by Pair Finance to authenticate your requests.

Error States

The common HTTP Response Status Codes are used.

HTTPS

The API is only available over HTTPS.

Time zones / dates

All timestamps are formatted as ISO8601 with timezone information. For API calls that allow for a timestamp to be specified, we use that exact timestamp. These timestamps look something like 2016-05-02T12:58:54+00:00.

Testing

For testing before go-live please use the staging endpoint https://stage.pairfinance.com/api/v1/ instead of the production endpoint shown in the method descriptions below (production endpoint https://app.pairfinance.com/api/v1/).

Cases

This API allows customers of Pair Finance GmbH to hand in new case files for processing or to query the status of all or individual case files in our system.

Cases Collection

List All Cases
GET/cases?from={from}&amount={amount}&status={status}&merchant_id=

Lists all case files (“cases”) that are part of the scope of the current user (e.g. cases that belong to this creditor). The list can be filtered by the state of the case file and the page number of the returned list.

Example URI

GET https://app.pairfinance.com/api/v1/cases?from=0&amount=10&status=active&merchant_id=
URI Parameters
HideShow
from
integer (optional) Default: 0 Example: 0

Starting number of the returned cases, defaults to 0.

amount
integer (optional) Default: 10 Example: 10

Amount of cases returned per case, defaults to 10.

status
string (optional) Example: active

Status of the cases to be returned, defaults to active, paused, stopped and excludes finished. It’s not possible to view multiple statuses at once, unless using the empty default.

merchant_id
string (optional) Example: mymerchant

For Partner companies, the ID of the merchant whose cases should be returned.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "meta": {
    "total_cases": 710,
    "first_case_number": 0,
    "last_case_number": 10,
    "cases_per_page": 10,
    "filter" {
        "status": "active"
    }
  },
  "cases": [
    {
      "id": "100039269541",
      "reference_id": "customers_crm_id_here",
      "created_at": "2016-05-02T12:58:54+00:00",
      "updated_at": "2016-05-02T12:58:54+00:00",
      "state": "active",
      "type": "private_person",
      "debt_total": "99.3",
      "total_debt_outstanding": "99.3",
      "currency": "EUR",
      "first_name": "John",
      "last_name": "Doe",
    }
  ]
}

Create a New Case
POST/cases

Creates a new case in our system that can be scheduled to run according to our system settings. This does not automatically start a strategy for this case file.

Below are allowed values for some fields that require specific inputs:

  • “primary_debtor_info”:

    • “type”:

      • “private_person”
      • “company”
    • “gender”:

      • “male”
      • “female”
      • “unknown”
  • “addresses”:

    • “type”:
      • “invoice” (= Rechnungsaddresse)
      • “shipping” (= Lieferaddresse)
      • “postal” (= Postanschrift)
      • “work” (= Arbeitsaddresse)
      • “previous” (= Voranschrift)
      • “other” (= Andere Addresse)
      • “actual” (= Aktuelle Address)
  • “creditor_fees”:

    • “type”:
      • “creditor_reminder_fee” (= Mahnspesen)
      • “creditor_chargeback_fee” (= Bankrücklastkosten)
      • “creditor_title_fee” (= Titulierungskosten)
      • “creditor_deferment_fee” (= Verzugsgebühren)
  • “contract_nature”:

    • “medical_service” (= Medical or dentist service)
    • “service_contract” (= Contract for services)
    • “loan_agreement” (= Loan repayment)
    • “craftsman_power” (= Craftsmen services)
    • “purchase_contract” (= Purchase Contract)
    • “lease” (= Leasing Contract/hire purchase)
    • “rental_contract” (= Rental contract)
    • “shipping_methods” (= Freightage)
    • “work_contract” (= Contract for work and services/contract for work and materials)
    • “advertisement_in_newspaper” (= Advertisement in newspaper or similar)
    • “fees_referring_to_private_nursing_care_insurance” (= fees referring to private nursing care insurance)
    • “guarantee_financial_security” (= guarantee/financial security)
    • “business_errand” (= business errand run by a self-employed person)
    • “home_accommodation” (= home accommodation)
    • “hotel_fees” (= hotel fees)
    • “nursery_or_kindergarden_fee” (= nursery or kindergarden fee)
    • “bill_of_current_account_cost” (= bill of current account cost)
    • “hospital_expenses” (= hospital expenses)
    • “cost_of_ambulance_service” (= cost of ambulance service)
    • “storage_cost” (= storage cost)
    • “cost_of_training_courses” (= cost of training courses)
    • “cost_of_renting_office_room” (= cost of renting office room incl. utilities )
    • “cost_of_renting_housing” (= cost of renting housing incl. utilities)
    • “ancillary_rental_costs” (= ancillary rental costs - also renovation costs)
    • “rent_other” (= rent (other))
    • “membership_fee” (= membership fee)
    • “pacht” (= lease)
    • “nursing_care_insurance” (= nursing care insurance)
    • "attorney_s_fee: “attorney)s fee”
    • “travel_contract” (= travel contract)
    • “annuity_in_arrears” (= annuity in arrears)
    • “repair_services” (= repair services)
    • “recourse_to_guarantee” (= recourse to guarantee/financial security)
    • “recourse_to_insurance_agreement” (= recourse to insurance agreement due to accident/incident)
    • “compensation_by_contract” (= compensation (for damages) by contract)
    • “compensation_by_accident_incident” (= compensation (for damages) by accident/incident)
    • “cheque_exchange” (= cheque/exchange)
    • “commission_for_cheque_exchange” (= commission for cheque/exchange)
    • “expenses_for_cheque_exchange” (= expenses for cheque/exchange)
    • “acknowledgement_of_debt” (= acknowledgement of debt)
    • “freight_cost” (= freight cost)
    • “telecommunication_services” (= telecommunication services)
    • “veterinary_service” (= veterinary service)
    • “amortization_rate_rate_of_interest” (= amortization rate/rate of interest)
    • "overdraw_one_s_bank_account: “overdraw one)s bank account”
    • “unjustified_enrichment” (= unjustified enrichment)
    • “being_behind_in_paying_aliments” (= being behind in paying aliments)
    • “out_of_court_settlement” (= out-of-court settlement)
    • “commission_for_real_estate” (= commission for real-estate agent/middleman)
    • “cost_of_food” (= cost of food)
    • “insurance_premium_fee” (= insurance premium/- fee)
    • “accommodation_service” (= accommodation service - energy, water, gas, heat)
    • “optional_benefits_services” (= optional benefits/services while being in stationary treatment)
    • “delivery_of_goods” (= delivery of goods)
    • “housing_benefit_for_owners_corporation” (= housing benefit for owners corporation)
    • “newspaper_subscription” (= newspaper subscription)
    • “overdue_interest_interest_for_delay” (= overdue interest/interest for delay)

Example URI

POST https://app.pairfinance.com/api/v1/cases
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Body
{
  "reference_id": "your_crm_id_here (optional)",
  "merchant_id": "for Partner companies, the ID of the merchant on whose behalf they are creating case files (optional)",
  "currency": "EUR",
  "debtor_info": {
    "primary_debtor_info": {
      "type": "private_person",
      "company_name": "Required if type=company",
      "title": "",
      "first_name": "...",
      "last_name": "...",
      "gender": "male",
      "customer_number": "abc",
      "date_of_birth": "1970-01-31",
      "pass_iban": "DE89370400440532013087",
      "pass_bic": "DEUTDEFF"
    },
    "addresses": [
      {
        "primary": true,
        "type": "invoice",
        "street": "...",
        "street_addon": "",
        "street_number": "22",
        "zip_code": "10178",
        "city": "Berlin",
        "country": "DE"
      }
    ],
    "emails": [
      {
        "primary": true,
        "email": "foo@bar.de"
      },
      {
        "primary": false,
        "email": "foo@bar2.de"
      }
    ],
    "phones": [
      {
        "primary": true,
        "number": "+49 151 1234567"
      }
    ]
  },
  "claims": [
    {
      "debt_total": "99.1",
      "vat_total": "9.2",
      "invoice_number": "1234",
      "invoice_date": "2016-05-02",
      "due_date": "2016-05-16",
      "contract_number": "1234",
      "contract_date": "2016-05-02",
      "contract_nature": "loan_agreement",
      "loan_nominal_amount": "6000.00",
      "loan_repayment_date": "2019-02-01",
      "items": [
        {
          "name": "...",
          "delivery_cost": "2.2",
          "cost_per_unit": "11.2",
          "number_of_units": "2"
        }
      ],
      "creditor_fees": [
        {
          "type": "creditor_reminder_fee",
          "amount": "5.0",
          "date_incurred": "2016-05-20"
        },
        {
          "type": "creditor_chargeback_fee",
          "amount": "10.0",
          "date_incurred": "2016-05-22"
        }
      ]
    }
  ]
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "currency",
      "message": "Currency code 'YUAN' not recognized"
    },
    {
      "key": "merchant_id",
      "message": "For Partners merchant_id is mandatory, please include this parameter in your call"
    },
    {
      "key": "claims",
      "errors": [
        {
          "key": "contract_date",
          "message": "Date format not recognizable (use YYYY-mm-dd)"
        }
      ]
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "merchant_id",
      "message": "Merchant id not found"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /cases/100039269541
Body
{
  "id": "100039269541",
  "reference_id": "your_crm_id_here (optional)",
  "merchant_id": "test_merchant",
  "debt_total": "99.1",
  "total_debt_outstanding": "99.1",
  "currency": "EUR",
  "debtor_info": {
    "primary_debtor_info": {
      "type": "private_person",
      "title": "",
      "first_name": "John",
      "last_name": "Doe",
      "gender": "male",
      "customer_number": "abc",
      "date_of_birth": "1970-01-31",
      "pass_iban": "DE89370400440532013087",
      "pass_bic": "DEUTDEFF"
    },
    "addresses": [
      {
        "primary": true,
        "type": "invoice",
        "street": "...",
        "street_addon": "",
        "street_number": "22",
        "zip_code": "10178",
        "city": "Berlin",
        "country": "DE"
      }
    ],
    "emails": [
      {
        "primary": true,
        "email": "foo@bar.de"
      },
      {
        "primary": false,
        "email": "foo@bar2.de"
      }
    ],
    "phones": [
      {
        "primary": true,
        "number": "+49 151 1234567"
      }
    ]
  },
  "claims": [
    {
      "id": 1234,
      "debt_total": "99.1",
      "vat_total": "9.2",
      "invoice_number": "1234",
      "invoice_date": "2016-05-02",
      "due_date": "2016-05-16",
      "contract_number": "1234",
      "contract_date": "2016-05-02",
      "contract_nature": "loan_agreement",
      "loan_nominal_amount": "6000.00",
      "loan_repayment_date": "2019-02-01",
      "items": [
        {
          "name": "...",
          "delivery_cost": "2.2",
          "cost_per_unit": "11.2",
          "number_of_units": "2"
        }
      ],
      "creditor_fees": [
        {
          "type": "creditor_reminder_fee",
          "amount": "5.0",
          "date_incurred": "2016-05-20"
        },
        {
          "type": "creditor_chargeback_fee",
          "amount": "10.0",
          "date_incurred": "2016-05-22"
        }
      ]
    }
  ],
  "events": [
    {
      "created_at": "2016-05-02T12:58:54+00:00",
      "name": "case file created",
      "status": ""
    }
  ]
}

View Case Details
GET/cases/{case_id}

Returns the detailed set of data about a given case file, including all claim (purchase) and item data but excluding historical data (what happened when with this case).

Example URI

GET https://app.pairfinance.com/api/v1/cases/100039269541
URI Parameters
HideShow
case_id
string (required) Example: 100039269541

ID of the Case file in the form of a string

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "100039269541",
  "reference_id": "your_crm_id_here (optional)",
  "merchant_id": "test_merchant",
  "created_at": "2016-05-02T12:58:54+00:00",
  "updated_at": "2016-05-02T12:58:54+00:00",
  "state": "active",
  "debt_total": "99.1",
  "total_debt_outstanding": "99.1",
  "currency": "EUR",
  "debtor_info": {
    "primary_debtor_info": {
      "type": "private_person",
      "title": "",
      "first_name": "John",
      "last_name": "Doe",
      "gender": "male",
      "customer_number": "abc",
      "date_of_birth": "1970-01-31",
      "pass_iban": "DE89370400440532013087",
      "pass_bic": "DEUTDEFF"
    },
    "addresses": [
      {
        "primary": true,
        "type": "invoice",
        "street": "...",
        "street_addon": "",
        "street_number": "22",
        "zip_code": "10178",
        "city": "Berlin",
        "country": "DE"
      }
    ],
    "emails": [
      {
        "primary": true,
        "email": "foo@bar.de"
      },
      {
        "primary": false,
        "email": "foo@bar2.de"
      }
    ],
    "phones": [
      {
        "primary": true,
        "number": "+49 151 1234567"
      }
    ]
  },
  "claims": [
    {
      "id": 1234,
      "debt_total": "99.1",
      "vat_total": "9.2",
      "invoice_number": "1234",
      "invoice_date": "2016-05-02",
      "due_date": "2016-05-16",
      "contract_number": "1234",
      "contract_date": "2016-05-02",
      "contract_nature": "loan_agreement",
      "loan_nominal_amount": "6000.00",
      "loan_repayment_date": "2019-02-01",
      "items": [
        {
          "name": "...",
          "delivery_cost": "2.2",
          "cost_per_unit": "11.2",
          "number_of_units": "2"
        }
      ],
      "creditor_fees": [
        {
          "type": "creditor_reminder_fee",
          "amount": "5.0",
          "date_incurred": "2016-05-20"
        },
        {
          "type": "creditor_chargeback_fee",
          "amount": "10.0",
          "date_incurred": "2016-05-22"
        }
      ]
    }
  ],
  "events": [
    {
      "created_at": "2016-05-02T12:58:54+00:00",
      "name": "case file created",
      "status": ""
    },
    {
      "created_at": "2016-05-20T12:58:54+00:00",
      "name": "primary notification sent",
      "status": "landed"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Resource not found"
}

Claims collection

Add a claim to a case file
POST/cases/{case_id}/claims

Allows adding claims to a case files. It is only possible to add new claims to a case file which is not activated yet to the one in dunning phase. JSON Body has the same format as in POST case file endpoint.

Example URI

POST https://app.pairfinance.com/api/v1/cases/100039269541/claims
URI Parameters
HideShow
case_id
string (required) Example: 100039269541

ID of the Case file in the form of a string

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Body
{
  "debt_total": "99.1",
  "vat_total": "9.2",
  "invoice_number": "1234",
  "invoice_date": "2016-05-02",
  "due_date": "2016-05-16",
  "contract_number": "1234",
  "contract_date": "2016-05-02",
  "contract_nature": "loan_agreement",
  "loan_nominal_amount": "6000.00",
  "loan_repayment_date": "2019-02-01",
  "items": [
    {
      "name": "...",
      "delivery_cost": "2.2",
      "cost_per_unit": "11.2",
      "number_of_units": "2"
    }
  ],
  "creditor_fees": [
    {
      "type": "creditor_reminder_fee",
      "amount": "5.0",
      "date_incurred": "2016-05-20"
    },
    {
      "type": "creditor_chargeback_fee",
      "amount": "10.0",
      "date_incurred": "2016-05-22"
    }
  ]
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "amount",
      "message": "Must be larger than 0"
    },
    {
      "key": "effective_date",
      "message": "Date format not recognizable (use YYYY-mm-dd)"
    },
    {
      "key": "contract_nature",
      "message": "Is not a valid value"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "case_id",
      "message": "ID of the Case file not found"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /cases/100039269541/payments
Body
{
  "id": 1234,
  "debt_total": "99.1",
  "vat_total": "9.2",
  "invoice_number": "1234",
  "invoice_date": "2016-05-02",
  "due_date": "2016-05-16",
  "contract_number": "1234",
  "contract_date": "2016-05-02",
  "contract_nature": "loan_agreement",
  "loan_nominal_amount": "6000.00",
  "loan_repayment_date": "2019-02-01",
  "items": [
    {
      "name": "...",
      "delivery_cost": "2.2",
      "cost_per_unit": "11.2",
      "number_of_units": "2"
    }
  ],
  "creditor_fees": [
    {
      "type": "creditor_reminder_fee",
      "amount": "5.0",
      "date_incurred": "2016-05-20"
    },
    {
      "type": "creditor_chargeback_fee",
      "amount": "10.0",
      "date_incurred": "2016-05-22"
    }
  ]
}

Payments collection

Report a Payment
POST/cases/{case_id}/payments

Allows reporting payments received for case files. A full payment will automatically stop the process; a partial payment means the remaning amount will be pursued.

Example URI

POST https://app.pairfinance.com/api/v1/cases/100039269541/payments
URI Parameters
HideShow
case_id
string (required) Example: 100039269541

ID of the Case file in the form of a string

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Body
{
  "amount": "10.0",
  "description": "you can optionally add a reference here",
  "effective_date": "2017-07-20"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "amount",
      "message": "must be larger than 0"
    },
    {
      "key": "effective_date",
      "message": "Date format not recognizable (use YYYY-mm-dd)"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "case_id",
      "message": "ID of the Case file not found"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /cases/100039269541/payments
Body
{
  "id": "jdyaXKmd",
  "case_file_id": "100039269541",
  "created_at": "2016-05-02T13:07:57.162+01:00",
  "state": "active",
  "data": {
    "partner": null,
    "effective_date": "2016-04-02",
    "description": "description 123",
    "unbook_date": null,
    "unbook_description": null,
    "cancel_data": {
      "was_state": "active",
      "became_state": "active"
    },
    "amount": "10.0"
  }
}

Returns collection

Report a Return
POST/cases/{case_id}/claims/{claim_id}/return

Allows reporting returns of a particular claims of the case files. If there is only one claim in the case file, reporting a return will automatically stop the debt collection process; if a case file contains other claims the remaning amount will be pursued.

Example URI

POST https://app.pairfinance.com/api/v1/cases/100039269541/claims/1234/return
URI Parameters
HideShow
case_id
string (required) Example: 100039269541

ID of the Case file in the form of a string

claim_id
string (required) Example: 1234

ID of the Claim in the form of a string whicn is returned

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Body
{
  "description": "you can optionally add a reference here",
  "effective_date": "2017-07-20"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "effective_date",
      "message": "Date format not recognizable (use YYYY-mm-dd)"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "case_id",
      "message": "ID of the Case file not found"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /cases/100039269541/payments
Body
{
  "id": "O7poJ4Wdj",
  "case_file_id": "101268959604",
  "created_at": "2018-06-08T12:10:05.030+02:00",
  "state": "active",
  "data": {
    "amount": 867,
    "effective_date": "2018-06-08",
    "description": "Device returned to the store in Berlin"
  }
}

Merchants

This API allows Partners of Pair Finance GmbH to create a new merchant (creditor) or to get detailed information about given merchant in our system.

Merchants Collection

Create a New Merchant
POST/merchants

For Partner companies only. Creates a new merchant in our system that a Partner company can submit case files on behalf of.

Example URI

POST https://app.pairfinance.com/api/v1/merchants
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Body
{
  "name": "test merchant 123",
  "legal_name": "test merchant 123 GmbH & Co. KG",
  "merchant_logo": "data:image/png;base64, ...",
  "tax_status": "1 - if entitled to deduct input tax (Vorsteuerabzugsberechtigt), 0 - if not",
  "tax_id_number": "99999999999 (optiona)",
  "address": {
    "street_name": "Musterstraße",
    "street_number": "25",
    "zip_code": "10178",
    "city": "Berlin",
    "country": "DE",
    "phone": "493000000000000 (optional)"
  },
  "account_details": {
    "iban": "DE123456789012345678",
    "bic_swift": "AAAABBCCDDD"
  },
  "contact_persons": [
    {
      "name": "Max Mustermann",
      "email": "max@musterfirma.de",
      "phone": "49311111111111"
    }
  ]
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "key": "merchant_logo",
      "message": "Merchant logo is too large. The file should be up to 300x100px"
    },
    {
      "key": "slug",
      "message": "ist bereits vergeben"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /merchants/test_merchant_123
Body
{
  "id": "test_merchant_123",
  "name": "test merchant 123",
  "legal_name": "test merchant 123 GmbH & Co. KG",
  "merchant_logo": "https://cloudfront.net/merchants/test_merchant_123/logo/test_merchant_123_logo.png",
  "tax_id_number": "99999999999",
  "address": {
    "street_name": "Musterstraße",
    "street_number": "25",
    "zip_code": "10178",
    "city": "Berlin",
    "country": "DE",
    "phone": "493000000000000"
  },
  "account_details": {
    "iban": "DE123456789012345678",
    "bic_swift": "AAAABBCCDDD"
  },
  "contact_persons": [
    {
      "name": "Max Mustermann",
      "email": "max@musterfirma.de",
      "phone": "49311111111111"
    }
  ]
}

Merchant Details

View Merchant Details
GET/merchants/{id}

For Partner companies only. Returns the detailed set of data about a given merchant, including case files list.

Example URI

GET https://app.pairfinance.com/api/v1/merchants/test_merchant_123
URI Parameters
HideShow
id
string (required) Example: test_merchant_123

ID of the Merchant in the form of a string

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id": "test_merchant_123",
    "name": "test merchant 123",
    "legal_name": "test merchant 123 GmbH & Co. KG",
    "total_cases": "3",
    "total_debt": "330.2",
    "total_recoveries": "200.00",
    "cases": [
            {
                "id": "100504961846",
                "reference_id": null,
                "created_at": "2018-01-10T13:29:01.876+01:00",
                "updated_at": "2018-01-26T08:22:34.608+01:00",
                "state": "inactive",
                "type": "private_person",
                "debt_total": "40.0",
                "currency": "EUR",
                "first_name": "Kongo",
                "last_name": "Alpha"
            },
            {
                "id": "100495146084",
                "reference_id": null,
                "created_at": "2017-11-27T11:00:49.669+01:00",
                "updated_at": "2018-01-26T08:22:34.493+01:00",
                "state": "active",
                "type": "private_person",
                "debt_total": "290.2",
                "currency": "EUR",
                "first_name": "Stoichkov",
                "last_name": "Borisbob"
            },
            {
                "id": "100417267661",
                "reference_id": null,
                "created_at": "2016-10-17T14:14:00.834+02:00",
                "updated_at": "2017-09-18T19:09:23.454+02:00",
                "state": "paid",
                "type": "company",
                "debt_total": "200.0",
                "currency": "EUR",
                "first_name": "Luigi",
                "last_name": "Pizza"
            }
    ]
    "documents": [
        {
            "id": 959,
            "file_file_name": "Handelsregister-Auszug.pdf",
            "file_content_type": "application/pdf",
            "file_file_size": 5322116,
            "file_updated_at": "2018-01-15T13:04:47.305+02:00",
            "entity_id": 84,
            "entity_type": "Company",
            "created_at": "2018-01-15T13:04:47.343+02:00",
            "updated_at": "2018-01-17T12:24:03.907+01:00",
            "data": {
                "date_received": "2018-01-15",
                "type_of_file": "HR-Auszug / Gewerbeanm.",
                "source": "creditor",
                "description": null,
                "visibility": "pair_creditor",
                "total_pages": null
            },
            "user_id": null,
            "activity_id": null,
            "deleted_at": null
        }
    ] 
    }
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Resource not found"
}

Merchant Documents

Upload Merchant's Documents
POST/merchants/{id}/documents

Аllows uploading documents. Main use case is uploading merchant’s KYC (Know Your Custormer) documents. In accordance to German law, every new customer should provide Pair Finance with proofs that the company is legit before initiating actual debt collection.

It is possible to upload docuements of two types:

  • ‘RegistrationDocumentAttachment’ Should be used for uploading “Handelsregister-Auszug” (commercial register abstract) for merchants that are registered in “commercial register” (German “Handelsregister”) such as GmbH, AG etc.

  • ‘CompanyAttachment’ - default option. Can be used for any other type of documents (eg, scan of ID, letter from the finance authority etc.)

Supported file types: ‘text/csv’, ‘text/plain’, ‘image/jpeg’, ‘image/jpg’, ‘image/png’, ‘image/gif’, ‘application/pdf’, ‘application/x-rar-compressed’, ‘application/octet-stream’, ‘application/zip’.

Request bodies for document uploads via the API may not be larger than 50MB.

Example URI

POST https://app.pairfinance.com/api/v1/merchants/test_merchant_123/documents
URI Parameters
HideShow
id
string (required) Example: test_merchant_123

ID of the Merchant in the form of a string

Request
HideShow
Headers
Content-Type: multipart/form-data
Authorization: Basic acbd18db4cc2f85cedef654fccc4a4d8
Body
{
    "attachments": [
        {
            "file": file_object,
            "type": "CompanyAttachment",
            "description": "Document's description"
        }
    ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id": "test_merchant_123",
    "name": "test merchant 123",
    "legal_name": "test merchant 123 GmbH & Co. KG",
    "total_cases": "3",
    "total_debt": "330.2",
    "total_recoveries": "200.00",
    "cases": [
        {
            "id": "100504961846",
            "reference_id": null,
            "created_at": "2018-01-10T13:29:01.876+01:00",
            "updated_at": "2018-01-26T08:22:34.608+01:00",
            "state": "inactive",
            "type": "private_person",
            "debt_total": "40.0",
            "currency": "EUR",
            "first_name": "Kongo",
            "last_name": "Alpha"
        },
        {
            "id": "100495146084",
            "reference_id": null,
            "created_at": "2017-11-27T11:00:49.669+01:00",
            "updated_at": "2018-01-26T08:22:34.493+01:00",
            "state": "active",
            "type": "private_person",
            "debt_total": "290.2",
            "currency": "EUR",
            "first_name": "Stoichkov",
            "last_name": "Borisbob"
        },
        {
            "id": "100417267661",
            "reference_id": null,
            "created_at": "2016-10-17T14:14:00.834+02:00",
            "updated_at": "2017-09-18T19:09:23.454+02:00",
            "state": "paid",
            "type": "company",
            "debt_total": "200.0",
            "currency": "EUR",
            "first_name": "Luigi",
            "last_name": "Pizza"
        }
    ]
    "documents": [
        {
            "id": 959,
            "file_file_name": "Handelsregister-Auszug.pdf",
            "file_content_type": "application/pdf",
            "file_file_size": 5322116,
            "file_updated_at": "2018-01-15T13:04:47.305+02:00",
            "entity_id": 84,
            "entity_type": "Company",
            "created_at": "2018-01-15T13:04:47.343+02:00",
            "updated_at": "2018-01-17T12:24:03.907+01:00",
            "data": {
                "date_received": "2018-01-15",
                "type_of_file": "HR-Auszug / Gewerbeanm.",
                "source": "creditor",
                "description": null,
                "visibility": "pair_creditor",
                "total_pages": null
            },
            "user_id": null,
            "activity_id": null,
            "deleted_at": null
        }
    ] 
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Resource not found"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": {
    "documents_samples.csv": [
      {
        "file": [
          "Ein Fehler ist aufgetreten. Bitte überprüfen Sie die Datei und versuchen Sie es erneut."
        ],
        "file_content_type": [
          "Ein Fehler ist aufgetreten. Bitte überprüfen Sie die Datei und versuchen Sie es erneut."
        ]
      }
    ]
  }
}

Generated by aglio on 26 Mar 2019