Push data

Create a new business linked

To create a new business the usual authentication approach is followed except uidis not required. The uid along with an authentication token will be returned once the business is created. If the email supplied already has a stub account the account details will be returned in addition to the uid and token.

post

Authorizations

ApiKeyAuthTokenAuthAppIdAuthOAuth2OpenID

X-API-KeystringRequired

API key needed to access the endpoints

Body

application/jsonapplication/transit+msgpackapplication/transit+jsonapplication/edn

apikeystringOptional

appidstringOptional

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/business

HTTPcURLJavaScriptPython

POST /api/push/business HTTP/1.1
Host: test.connect.stub.africa
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 205

{
  "apikey": "text",
  "appid": "text",
  "data": {
    "businessname": "text",
    "firstname": "text",
    "lastname": "text",
    "industry": "text",
    "phone": "text",
    "vatregistered": true,
    "email": "text"
  },
  "webhook": "text",
  "signature": "text"
}

application/jsonapplication/transit+msgpackapplication/transit+jsonapplication/edn

No content

---

Update business information

Update the business data created by your app.

post

Authorizations

ApiKeyAuthTokenAuthAppIdAuthOAuth2OpenID

X-API-KeystringRequired

API key needed to access the endpoints

Body

application/jsonapplication/transit+msgpackapplication/transit+jsonapplication/edn

apikeystringOptional

appidstringOptional

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/business/update

HTTPcURLJavaScriptPython

POST /api/push/business/update HTTP/1.1
Host: test.connect.stub.africa
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 218

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": {
    "businessname": "text",
    "firstname": "text",
    "lastname": "text",
    "industry": "text",
    "phone": "text",
    "vatregistered": true,
    "email": "text"
  },
  "webhook": "text",
  "signature": "text"
}

application/jsonapplication/transit+msgpackapplication/transit+jsonapplication/edn

No content

---

Asynchronously record income

Record income and send it to the account of the business specified by the uid

post

Body

application/json

apikeystringRequired

appidstringRequired

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/income

HTTPcURLJavaScriptPython

POST /api/push/income HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 233

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": {
    "id": "text",
    "date": "text",
    "name": "text",
    "category": "text",
    "notes": "text",
    "currency": "ZAR",
    "amount": 1,
    "vat": 1,
    "productid": "text",
    "feeid": "text"
  },
  "webhook": "text",
  "signature": "text"
}

No content

---

Asynchronously record an expense

Create an expense and send it to the account of the business specified by the uid

post

Body

application/json

apikeystringRequired

appidstringRequired

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/expense

HTTPcURLJavaScriptPython

POST /api/push/expense HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 199

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": {
    "id": "text",
    "date": "text",
    "name": "text",
    "category": "text",
    "notes": "text",
    "currency": "ZAR",
    "amount": 1,
    "vat": 1
  },
  "webhook": "text",
  "signature": "text"
}

No content

---

Asynchronously record a sale

Record a sale and send it to the account of the business specified by the uid

post

Body

application/json

apikeystringRequired

appidstringRequired

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/sale

HTTPcURLJavaScriptPython

POST /api/push/sale HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 523

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": {
    "id": "text",
    "payment": {
      "id": "text",
      "date": "text",
      "name": "text",
      "category": "text",
      "currency": "ZAR",
      "amount": 1,
      "vat": 1
    },
    "items": [
      {
        "id": "text",
        "name": "text",
        "description": "text",
        "price": 1,
        "quantity": 1,
        "cost": 1,
        "costcurrency": "ZAR"
      }
    ],
    "customer": {
      "id": "text",
      "name": "text",
      "email": "text",
      "address": "text",
      "address2": "text",
      "suburb": "text",
      "city": "text",
      "postalcode": "text",
      "country": "text",
      "vatnumber": "text",
      "registrationnumber": "text"
    }
  },
  "webhook": "text",
  "signature": "text"
}

No content

---

Asynchronously record multiple income and expenses

Push a batch of income and expenses for a specific user.

post

Body

application/json

apikeystringRequired

appidstringRequired

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/many

HTTPcURLJavaScriptPython

POST /api/push/many HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 370

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": {
    "income": [
      {
        "id": "text",
        "date": "text",
        "name": "text",
        "category": "text",
        "notes": "text",
        "currency": "ZAR",
        "amount": 1,
        "vat": 1,
        "productid": "text",
        "feeid": "text"
      }
    ],
    "expenses": [
      {
        "id": "text",
        "date": "text",
        "name": "text",
        "category": "text",
        "notes": "text",
        "currency": "ZAR",
        "amount": 1,
        "vat": 1
      }
    ]
  },
  "webhook": "text",
  "signature": "text"
}

No content

---

Asynchronously push settlement data

