🏬Payments

Intro

This guide describes how to notify the Realpad system of exactly one incoming payment from a customer (buyer) to the real estate developer. This payment typically starts in the accounting software used by the real estate developer, but it can also be taken from the bank statement, cash desk information and similar.

The intended usage of this API endpoint is as follows:

• The synchronization is triggered based on the business requirements. Typical use case is to synchronize payments every night, but it's also possible to synchronize payments in real-time, as they arrive.

• Best practice is to always synchronize past several days of payments. Realpad can easily identify the payments it has already seen (based on the id parameter) and skip them. Sending several days of payments means that even in the case that the synchronization does not run for a period of time, it will correctly synchronize all the data once it runs.

• The integration should identify all the payments it needs to synchronize:

  • "Registration date should be in the past N days" - see the previous point.

  • "Payment should be transferred to Realpad CRM" - depends on how the real estate developer has the accounts set up. Ideally there is one or more dedicated bank accounts for receiving customer (buyer) payments. If not, some other method of determining which payments should be synchronized must be used.

• Once the payments are identified, the API endpoint described below should be invoked for each of them in turn.

• Full log of the synchronization should be stored: which payments were synchronized to the API endpoint, and what was the API response in each case.

Request

The endpoint is stateless, meaning the server does not keep any sessions and you have to send the login credentials with each request. The endpoint to use is

https://cms.realpad.eu/ws/v10/add-incoming-payment

All the API calls must be performed using the HTTP POST method, using the x-www-form-urlencoded encoding (i.e. no JSON, just a set of key-value pairs).

Parameters

• login - mandatory string, the login from the credentials.

• password - mandatory string, the password from the credentials in plain text.

• id - mandatory string, unique identifier of the payment in the accounting software. Realpad uses this as an "external ID" to recognize payments it has seen before.

• timestamp - mandatory string, date and time in the ISO 8601 format (2023-01-20T20:04:30) when this payment has either:

  • Arrived to the account of the real estate developer, OR

  • The accounting software first discovered it, OR

  • Any other date and time, in this case the value must not change later.

• accountno - mandatory string, account number (123-56789) where the payment was sent from. If the account number is given as IBAN, specify it here.

• accountbank - mandatory string, bank number (0300) where the payment was sent from. If the account number is given as IBAN, set the value "IBAN" to this field.

• accountholder - mandatory string, optional name of the account holder, as it appears on the statement.

• amount - mandatory number, formatted without any currency information, without thousands separator, with dot "." as (optional) decimal separator. The amount may be positive, negative or zero. The amount should be in the primary currency used by the developer, or converted to it - Realpad only handles payments in one currency at a time!

• amountnovat - number, optional, if present then it must follow the same format rules as amount. If specified, Realpad will use this value to determine the VAT rate, if not, it will try to detect it automatically from the main unit of the deal.

• symvar - string, optional "variable symbol" of the payment. Under typical circumstances, this is the value that is used when finding the deal to associate the payment with, in other words, the "pairing symbol".

• symconst - string, optional "constant symbol" of the payment.

• symspec - string, optional "specific symbol" of the payment.

• note - string, freeform text further identifying the payment.

• bankaccountid - integer, Realpad database ID of the bank account this payment arrived to. Contact us to tell you the IDs you should use.

• projectid - integer, Realpad database ID of the project this payment is meant for. In case the variable symbol is not unique across projects and this parameter is empty, the payment will not be matched.

• customchangepayment - String, if "true" then this payment is considered to be "for custom changes". Any other value including not sending this parameter as all is interpreted as "normal payment".

Payment symbols and note are not required, as not every payment must contain them. However, as they can simplify manual payment identification and pairing, they should be provided whenever possible.

Response

The response consists of the HTTP Status Code and, if the call was successful, a payment identifier in plain text.

Status codes

• 201 CREATED - all was fine, the call succeeded, the payment has been registered in the Realpad system and the response text contains its new internal identifier.

• 200 OK - all was fine, the call succeeded, the payment however has been already in the Realpad system and has not been updated. The response text contains the internal identifier in the Realpad system.

• 401 NOT AUTHORIZED - the credentials are invalid OR the account or the requesting IP is banned. Please contact the Realpad team in this case.

• 400 BAD REQUEST - the additional HTTP status text will specify the reason. Parameters could be missing or unexpected, or their format could be wrong.

• 418 - The requested API version is deprecated. Please contact the Realpad team in this case.

Sign up to receive updates!