# Push data ### Create a new business linked To create a new business the usual authentication approach is followed except `uid`is 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 /api/push/business > ```json {"openapi":"3.1.0","info":{"title":"stub Connect API","version":"1.0.1"},"servers":[{"url":"https://test.connect.stub.africa"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"AppIdAuth":[]},{"OAuth2":["openid"]},{"OpenID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key needed to access the endpoints"},"TokenAuth":{"type":"apiKey","in":"header","name":"X-Token","description":"Token needed to access the endpoints"},"AppIdAuth":{"type":"apiKey","in":"header","name":"X-AppId","description":"AppId needed to access the endpoints"},"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://auth.stub.africa/.well-known/openid-configuration"}}},"paths":{"/api/push/business":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"required":["businessname","firstname","lastname","email"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["data"],"additionalProperties":false}},"application/transit+msgpack":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"required":["businessname","firstname","lastname","email"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["data"],"additionalProperties":false}},"application/transit+json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"required":["businessname","firstname","lastname","email"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["data"],"additionalProperties":false}},"application/edn":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"required":["businessname","firstname","lastname","email"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["data"],"additionalProperties":false}}}},"responses":{"200":{},"400":{},"401":{}},"tags":["Push data"]}}}} ``` *** ### Update business information Update the business data created by your app. ## POST /api/push/business/update > ```json {"openapi":"3.1.0","info":{"title":"stub Connect API","version":"1.0.1"},"servers":[{"url":"https://test.connect.stub.africa"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"AppIdAuth":[]},{"OAuth2":["openid"]},{"OpenID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key needed to access the endpoints"},"TokenAuth":{"type":"apiKey","in":"header","name":"X-Token","description":"Token needed to access the endpoints"},"AppIdAuth":{"type":"apiKey","in":"header","name":"X-AppId","description":"AppId needed to access the endpoints"},"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://auth.stub.africa/.well-known/openid-configuration"}}},"paths":{"/api/push/business/update":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["uid","data"],"additionalProperties":false}},"application/transit+msgpack":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["uid","data"],"additionalProperties":false}},"application/transit+json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["uid","data"],"additionalProperties":false}},"application/edn":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["uid","data"],"additionalProperties":false}}}},"responses":{"200":{},"400":{},"401":{}},"tags":["Push data"]}}}} ``` *** ### Asynchronously record income Record income and send it to the account of the business specified by the `uid` {% openapi src="" path="/api/push/income" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} *** ### Asynchronously record an expense Create an expense and send it to the account of the business specified by the `uid` {% openapi src="" path="/api/push/expense" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} *** ### Asynchronously record a sale Record a sale and send it to the account of the business specified by the `uid` {% openapi src="" path="/api/push/sale" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} *** ### Asynchronously record multiple income and expenses Push a batch of income and expenses for a specific user. {% openapi src="" path="/api/push/many" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} *** ### 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 /api/push/settlement > ```json {"openapi":"3.1.0","info":{"title":"stub Connect API","version":"1.0.1"},"servers":[{"url":"https://test.connect.stub.africa"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"AppIdAuth":[]},{"OAuth2":["openid"]},{"OpenID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key needed to access the endpoints"},"TokenAuth":{"type":"apiKey","in":"header","name":"X-Token","description":"Token needed to access the endpoints"},"AppIdAuth":{"type":"apiKey","in":"header","name":"X-AppId","description":"AppId needed to access the endpoints"},"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://auth.stub.africa/.well-known/openid-configuration"}}},"paths":{"/api/push/settlement":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"income":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"},"productid":{"type":"string"}},"required":["id"],"additionalProperties":false}},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"}},"required":["id"],"additionalProperties":false}},"settlement":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"date":{"type":"string"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false}},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/transit+msgpack":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"income":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"},"productid":{"type":"string"}},"required":["id"],"additionalProperties":false}},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"}},"required":["id"],"additionalProperties":false}},"settlement":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"date":{"type":"string"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false}},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/transit+json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"income":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"},"productid":{"type":"string"}},"required":["id"],"additionalProperties":false}},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"}},"required":["id"],"additionalProperties":false}},"settlement":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"date":{"type":"string"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false}},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/edn":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"income":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"},"productid":{"type":"string"}},"required":["id"],"additionalProperties":false}},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"}},"required":["id"],"additionalProperties":false}},"settlement":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"date":{"type":"string"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false}},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}}}},"responses":{"200":{},"400":{},"401":{}},"tags":["Push data"]}}}} ``` *** ### 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](https://developers.stub.africa/pull-data#generate-upload-s3-url "mention") 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 /api/push/settlement-file > ```json {"openapi":"3.1.0","info":{"title":"stub Connect API","version":"1.0.1"},"servers":[{"url":"https://test.connect.stub.africa"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"AppIdAuth":[]},{"OAuth2":["openid"]},{"OpenID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key needed to access the endpoints"},"TokenAuth":{"type":"apiKey","in":"header","name":"X-Token","description":"Token needed to access the endpoints"},"AppIdAuth":{"type":"apiKey","in":"header","name":"X-AppId","description":"AppId needed to access the endpoints"},"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://auth.stub.africa/.well-known/openid-configuration"}}},"paths":{"/api/push/settlement-file":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string"},"date":{"type":"string"}},"required":["url","date"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/transit+msgpack":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string"},"date":{"type":"string"}},"required":["url","date"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/transit+json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string"},"date":{"type":"string"}},"required":["url","date"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/edn":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string"},"date":{"type":"string"}},"required":["url","date"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}}}},"responses":{"200":{},"400":{},"401":{}},"tags":["Push data"]}}}} ``` #### Web hook responses on settlements There are 3 states post the processing of a settlement. 1. When all the settlements are ingested successfully. ```json { ... "response": { "id": "user_abc123xyz", "error": false, "processed": 150 }, ... } ``` When no settlements are ingested successfully. i.e. total failure ```json { ... "response": { "error": true, "message": "e.g. Error processing s3 file" }, ... } ``` When there is a partial failure ```json { ... "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. {% openapi src="" path="/api/push/subscription" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} ### 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. {% openapi src="" path="/api/push/cancellation" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} ### 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. {% openapi src="" path="/api/push/reset" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %}