Callback structure

Tracked properties

Organization callback

When an organization is created through Embedded Funding (object financing) API, a callback URL can be provided in the request through status_callback property.

This URL will be used to send out a callback message on specific events pertaining to organization properties. Properties that are currently tracked through this callback are:

• Credit limit and any change related to it (e.g. credit status)

• Credit balance (total amount - borrowed amount)

Limit request callback

When a limit request is created, another callback URL can be provided through the status_callback property.

This URL will be used to send out a callback message on specific events pertaining to limit request property changes. Properties that are currently tracked through this callback are:

• Limit request status (pending, approved, rejected, canceled)

Withdrawal request callback

When a withdrawal request is created, another callback URL can be provided in the request through status_callback property. 

This URL will be used to send out a callback message on specific events pertaining to withdrawal request properties. Only one property is currently tracked:

• Withdrawal request status (created, cancelled, rejected, accepted, paid out, etc.)

Any updates to these properties will be registered and sent out to this callback URL.

Loan callback

When a withdrawal request is created an additional callback URL can be provided through the loan_status_callback property.

This URL will be invoked when something happens on the loan that was created from the approved withdrawal request. The properties "companyId" and"loanId" are populated in the request payload.

Right now the callback is invoked when:

• A payment has been registered on a loan

Callback structure

Callback call contains following properties in simple JSON format:

{

"message" : 0, // Can be 0, 1, 2, 3 or 4.

"withdrawalId" : "39770189-a190-438d-8210-e425181157c4",

"companyId" : "83203410-df0e-4bff-bb79-cd94535a4cbe",

"limitRequestId": "23203210-af0e-sadf-9079-1157c45a4cbe",

"loanId": "34503210-af0b-sadf-9079-2252c45a4cbe"

}

Message mapping:

• 0 is CreditLimitUpdated

• 1 is WithdrawalRequestStatusChanged

• 2 is CreditBalanceUpdated

• 3 is LimitRequestStatusChanged

• 4 is LoanPaymentRegistered

Identifiers are related to the actual event and might differ depending on the actual message. For example, when CreditLimitUpdated message is sent, withdrawalId is null, because the event is not tied to the withdrawal request in any way.

Callback handling

It’s up to the callback provider to decide how to handle the callback message. An example would be that, in case that system that provided the callback handles some kind of internal state of some of these properties like credit limit or balance, that system can, once it gets the callback (e.g. CreditLimitUpdated), update that internal state. The updated data can be retrieve e.g. by calling the GetCreditStatus API and using that response to update the data or inform the customer about the change.

Informal mapping:

• If CreditLimitUpdated or CreditBalanceUpdated , system can call:

  • GET /v1/companies/{companyId}/status

  • GET /v1/companies/{companyId}/terms

• If WithdrawalRequestStatusChanged, system can call:

  • GET /v1/companies/{companyId}/withdrawal/{withdrawalRequestId}

  • GET /v1/companies/{companyId}/withdrawal/{withdrawalRequestId}/status

• If LimitRequestStatusChanged, system can call:

  • GET /v1/companies/{companyId}/limit-requests/{limitRequestId}/status

• if LoanPaymentRegistered, the system can call:

  • GET /v1/companies/{companyId}/loans/{loanId}to get the detailed information on the payment done on the loan.

Endpoints listed here and their description can be further explored in the Swagger specification or this portal.

IP Whitelisting

If you have a firewall using IP whitelisting you will need to whitelist the following IP addresses:

• 20.82.192.194

• 20.67.208.150

• 20.105.65.222

• 20.93.102.228