Skip to content

Partial Returns Guide

Documentation version 1.01, 12.09.2025

The current document contains information on how partial returns can be performed for Hire Purchase or Pay in parts / Split into parts contracts via Inbank API. The process description can be found in the API Request Flow chapter. Note that unlike most of other Inbank API endpoints, the endpoints for the partial returns process include v3 and not v2 in the request URL.

Please note, that the current document is applicable to partial returns only, if you would like to implement full contact withdrawal, refer to Contract Withdrawal.

To test in the demo environment, please let us know as extra steps are needed from our side to ensure the return will work for your tests.

There are two preconditions for partial returns:

  • The return is possible starting from the next day of when the contract was made.
  • The contract should be paid out.

For any questions regarding the partial return integration process, contact Inbank at:

API Request Flow



*Note that steps number 3 and 5 can be skipped if needed.

Languages
Servers
Demo environment
https://demo-api.inbank.ee/
Live environment
https://api.inbank.ee/

Check if a partial return is available

Request

GET /partner/v3/shops/{shopUuid}/contracts/{contractUuid}/change-options

The endpoint returns the information on whether a partial return is possible and if so also the amount range within which the return can be submitted.

Security
bearerAuth
Path
shopUuidstringrequired

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuidstringrequired

The unique identifier of the contract.

Example: 788ec8c4-c497-470b-8505-2303f151d427
curl -i -X GET \
  https://demo-api.inbank.ee/partner/v3/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/contracts/788ec8c4-c497-470b-8505-2303f151d427/change-options \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Return contract change-options

Bodyapplication/json
optionsobject
Response
application/json
{
  "options": {
    "PARTIAL_RETURN": { … }
  }
}

Create new draft contract

Request

POST /partner/v3/shops/{shopUuid}/contracts/{contractUuid}/versions

Using this endpoint a partial return can be submitted to Inbank, which in turn creates a new contract version that needs to be reviewed using the Review updated payment schedule API request and, if all is fine, then confirmed using the Confirm the updated contract API request.

Security
bearerAuth
Path
shopUuidstringrequired

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuidstringrequired

The unique identifier of the contract.

Example: 788ec8c4-c497-470b-8505-2303f151d427
Bodyapplication/jsonrequired
contractChangeDetailsobject
curl -i -X POST \
  https://demo-api.inbank.ee/partner/v3/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/contracts/788ec8c4-c497-470b-8505-2303f151d427/versions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contractChangeDetails": [
      {
        "type": "PARTIAL_RETURN",
        "returnAmount": 58.65
      }
    ]
  }'

Responses

Create new draft contract version

Bodyapplication/json
uuidstring

The new draft contract version uuid.

statusstring

Status of the contract.

createdAtstring

Date and time of contract creation.

sourceContractChangeobject
pricingUuidstring

The pricing uuid.

paymentScheduleUuidstring

The payment schedule uuid.

consumerCreditInformationUuidstring

Consumer credit information uuid.

Response
application/json
{
  "uuid": "aa48230c-2b2f-4a33-a7b4-3ce1705a0721",
  "status": "DRAFT",
  "createdAt": "2023-05-31T15:22:02.095689040Z",
  "sourceContractChange": {
    "uuid": "83841538-b616-4f05-ab2d-69ad1a5f0cab",
    "fromContractVersionUuid": "9435e008-86a1-4303-ae48-a3259f35df78",
    "toContractVersionUuid": "aa48230c-2b2f-4a33-a7b4-3ce1705a0721",
    "createdAt": "2023-05-31T15:22:02.113096869Z",
    "entityCreatedBy": "5e97bbd2-b40a-4b24-bfdd-d0ee2e95bd2c",
    "contractChangeDetails": { … }
  },
  "pricingUuid": "0d8a822a-58e5-408c-9f69-1e7e0dfe8043",
  "paymentScheduleUuid": "aecbf130-31c0-4f1b-9ca9-f006467d8c43",
  "consumerCreditInformationUuid": "a6d3dfb7-767e-49b0-bdd7-3d03e615ece2"
}

Review updated payment schedule

Request

GET /partner/v3/shops/{shopUuid}/contracts/{contractUuid}/payment-schedules/{paymentScheduleUuid}

If the updated payment schedule needs to be reviewed prior to activating the contact with the updated amount, it can be retrieved using this endpoint.

Please note, that this endpoint is optional in the preces, so if you do not have the need to review the payment schedule, this step can be skipped.

Security
bearerAuth
Path
shopUuidstringrequired

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuidstringrequired

The unique identifier of the contract.

Example: 788ec8c4-c497-470b-8505-2303f151d427
paymentScheduleUuidstringrequired

