Zetl APIInstant Settlement Request
INFO
This documentation is work in progress and subject to change. If you have any questions or feedback, please reach out to us via Support.
This object represents an Instant Settlement request data for your customer. It lets you manage Instant Settlement requests that belong to the customer.
Instant Settlement Object
| Property | Type | Description |
|---|---|---|
| funding_id | string | Unique identifier of the funding object (Assigned by Zetl). |
| customer_id | string | Zetl-generated customer ID |
| currency | string (exactly 3) | Currency of funding request (ISO 4217 currency code). See: Supported Currencies |
| amount | numeric | Amount of funding request (in minor unit). See: Supported Currencies |
| account_chargeback_rate | numeric (min. 0, max. 1) | Current account chargeback rate of the user (Represented in decimal, for example: 3% chargeback rate should be send as 0.03) |
| account_refund_rate | numeric (min. 0, max. 1) | Current account refund rate of the user (Represented in decimal, for example: 3% refund rate should be send as 0.03) |
| settlement_period | numeric | Transaction settlement period of the user (Represented in days). |
| interest_rate | numeric (min. 0, max. 1) | Interest rate of the funding request (Represented in decimal, for example: 0.2% interest rate will be send as 0.002) |
| transactions | object | Historical transaction data of the user (Partner-supplied information in any valid JSON key-value format) |
| status | string (enum) | Status of funding request. See: Funding Status |
| created_at | string | Resource creation ISO datetime string (UTC) |
| updated_at | string | Resource last modified ISO datetime string (UTC) |
Partner-feature
Some partner might use null value for account_chargeback_rate and account_refund_rate depending on partnership configuration
Funding Status
| Status | Description |
|---|---|
| submitted | Funding request has been submitted to Zetl for review. |
| approved | Funding request has been approved by Zetl. |
| denied | Funding request has been denied by Zetl. |
| accepted | Funding request has been accepted by the customer. |
| rejected | Funding request has been rejected by the customer. |
| funded | Funding request has been funded by Zetl (money has been disbursed to customer). |
| repaid | Funding request has been repaid by the customer. |
Auto-Accepted Offer
Some partner might skip decision flow and found their funding offer auto-accepted depending on partnership configuration
Instant Settlement Example
{
"funding_id": "c6241b71-4340-4710-a304-0409124ff87c",
"customer_id": "b8a1dfe0-c575-4d5c-9840-2fca96b5d96a",
"currency": "HKD",
"amount": 100000,
"account_chargeback_rate": 0.03,
"account_refund_rate": 0.03,
"settlement_period": 7,
"interest_rate": 0.0049,
"transactions": {
"transaction_list": [
{
"transaction_id": "c6241b71-4340-4710-a304-0409124ff87c",
"transaction_date": "2023-11-29",
"transaction_currency": "HKD",
"transaction_amount": 100000,
"transaction_status": "success",
"transaction_type": "sale",
"transaction_settlement_date": "2023-12-07",
"settlement_status": "settled"
}
],
"transaction_count": 1,
"total_amount": 100000
},
"status": "approved",
"created_at": "2023-12-01T00:02:00Z",
"updated_at": "2023-12-01T00:02:00Z"
}Create Instant Settlement Request
POST /v1/instant-settlements
https://api.zetl.com/v1/instant-settlements
Submit a instant settlement request for your customer.
Request Properties
| Property | Type | Description |
|---|---|---|
| customer_rate | string | Zetl-generated user ID |
| currency | string (exactly 3) | Currency of funding request (ISO 4217 currency code). See: Supported Currencies |
| amount | numeric | Amount of funding request (in minor unit). See: Supported Currencies |
| account_chargeback_rate | numeric (min. 0, max. 1) | Current account chargeback rate of the user (Represented in decimal, for example: 3% chargeback rate should be send as 0.03) |
| account_refund_rate | numeric (min. 0, max. 1) | Current account refund rate of the user (Represented in decimal, for example: 3% refund rate should be send as 0.03) |
| settlement_period | numeric (enum) | Transaction settlement period of the user (Represented in days). |
| transactions | object | Historical transaction data of the user (Partner-supplied information in any valid JSON key-value format) |
Partner-feature
Some partner might use null value for account_chargeback_rate and account_refund_rate depending on partnership configuration
Request Example
POST /v1/instant-settlements HTTP/1.1
Host: api.zetl.com
Content-Type: application/json
Authorization: Bearer <your-private-key>
{
"customer_id": "b8a1dfe0-c575-4d5c-9840-2fca96b5d96a",
"currency": "HKD",
"amount": 100000,
"account_chargeback_rate": 0.03,
"account_refund_rate": 0.03,
"settlement_period": 7,
"transactions": {
"transaction_list": [
{
"transaction_id": "c6241b71-4340-4710-a304-0409124ff87c",
"transaction_date": "2021-01-01",
"transaction_currency": "HKD",
"transaction_amount": 100000,
"transaction_status": "success",
"transaction_type": "sale",
"transaction_settlement_date": "2021-01-08",
"settlement_status": "settled"
}
],
"transaction_count": 1,
"total_amount": 100000
}
}curl --request POST \
--url https://api.zetl.com/v1/instant-settlements \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-private-key>' \
--data '{
"customer_id": "b8a1dfe0-c575-4d5c-9840-2fca96b5d96a",
"currency": "HKD",
"amount": 100000,
"account_chargeback_rate": 0.03,
"account_refund_rate": 0.03,
"settlement_period": 7,
"transactions": {
"transaction_list": [
{
"transaction_id": "c6241b71-4340-4710-a304-0409124ff87c",
"transaction_date": "2021-01-01",
"transaction_currency": "HKD",
"transaction_amount": 100000,
"transaction_status": "success",
"transaction_type": "sale",
"transaction_settlement_date": "2021-01-08",
"settlement_status": "settled"
}
],
"transaction_count": 1,
"total_amount": 100000
}
}'Response Properties
Refer to Instant Settlement object
Possible Error
See Handling Error for generic possible errors.
| Code | Description |
|---|---|
| kyc_incomplete | The customer haven't completed the KYC filling process. Complete the KYC information and any necessary supporting documents upload (See: KYC Information) |
Error Example
{
"error": {
"type": "invalid_request_error",
"code": "kyc_incomplete",
"message": "KYC is incomplete, please complete KYC first before requesting funding."
}
}Retrieve List of Instant Settlement (All)
GET /v1/instant-settlements
https://api.zetl.com/v1/instant-settlements
Get a list of instant settlement request owned by your business (all customers).
Query Parameters
See Pagination for generic URL query parameters available.
Response Properties
| Property | Type | Description |
|---|---|---|
| items | array of Instant Settlement | List of instant settlement funding owned by your business (transactions key omitted). |
| count | number | Total number of instant settlement funding owned by your business. |
Response Example
{
"items": [
{
"funding_id": "c6241b71-4340-4710-a304-0409124ff87c",
"customer_id": "b8a1dfe0-c575-4d5c-9840-2fca96b5d96a",
"currency": "HKD",
"amount": 100000,
"account_chargeback_rate": 0.03,
"account_refund_rate": 0.03,
"settlement_period": 7,
"interest_rate": 0.0049,
"status": "approved",
"created_at": "2023-12-01T00:02:00Z",
"updated_at": "2023-12-01T00:02:00Z"
}
],
"count": 1
}Possible Error
See Handling Error for generic possible errors.
Retrieve Instant Settlement resource
GET /v1/instant-settlements/{funding_id}
https://api.zetl.com/v1/instant-settlements/{funding_id}
Get details of a customer's instant settlement request
Response Properties
Refer to Instant Settlement object
Possible Error
See Handling Error for generic possible errors.
Retrieve List of Instant Settlement (Filtered)
GET /v1/customers/{customer_id}/instant-settlements
https://api.zetl.coom/v1/customers/{customer_id}/instant-settlements
Get a list of instant settlement request owned by your customer. Refer to Retrieve List of Instant Settlement (All)
Retrieve Instant Settlement resource (Filtered)
GET /v1/customers/{customer_id}/instant-settlements/{funding_id}
https://api.zetl.com/v1/customers/{customer_id}/instant-settlements/{funding_id}
Get details of a customer's instant settlement request. Refer to Retrieve Instant Settlement resource
Accept/Reject Instant Settlement Request
PUT /v1/instant-settlements/{funding_id}/decision
https://api.zetl.com/v1/instant-settlements/{funding_id}/decision
Accept or reject an instant settlement request.
Request Properties
| Property | Type | Description |
|---|---|---|
| type | string (enum) | Type of decision, (accept or reject). |
| reason | string? | Reason for rejection. (Required only for reject type decision). |
Request Example
POST /v1/instant-settlement/c6241b71-4340-4710-a304-0409124ff87c/decision HTTP/1.1
Host: api.zetl.com
Content-Type: application/json
Authorization: Bearer <your-private-key>
{
"type": "accept"
}curl --request POST \
--url https://api.zetl.com/v1/instant-settlement/c6241b71-4340-4710-a304-0409124ff87c/decision \
--header 'Authorization: Bearer <your-private-key>' \
--header 'Content-Type: application/json' \
--data '{"type": "accept"}'Response Properties
Refer to Instant Settlement object.
Possible Error
See Handling Error for generic possible errors.
| Code | Description |
|---|---|
| funding_status_invalid | The funding request is not in a valid status to be accepted/rejected. (Already denied / accepted / rejected / funded / repaid) |
Error Example
{
"error": {
"type": "invalid_request_error",
"code": "funding_status_invalid",
"message": "Instant settlement with funding_id \"c6241b71-4340-4710-a304-0409124ff87c\" is already rejected."
}
}