Walking through the account integration

Note: This walkthrough is intended to simply get you an example to get up and running quickly to experiment and started. More depth around individual API calls and concepts can be found in the API documentation. The commands here are done from the terminal, but you can also use the Postman collection posted here.

Getting Started

Our desired outcome here is to have two claims go into the same account. Our organization has a master account, with one payor and then possbily multiple outstanding payments. This looks like:

Account Payor Claim ID Amount
123456 Bob A1-2001 €100
123456 Bob A1-2002 €330

Now we'll get both of these claims into receeve.

1. Authenticate

The first thing you will need to do is get your OAuth credentials from Customer Success. You should have the following pieces of information.

  • apiURL.- for example: https://api.receeve-demo.com
  • clientId.- for example: 41764642-94c4-486c-8c5b-7f6971d532cd
  • apiClient.- for example: API_CLIENT
  • apiSecret.- for example: API_SECRET
  1. Calculate the token using base64, for this example:
$ echo -n "API_CLIENT:API_SECRET" | base64
  1. Request an access_token using the endpoint /v1/oauth2/token

For example:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic QVBJX0NMSUVOVDpBUElfU0VDUkVU" https://api.receeve-demo.com/v1/oauth2/token

Where:

  • QVBJX0NMSUVOVDpBUElfU0VDUkVU === base64(apiClient:apiSecret)

You should get a response that looks like:

{
    "access_token": "ACCESS_TOKEN",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Copy the ACCESS_TOKEN. It will expire in the number of seconds listed, but you will have enough time to use it for sending in some data.

2. Sending in the first claim

You have an OAuth token and so now you are ready to go. NOTE: Make sure to replace the clientId, the ACCESS_TOKEN, and then then email address in the call below.

It is important to note that the linking mechanism in our example is the field accountReference. Because this field is the same in our API calls, receeve will automatically link the claims together under a single account. So it is important before you begin to have selected the hierarchy of the information.

We are going to do two seperate calls in this example to simulate that the claims happened at different times. But you can place multiple claims into a single API call if you want.

First Call

curl -X POST https://api.receeve-demo.com/v1/{clientId}/create_claims -H 'Content-Type: application/json' -H 'Authorization: ACCESS_TOKEN' -d '{"A1-2001": {"amount": 10000,"currency": "EUR","portfolioReference": "yourPortfolioReference1","productReference": "yourProductReference","totalFees": 0,"originalDueDate": "2019-05-28","currentDueDate": "2019-06-28","paymentReference": "yourPaymentReference1","accountNumber": "accountNumberReference1","accountReference": "123456","meta": {"mySampleScore": "AAA"},"fees": [{"name": "Interest","amount": 120}],"primaryDebtor": {"birthday": "1980-06-28","gender": "M","firstName": "Bob","lastName": "White","middleName": "Benedict","title": "Doctor","companyName": "Acme Brick Co.","debtorReference": "string","contactInformation": {"country": "DE","city": "Delbrück","mobileNumber": 495555555555,"postalCode": 33129,"addressLine1": "Boikweg 24","addressLine2": "c/o Acme","addressLine3": "additional information","landLine": 495555555555,"state": "Dortmund","email": "testEmail@example.com"}}}}'

You should get a response that looks like:

{
    "A1-2001": {
        "success": true,
        "messages": []
    }
}

3. The second claim

Now you're ready to send in the second claim.

Second Call

curl -X POST https://api.receeve-demo.com/v1/{clientId}/create_claims -H 'Content-Type: application/json' -H 'Authorization: ACCESS_TOKEN' -d '{"A1-2002": {"amount": 33000,"currency": "EUR","portfolioReference": "yourPortfolioReference1","productReference": "yourProductReference","totalFees": 0,"originalDueDate": "2019-05-28","currentDueDate": "2019-06-28","paymentReference": "yourPaymentReference1","accountNumber": "accountNumberReference1","accountReference": "123456","meta": {"mySampleScore": "AAA"},"fees": [{"name": "Interest","amount": 120}],"primaryDebtor": {"birthday": "1980-06-28","gender": "M","firstName": "Bob","lastName": "White","middleName": "Benedict","title": "Doctor","companyName": "Acme Brick Co.","debtorReference": "string","contactInformation": {"country": "DE","city": "Delbrück","mobileNumber": 495555555555,"postalCode": 33129,"addressLine1": "Boikweg 24","addressLine2": "c/o Acme","addressLine3": "additional information","landLine": 495555555555,"state": "Dortmund","email": "testEmail@example.com"}}}}'

You should get a response that looks like:

{
    "A1-2002": {
        "success": true,
        "messages": []
    }
}

And that's it. Both claims are now linked to the same account identifier 123456. If you go to the back office application, you can search for that account ID and then see both claims inside of the account manager.

4. Stop the claims

Now imagine that Bob paid the money to you in cash for some reason. So there was no digital record of it captured by receeve directly. You would want to tell receeve that the claims are now paid and to stop the process. You need one more API call to do so:

curl -X POST https://api.receeve-demo.com/v1/{clientId}/resolve_claims -H 'Content-Type: application/json' -H 'Authorization: ACCESS_TOKEN' -d '[{"ref": "A1-2001","reason": "CLAIM_PAID"},{"ref": "A1-2002","reason": "CLAIM_PAID"}]'

You should get a response that looks like:

{
    "A1-2001": {
        "success": true,
        "messages": []
    },
    "A1-2002": {
        "success": true,
        "messages": []
    }
}

Recap

You've now authenticated yourself, and simply sent two claims that are part of a single account. Once they were paid, you stopped the processing on them. There are a variety of use cases that you may want to implement for your organization, but you now have the basics to get up and running in order to do so. You can test sending different meta data, amounts, or whatever you would like to test out in the strategy by modifying the payload in the above example. Or feel free to use the Postman collection in order to save different scenarios to test and integrate.

ON THIS PAGE