The unique identifier of the payment schedule.

Example: eb81f17a-babc-41a7-88505-2303f151d427
curl -i -X GET \
  https://demo-api.inbank.ee/partner/v3/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/contracts/788ec8c4-c497-470b-8505-2303f151d427/payment-schedules/eb81f17a-babc-41a7-88505-2303f151d427 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Return payment schedule

Bodyapplication/json
uuidstring

The unique identifier of the payment schedule.

responseLevelstring

The response level.

periodstring

Period.

amountstring

Amount.

paymentDaystring

The payment day.

downPaymentAmountTotalstring

The total down payment amount.

netCreditAmountstring

The net credit amount.

paymentAmountMonthlystring

The monthly payment amount.

interestRateAnnualstring

The annual interes rate.

contractFeeAmountTotalstring

The total contract fee amount.

adminFeeAmountMonthlystring

The monthly admin fee amount.

adminFeeAmountTotalstring

The total admin fee amount.

insuranceFeeAmountTotalstring

The total insurance fee amount.

creditCostRateAnnualstring

The annual credit cost rate.

creditCostAmountTotalstring

The total credit cost amount.

residualAmountTotalstring

The total residual amount.

residualAmountPrcstring

The residual amount percent.

interestBearingAmountstring

The bearing interest bearing.

interestAmountTotalstring

The total interest amount.

repaymentsAmountTotalstring

The total repayments amount.

firstPaymentDatestring

The first payment date.

firstPaymentAmountstring

The first payment amount.

lastPaymentDatestring

The last payment date.

lastPaymentAmountstring

The last payment amount.

downPaymentMainPartstring

The down payment main part.

rowsTotalsobject

The row totals.

paymentScheduleItemsArray of items
Response
application/json
{
  "uuid": "aecbf130-31c0-4f1b-9ca9-f006467d8c43",
  "responseLevel": "full",
  "period": 12,
  "amount": 500,
  "paymentDay": 5,
  "downPaymentAmountTotal": 0,
  "netCreditAmount": 449.78,
  "paymentAmountMonthly": 41.24,
  "interestRateAnnual": 0,
  "contractFeeAmountTotal": 15,
  "adminFeeAmountMonthly": 2.5,
  "adminFeeAmountTotal": 30,
  "insuranceFeeAmountTotal": 0,
  "creditCostRateAnnual": 0.1685,
  "creditCostAmountTotal": 45,
  "residualAmountTotal": 0,
  "residualAmountPrc": 0,
  "interestBearingAmount": 464.78,
  "interestAmountTotal": 0,
  "repaymentsAmountTotal": 545,
  "firstPaymentDate": "2023-07-05",
  "firstPaymentAmount": 41.24,
  "lastPaymentDate": "2024-06-05",
  "lastPaymentAmount": 41.14,
  "downPaymentMainPart": 0,
  "rowsTotals": {
    "paymentAmountTotal": 494.78
  },
  "paymentScheduleItems": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}

Confirm the updated contract

Request

PATCH /partner/v3/shops/{shopUuid}/contracts/{contractUuid}/versions/{versionUuid}/activate

For the partial return to take effect, the updated contract needs to be confirmed. Please note, that after this request is sent, the updates will be instantly applied.

Security
bearerAuth
Path
shopUuidstringrequired

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuidstringrequired

The unique identifier of the contract.

Example: 788ec8c4-c497-470b-8505-2303f151d427
versionUuidstringrequired

The unique identifier of the verion.

Example: bd4hbfe4-babc-41a7-88505-2303f151d427
curl -i -X PATCH \
  https://demo-api.inbank.ee/partner/v3/shopsa93f1f44-d5dd-4469-bfcc-c1de9e969213/contracts/788ec8c4-c497-470b-8505-2303f151d427/versions/bd4hbfe4-babc-41a7-88505-2303f151d427/activate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

New version activated

Response
No content

Review the contract update history

Request

GET /partner/v3/shops/{shopUuid}/contracts/{contractUuid}/versions

The endpoint returns the change history for the contract, with UUIDS to the payment schedules and dates of the change.

Security
bearerAuth
Path
shopUuidstringrequired

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuidstringrequired

The unique identifier of the contract.

Example: 788ec8c4-c497-470b-8505-2303f151d427
curl -i -X GET \
  https://demo-api.inbank.ee/partner/v3/shopsa93f1f44-d5dd-4469-bfcc-c1de9e969213/contracts/788ec8c4-c497-470b-8505-2303f151d427/versions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Get versions

Bodyapplication/json
contractVersionsobject
Response
application/json
{
  "contractVersions": [
    { … }
  ]
}