Push settlement data including income records, expense records, and optional settlement summary. This endpoint creating new records or updating existing ones based on the provided ID. Income and expenses in the same batch are typically paid out together in a single bank deposit or settlement.

post

Authorizations

ApiKeyAuthTokenAuthAppIdAuthOAuth2OpenID

X-API-KeystringRequired

API key needed to access the endpoints

Body

application/jsonapplication/transit+msgpackapplication/transit+jsonapplication/edn

apikeystringRequired

appidstringRequired

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/settlement

HTTPcURLJavaScriptPython

POST /api/push/settlement HTTP/1.1
Host: test.connect.stub.africa
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 419

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": [
    {
      "income": [
        {
          "id": "text",
          "date": "text",
          "name": "text",
          "accountid": "text",
          "notes": "text",
          "currency": "ZAR",
          "amount": 1,
          "vat": 1,
          "productid": "text"
        }
      ],
      "expenses": [
        {
          "id": "text",
          "date": "text",
          "name": "text",
          "accountid": "text",
          "notes": "text",
          "currency": "ZAR",
          "amount": 1,
          "vat": 1
        }
      ],
      "settlement": {
        "id": "text",
        "amount": 1,
        "fee": 1,
        "date": "text"
      }
    }
  ],
  "webhook": "text",
  "signature": "text"
}

application/jsonapplication/transit+msgpackapplication/transit+jsonapplication/edn

No content

---

Asynchronously push settlement data using a file

This endpoint is complementary to the one above. Instead of send the data in the body of the payload. The path to file uploaded on s3 is included. File url must be one retrieved from Generate upload s3 URL

It is STRONGLY advised that a web hook is provided so that error can be received. Both success and errors will be sent to the URL provided.

post

Authorizations

ApiKeyAuthTokenAuthAppIdAuthOAuth2OpenID

X-API-KeystringRequired

API key needed to access the endpoints

Body

application/jsonapplication/transit+msgpackapplication/transit+jsonapplication/edn

apikeystringRequired

appidstringRequired

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/settlement-file

HTTPcURLJavaScriptPython

POST /api/push/settlement-file HTTP/1.1
Host: test.connect.stub.africa
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": {
    "url": "text",
    "date": "text"
  },
  "webhook": "text",
  "signature": "text"
}

application/jsonapplication/transit+msgpackapplication/transit+jsonapplication/edn

No content

Web hook responses on settlements

There are 3 states post the processing of a settlement.

1. When all the settlements are ingested successfully.

{
  ...
  "response": {
    "id": "user_abc123xyz",
    "error": false,
    "processed": 150
  },
 ...
}

When no settlements are ingested successfully. i.e. total failure

{
  ...
  "response": {
    "error": true,
    "message": "e.g. Error processing s3 file"
  },
  ...
}

When there is a partial failure

{
  ...
 "response": {
    "id": "user_abc123xyz",
    "error": true,
    "message": "Processed 20 settlements: 15 successful, 5 failed",
    "errors": [
      {
        "batch": 2,
        "settlements": 5,
        "settlement-ids": [
          "settlement_016",
          "settlement_017",
          "settlement_018",
          "settlement_019",
          "settlement_020"
        ],
        "error": "Transaction failed: Invalid date format for settlement date"
      }
    ]
  },
  ...
}

---

Asynchronously continue a subscription

Notify us that a subscription you are collecting on our behalf has been paid. This entitles the user to another month of access to stub premium.

post

Body

application/json

apikeystringRequired

appidstringRequired

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/subscription

HTTPcURLJavaScriptPython

POST /api/push/subscription HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": {
    "id": "text",
    "date": "text",
    "amount": 1
  },
  "webhook": "text",
  "signature": "text"
}

No content

Asynchronously cancel a subscription

Notify us that a subscription you are collecting on our behalf has been cancelled. This entitles the user to stub premium until the end of the current billing period. Please note that this doesn't cancel subscriptions set up from within stub.

post

Body

application/json

apikeystringRequired

appidstringRequired

uidstringRequired

webhookstringOptional

signaturestringOptional

Responses

200Success

No content

400Error

401Error

post

/api/push/cancellation

HTTPcURLJavaScriptPython

POST /api/push/cancellation HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "apikey": "text",
  "appid": "text",
  "uid": "text",
  "data": {
    "date": "text"
  },
  "webhook": "text",
  "signature": "text"
}

No content

Reset all transactional test data

This allows you to clear all the data in a test account except the basic account info and subscription status.

post

Body

application/json

apikeystringRequired

appidstringRequired

uidstringRequired

Responses

200Success

No content

400Error

401Error

post

/api/push/reset

HTTPcURLJavaScriptPython

POST /api/push/reset HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "apikey": "text",
  "appid": "text",
  "uid": "text"
}

No content