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.

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": [
    ]
}