Get Settlement

GET /settlements/{id}

Try it

Parameters

X-Correlation-IDheaderid*path

Request sampleLanguage

curl -X GET 'https://one.ozow.com/v1/settlements/string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'X-Correlation-ID: 00000000-0000-0000-0000-000000000000'

Response exampleStatus

{
  "links": {
    "self": "https://one.ozow.com/v1/settlements/497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "lineItems": "https://one.ozow.com/v1/settlements/497f6eca-6276-4993-bfeb-53cbbbba6f08/lineitems"
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "totalSettlement": {
    "currency": "ZAR",
    "value": 50
  },
  "totalFees": {
    "currency": "ZAR",
    "value": 50
  },
  "lineItemCounts": {
    "total": 128,
    "transaction": 119,
    "refund": 4,
    "adjustment": 2,
    "payout": 3
  },
  "reference": "OZOWSTL0004821",
  "date": "2020-04-19",
  "bank": {
    "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
    "institutionName": "Demo Bank",
    "accountNumber": "1234567890",
    "branchCode": "5040"
  }
}

Built from the response schema. Values are placeholders, not real data.

GEThttps://one.ozow.com/v1/settlements/{id}Production

Retrieve a settlement by it's unique identifier.

Authentication

OAuth 2.0
scopessettlements

Path parameters

id string required
The settlement identifier.

Header parameters

X-Correlation-ID string
Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header.

Responses

200 OK

X-Correlation-ID header
The correlation id for the request that was processed.

links object required
Links related to this resource.
- self string uri required
  The unique URI to this resource.
- lineItems string uri required
  The URI to list the line items associated with this settlement.
id string uuid required
The unique id for this settlement.
totalSettlement Amount required
The total amount being settled.
Fields of Amount
- currency string required
  The ISO 4217 current code.
  min length3max length3
- value number float required
  The amount in the currency specified.
  min0.01
Open Amount on its own page
totalFees Amount required
The total fees deducted from all corresponding transactions before calculating the settlement amount. The fees for each line item record may not add up to this fee because of rounding and this fee will be calculated off total amounts or counts.
Fields of Amount
- currency string required
  The ISO 4217 current code.
  min length3max length3
- value number float required
  The amount in the currency specified.
  min0.01
Open Amount on its own page
lineItemCounts object required
The line item counts for each type available. total is always present; a type with no line items in this settlement is left out rather than returned as zero.
- total integer required
  The total number of line items in the settlement.
- transaction integer
  The number of transaction line items in the settlement.
- refund integer
  The number of refund line items in the settlement.
- adjustment integer
  The number of adjustment line items in the settlement.
- payout integer
  The number of payout line items in the settlement.
reference string required
The unique settlement reference that will be present in the reference on your bank statement.
max length50
date string date required
The UTC date the settlement was created.
bank BankAccount
Fields of BankAccount
- institutionId string uuid required
  The unique identifier of the institution.
- institutionName string
  The name of the institution.
- accountNumber string required
  The bank account number.
- branchCode string required
  The branch code of the account.
  max length10
Open BankAccount on its own page

400 Bad Request.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

A field in the request body did not validate

{
  "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83",
  "links": null,
  "code": "BadRequest",
  "title": "Bad Request",
  "detail": "amount: Amount must be greater than 0",
  "source": {
    "pointer": "/amount",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

401 Unauthorised.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

No usable access token on the request

{
  "id": "1cecc2b7-1c29-418a-b26a-bf7546926083",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Unauthorized",
  "title": "Unauthorized Request",
  "detail": "Authorization header is missing or invalid.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": null
}

500 Internal Server Error.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

The request failed on the Ozow side

{
  "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97",
  "links": null,
  "code": "InternalServerError",
  "title": "Internal Server Error",
  "detail": "Error occurred while processing request.",
  "source": {
    "pointer": "/data",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Request

curl -X GET 'https://one.ozow.com/v1/settlements/string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'X-Correlation-ID: 00000000-0000-0000-0000-000000000000'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://one.ozow.com/v1/settlements/string");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("X-Correlation-ID", "00000000-0000-0000-0000-000000000000");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://one.ozow.com/v1/settlements/string',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_ACCESS_TOKEN',
        'X-Correlation-ID: 00000000-0000-0000-0000-000000000000',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

const response = await fetch("https://one.ozow.com/v1/settlements/string", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "X-Correlation-ID": "00000000-0000-0000-0000-000000000000",
  },
});

const data = await response.json();

import requests

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "X-Correlation-ID": "00000000-0000-0000-0000-000000000000",
}

response = requests.get(
    "https://one.ozow.com/v1/settlements/string",
    headers=headers,
)

Response

{
  "links": {
    "self": "https://one.ozow.com/v1/settlements/497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "lineItems": "https://one.ozow.com/v1/settlements/497f6eca-6276-4993-bfeb-53cbbbba6f08/lineitems"
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "totalSettlement": {
    "currency": "ZAR",
    "value": 50
  },
  "totalFees": {
    "currency": "ZAR",
    "value": 50
  },
  "lineItemCounts": {
    "total": 128,
    "transaction": 119,
    "refund": 4,
    "adjustment": 2,
    "payout": 3
  },
  "reference": "OZOWSTL0004821",
  "date": "2020-04-19",
  "bank": {
    "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
    "institutionName": "Demo Bank",
    "accountNumber": "1234567890",
    "branchCode": "5040"
  }
}

Built from the response schema. Values are placeholders, not real data.

Bad Request.

{
  "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83",
  "links": null,
  "code": "BadRequest",
  "title": "Bad Request",
  "detail": "amount: Amount must be greater than 0",
  "source": {
    "pointer": "/amount",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Unauthorised.

{
  "id": "1cecc2b7-1c29-418a-b26a-bf7546926083",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Unauthorized",
  "title": "Unauthorized Request",
  "detail": "Authorization header is missing or invalid.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": null
}

Internal Server Error.

{
  "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97",
  "links": null,
  "code": "InternalServerError",
  "title": "Internal Server Error",
  "detail": "Error occurred while processing request.",
  "source": {
    "pointer": "/data",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}