Partial Returns Guide

Documentation version 1.01, 21.06.2023

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.

Check if a partial return is available

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.

SecuritybearerAuth
Request
path Parameters
shopUuid
required
string

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuid
required
string

The unique identifier of the contract.

Example: 788ec8c4-c497-470b-8505-2303f151d427
Responses
200

Return contract change-options

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

get/partner/v3/shops/{shopUuid}/contracts/{contractUuid}/change-options
Request samples 
Response samples 
application/json
{
  • "options": {
    }
}
Create new draft contract
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 and, if all is fine, then activated.


SecuritybearerAuth 
Request 
path Parameters
shopUuid
required
string
The unique identifier of the shop.


 
 Example:  a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuid
required
string
The unique identifier of the contract.


 
 Example:  788ec8c4-c497-470b-8505-2303f151d427
Request Body schema: application/json
required
object
 
Responses 
201
Create new draft contract version


401
Unauthorized


403
Forbidden


404
Not Found


422
Unprocessable Entity


500
Internal Server Error


post/partner/v3/shops/{shopUuid}/contracts/{contractUuid}/versions
Request samples 
application/json
{
  • "contractChangeDetails": [
    ]
}
Response samples 
application/json
{
  • "uuid": "aa48230c-2b2f-4a33-a7b4-3ce1705a0721",
  • "status": "DRAFT",
  • "createdAt": "2023-05-31T15:22:02.095689040Z",
  • "sourceContractChange": {
    },
  • "pricingUuid": "0d8a822a-58e5-408c-9f69-1e7e0dfe8043",
  • "paymentScheduleUuid": "aecbf130-31c0-4f1b-9ca9-f006467d8c43",
  • "consumerCreditInformationUuid": "a6d3dfb7-767e-49b0-bdd7-3d03e615ece2"
}
Review updated payment schedule
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.      


SecuritybearerAuth 
Request 
path Parameters
shopUuid
required
string
The unique identifier of the shop.


 
 Example:  a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuid
required
string
The unique identifier of the contract.


 
 Example:  788ec8c4-c497-470b-8505-2303f151d427
paymentScheduleUuid
required
string
The unique identifier of the payment schedule.


 
 Example:  eb81f17a-babc-41a7-88505-2303f151d427
Responses 
200
Return payment schedule


401
Unauthorized


403
Forbidden


404
Not Found


500
Internal Server Error


get/partner/v3/shops/{shopUuid}/contracts/{contractUuid}/payment-schedules/{paymentScheduleUuid}
Request samples 
Response samples 
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": {
    },
  • "paymentScheduleItems": [
    ]
}
Activate the updated contract
PATCH /partner/v3/shops/{shopUuid}/contracts/{contractUuid}/versions/{versionUuid}/activate


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


SecuritybearerAuth 
Request 
path Parameters
shopUuid
required
string
The unique identifier of the shop.


 
 Example:  a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuid
required
string
The unique identifier of the contract.


 
 Example:  788ec8c4-c497-470b-8505-2303f151d427
versionUuid
required
string
The unique identifier of the verion.


 
 Example:  bd4hbfe4-babc-41a7-88505-2303f151d427
Responses 
204
New version activated


401
Unauthorized


403
Forbidden


404
Not Found


500
Internal Server Error


patch/partner/v3/shops{shopUuid}/contracts/{contractUuid}/versions/{versionUuid}/activate
Request samples 
Response samples 
application/json
{
  • "message": "unauthorized"
}
Review the contract update history
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.      


SecuritybearerAuth 
Request 
path Parameters
shopUuid
required
string
The unique identifier of the shop.


 
 Example:  a93f1f44-d5dd-4469-bfcc-c1de9e969213
contractUuid
required
string
The unique identifier of the contract.


 
 Example:  788ec8c4-c497-470b-8505-2303f151d427
Responses 
200
Get versions


401
Unauthorized


403
Forbidden


404
Not Found


422
Unprocessable Entity


500
Internal Server Error


get/partner/v3/shops{shopUuid}/contracts/{contractUuid}/versions
Request samples 
Response samples 
application/json
{
  • "contractVersions": [
    ]
}