# Authorization
{% hint style="info" %}
Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.
{% endhint %}
## Get your API keys
Retrieve the API Keys from the Developers section within your account. Utilize this key as a bearer token in the Authorization header included with each request: **`Authorization: Bearer {{secretkey}}`**
## Base Url
{% hint style="success" %}
[https://gate.paytota.com/](https://gate.paytota.com/login)
{% endhint %}
# Webhooks
Define webhook rules to your server. The callback URL will receive a POST request with the related object's (e.g. Purchase for purchase.\* webhooks) data in body when any of the events is configured to listen for are triggered. The payload object will additionally include an **"event\_type"** field to indicate which event type triggered the webhook and **"status"** to indicate failure or success of the transaction.
The webhooks can be defined in the developer section of the client account.
Note that, as well as with the rest of dataset, test and live Webhooks are separate; test webhooks will not handle events caused by live Purchases, and vice-versa.
## Webhook Authorization
Payloads are signed using asymmetric A.K.A. public-key cryptography to guarantee the authenticity of delivered callbacks. Each callback delivery request includes an **X-Signature** header field. This field contains a base64-encoded RSA PKCS#1 v1.5 signature of the SHA256 digest of the request body buffer.
You can obtain the public key for Webhook authentication from Webhook.public\_key of the corresponding Webhook.
You can obtain the public key for success callback authentication from **GET {base\_url}/api/v1/public\_key/**
Please note the provider is not responsible for any financial losses incurred due to not implementing payload signature verification.
See below sample
{% tabs %}
{% tab title="PHP" %}
```php
```
{% endtab %}
{% tab title="JS" %}
```javascript
const crypto = require('crypto');
const data = "Hello World";
const signature = 'ktRxi//UUzVK8Pi5ICRSs5nCaK2g5Op+BM2mq4BK6zrb+A2392fiuFBoNj4yBWLfJxzzl1IwgVgQbjjrnbJ3i4kpYTZQ1nG82zpD7SAiF6qWq06YHR5Hrp0uvkiCKHt6pDYkXsCIph8VQqp61uplv3gifTtMRR1BGXwcxfWdrTheiFGWPnlijFaoMgLOG5CVfQAif9E7zx2ybDYtu2mMnxUWAld5bxNZXMKG87NGQ42tLaUE5OYv5yJz0kZZPZFZ5d0neGLAdm+Njf5zWlOw==';
const publicKeyPem = `-----BEGIN CERTIFICATE-----
MIIFMDCCBBigAwIBAgISA8MYezqjKnHZa+83lO64HqQoMA0GCSqGSIb3DQEBCwUA
MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQD
EwJSMzAeFw0yMzA2MTYxNjE0MjdaFw0yMzA5MTQxNjE0MjZaMB4xHDAaBgNVBAMT
E3BheW1lbnRzLmFmcml2ci5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK
AoIBAQDCFjhZsB7yR669TQ7mxWo9w7ajiT8Z3VZUrWSm0SKmsoxgQ1oDb1yDWIDU
fNCGQvaoRcxBfB+g9D3rhiGtX5oi8FhSFSEuNFXRN3kTVm8vRmfFdY45sjBdtF0j
8RjGwskqSzCzciXfSLoeKoLubUMcCTmUC9FLkwDqkQHedswcYG5AalvBqT7eqtBe
zip1+tVdZSVq79m5EJw98ccLF42cinkoqK76Mg2uss0mNuvpSxFN7gn/0XhaLl5U
5F2kwQr3qsijWLHqOm2cHyGOeiVScbJexvhnVMlJMEblHU/x/K6gZTCj4+O7KDgg
Gh3LHmZJ9sAtRudvM/16jGxIGoknAgMBAAGjggJSMIICTjAOBgNVHQ8BAf8EBAMC
BaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAw
HQYDVR0OBBYEFMJallKq+V5W8oqJPkmioUIvRMKGMB8GA1UdIwQYMBaAFBQusxe3
WFbLrlAJQOYfr52LFMLGMFUGCCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0
cDovL3IzLm8ubGVuY3Iub3JnMCIGCCsGAQUFBzAChhZodHRwOi8vcjMuaS5sZW5j
ci5vcmcvMFsGA1UdEQRUMFKCE3BheW1lbnRzLmFmcml2ci5jb22CDnNydi5hZnJp
dnIuY29tghd3d3cucGF5bWVudHMuYWZyaXZyLmNvbYISd3d3LnNydi5hZnJpdnIu
Y29tMBMGA1UdIAQMMAowCAYGZ4EMAQIBMIIBBAYKKwYBBAHWeQIEAgSB9QSB8gDw
AHYAtz77JN+cTbp18jnFulj0bF38Qs96nzXEnh0JgSXttJkAAAGIxTOECAAABAMA
RzBFAiBSb7ssu+4XK1NRsXnV4eeI7mHcnJm57p9enU/2N019QgIhAJLMIyZeb/Mf
P9NKPCbpeHp5ld48TS91Jm1Z4cPDjuyFAHYA6D7Q2j71BjUy51covIlryQPTy9ER
a+zraeF3fW0GvW4AAAGIxTOEBAAABAMARzBFAiAYr5lgHDg7JfQrMA4t9Z7GybWD
DfhS7/SJyklAwWNULAIhAPMBI4FKxrN91iIKiQN3OfD0ibiQGlQgHz9s5w6YInTa
MA0GCSqGSIb3DQEBCwUAA4IBAQCe1q3OaK9kakvORWXshHMw7aegML0YG7e/M8Ma
2KBkOAl9X0+Jy0c7Hn26fN6ZudWeOHE4PngY1tTKGoUm2PKVesYt7sP8Ivo+/NTo
B1+C/q1Mdwv/vcewmw2n6/flTnvvmw6s9zXpRVJJ2sD2jAwIByMNWN8naegz2f1g
3HEPOtKVosX0zYXpFflPkGTRui0FgpiCQq0/3MaFXAu3/aSbh6Fczb1/JaAswarK
LhlGP5mNHorLbFea+B7lmIeUf9gosUrZ3cjfBVKknWrBg//DzTpf+YS1nte+Kk6S
FoLSAh7OePSmFM0okO6iyDLxmGFAja2D+CZCQbR5Y+TVi7T1
-----END CERTIFICATE-----`;
function verifySignature(publicKeyPem, data, signature) {
const publicKey = crypto.createPublicKey(publicKeyPem);
const verifier = crypto.createVerify('SHA256');
verifier.update(data);
const isVerified = verifier.verify(publicKey, Buffer.from(signature, 'base64'));
return isVerified;
}
const result = verifySignature(publicKeyPem, data, signature);
if (result) {
console.log("good");
} else {
console.log("bad");
}
```
{% endtab %}
{% endtabs %}
# Account Balance
## This API method is used to retrieve Account balance
`GET` `{base url}/api/v1/account/json/balance/`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | --------------------------- |
| Authorization\* | | Bearer **`{{secret key}}`** |
| Content-Type\* | String | application/json |
{% tabs %}
{% tab title="201: Created " %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Response" %}
```json5
{
"UGX": {
"balance": 2710,
"fee_sell": 2590,
"reserved": 0,
"gross_balance": 5300,
"payout_balance": 1000,
"payout_fee_sell": 0,
"pending_payouts": 0,
"payout_overdraft": 0,
"pending_outgoing": 1500,
"available_balance": 1210,
"payout_gross_balance": 1000,
"available_payout_balance": 1000
}
}
```
{% endtab %}
{% tab title="Description" %}
| description: | Company Balance in a specific currency |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| gross\_balance |
Raw Company balance without any fees or reserved amounts subtracted
|
| balance |
Company gross balance with transaction fees subtracted
|
| available\_balance |
Company balance currently available for withdrawal
|
| reserved |
Amount protected from withdrawal for an amount of time as per the brand configuration
|
| pending\_outgoing |
Amount currently pending withdrawal
|
| fee\_sell |
FeeSellinteger
Fees applied to transactions
|
| {% endtab %} | |
| {% endtabs %} | |
# Quick payment (simplified)
Use this flow when you only need **one API call** and a **redirect** to Paytota’s checkout. No Step 2 or form-data required.
1. **Create** a purchase with a minimal payload (below).
2. **Redirect** the customer to the `checkout_url` from the response.
3. **Result**: the customer pays on Paytota; they are sent back to your `success_redirect` or `failure_redirect`, and you receive a webhook (`purchase.paid` or `purchase.error`).
`POST` `{base url}/api/v1/purchases/`
**Headers:** `Authorization: Bearer {{secret key}}`, `Content-Type: application/json`
**Minimal payload:**
```json5
{
"client": {
"email": "customer@example.com",
"phone": "256770123456",
"country": "UG"
},
"purchase": {
"currency": "UGX",
"products": [{ "name": "Item", "price": "500" }]
},
"reference": "your-unique-ref-123",
"brand_id": "{{BrandId}}",
"success_redirect": "https://yoursite.com/success",
"failure_redirect": "https://yoursite.com/failure"
}
```
**Response:** use the `checkout_url` from the JSON (e.g. `https://payments.paytota.com/p/{id}/`) and redirect the customer there. After payment they are sent to your success or failure URL.
For **STK push / server-to-server** execution or more options, see the full [Collection/Purchase](#collectionpurchase) flow below.
# Collection/Purchase
### Step 1 - Initiate
## This API method is utilized to trigger a collection/purchase request, resulting in a JSON response being returned to you.
`POST` `{base url}/api/v1/purchases/`
{% tabs %}
{% tab title="Payload" %}
```json5
{
"client": {
"email": "example@gmail.com",
"phone": "256770123456",
"country": "UG",
// "full_name": "Jane Rose",
// "personal_code": "10231",
// "tax_number": "70002307552",
// "city": "Kampala",
// "street_address": "Ntinda",
// "zip_code": "124538",
// "state": "Nakawa"
},
"purchase": {
"currency": "UGX",
"products": [
{
"name": "Example One",
"price": "500"
}
]
},
"reference": "Your unique transaction reference",
"skip_capture": false,
"brand_id": "{{BrandId}}"
}
```
{% endtab %}
{% tab title="Response" %}
```json5
{
"id": "05b0b12b-1702-4719-8e53-e3a2ee2d5e20",
"due": 1747390681,
"type": "purchase",
"client": {
"cc": [],
"bcc": [],
"city": "Kampala",
"email": "example@gmail.com",
"phone": "256770123456",
"state": "Nakawa",
"country": "UG",
"zip_code": "124538",
"bank_code": "",
"full_name": "Jane Rose",
"brand_name": "",
"legal_name": "",
"tax_number": "70002307552",
"client_type": null,
"bank_account": "",
"personal_code": "10231",
"shipping_city": "",
"shipping_state": "",
"street_address": "Ntinda",
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
],
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"issued": "2025-05-16",
"status": "created",
"is_test": false,
"payment": null,
"product": "purchases",
"user_id": null,
"brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
"order_id": null,
"platform": "api",
"purchase": {
"debt": 0,
"notes": "",
"total": 1000,
"currency": "UGX",
"language": "en",
"products": [
{
"name": "Test Purchase",
"price": 1000,
"category": "",
"discount": 0,
"quantity": "1.0000",
"tax_percent": "0.00",
"total_price_override": null
}
],
"timezone": "UTC",
"due_strict": false,
"email_message": "",
"total_override": null,
"shipping_options": [],
"subtotal_override": null,
"total_tax_override": null,
"has_upsell_products": false,
"payment_method_details": {},
"request_client_details": [],
"total_discount_override": null
},
"client_id": "dfb1fb80-0322-4daa-900f-b0a39cda0452",
"reference": "e44fe395-ddf4-4c0f-8386-c53dd8252985",
"viewed_on": null,
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1747387081,
"event_type": "purchase.created",
"updated_on": 1747387081,
"invoice_url": null,
"can_retrieve": false,
"checkout_url": "https://payments.paytota.com/p/05b0b12b-1702-4719-8e53-e3a2ee2d5e20/",
"send_receipt": false,
"skip_capture": false,
"creator_agent": "",
"referral_code": null,
"can_chargeback": false,
"issuer_details": {
"website": "",
"brand_name": "TOTAL PAYMENTS",
"legal_city": "Kamplaa",
"legal_name": "PAYTOTA",
"tax_number": "",
"bank_accounts": [
{
"bank_code": "EQBLUGKAXXX",
"bank_account": "1036200000000"
}
],
"legal_country": "UG",
"legal_zip_code": "23235",
"registration_number": "80000000000000",
"legal_street_address": "Venture Labs, Plot 23 Binayomba Road, Bugolobi"
},
"marked_as_paid": false,
"status_history": [
{
"status": "created",
"timestamp": 1747387081
}
],
"cancel_redirect": "",
"created_from_ip": "54.86.50.139",
"direct_post_url": null,
"force_recurring": false,
"recurring_token": null,
"failure_redirect": "",
"success_callback": "",
"success_redirect": "",
"transaction_data": {
"flow": "payform",
"extra": {},
"country": "",
"attempts": [],
"payment_method": ""
},
"upsell_campaigns": [],
"refundable_amount": 0,
"is_recurring_token": false,
"billing_template_id": null,
"currency_conversion": null,
"reference_generated": "PT1418",
"refund_availability": "none",
"referral_campaign_id": null,
"retain_level_details": null,
"referral_code_details": null,
"referral_code_generated": null,
"payment_method_whitelist": null
}
```
{% endtab %}
{% tab title="Headers" %}
| Name | Type | Description |
| ----------------------------------------------- | ------ | --------------------------- |
| Authorization\* | String | Bearer **`{{secret key}}`** |
| Content-Type\* | String | application/json |
{% endtab %}
{% tab title="Response Status " %}
201: Created
{% endtab %}
{% endtabs %}
{% hint style="success" %}
The transaction ID in JSON response is then used to execute request(Step 2) to initiate a STK Push prompt on the Subscriber's mobile handset to be debited.
{% endhint %}
### Step 2 - Execute
### You have two methods to execute the transaction
* Redirect the customer to the **{{checkout\_url}}** provided in the response from **step 1** on the Paytota platform.\
\
Take note the following parameters should be added to your Initial JSON body on using this method **`success_redirect`**, **`failure_redirect`**\
After the payment is processed, the system will redirect the customer back to your website.
* Alternatively, you can initiate a STK Push prompt on the subscriber handset by sending a **form-data** request through your backend system. **Following a successful execution, you will receive asynchronous status update via webhook. The notification will have the status 'pending\_execute'.**
## Using the transaction ID received in Step 1, this method is then queried by sending a form-data request to initiate a PIN prompt on the subscriber handset.
`POST` `{base url}/p/{id}/`
{% tabs %}
{% tab title="Payload" %}
| Name | Type | Value |
| ------------------------------------- | ------ | -------------- |
| s2s\* | String | true |
| pm\* | String | paytota\_proxy |
| {% endtab %} | | |
{% tab title="Response" %}
```json5
{
"status": "pending",
"details": {
"return_code": "200",
"message": "Transaction received for processing",
"transaction": {
"status": "pending",
"internal_reference": "97AE66FC9CD7A040EA17AC7911C82EAD"
}
}
}
```
{% endtab %}
{% tab title="Request Headers" %}
#### Headers
| Name | Type | Description |
| ---------------------------------------------- | ------ | ------------------- |
| Content-Type\* | String | multipart/form-data |
#### Request Body
{% endtab %}
{% tab title="Response Status " %}
200: OK
{% endtab %}
{% endtabs %}
{% hint style="success" %}
You will receive a callback on your webhook URL regarding the status of the transaction
```
Successful transaction (status = paid)
Failed transaction (status = error)
```
{% endhint %}
Callback Example
```json5
{
"id": "05b0b12b-1702-4719-8e53-e3a2ee2d5e20",
"due": 1747390681,
"type": "purchase",
"client": {
"cc": [],
"bcc": [],
"city": "Kampala",
"email": "example@gmail.com",
"phone": "256770123456",
"state": "Nakawa",
"country": "UG",
"zip_code": "124538",
"bank_code": "",
"full_name": "Jane Rose",
"brand_name": "",
"legal_name": "",
"tax_number": "70002307552",
"client_type": null,
"bank_account": "",
"personal_code": "10231",
"shipping_city": "",
"shipping_state": "",
"street_address": "Ntinda",
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
],
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"issued": "2025-05-16",
"status": "paid",
"is_test": false,
"payment": {
"amount": 1000,
"paid_on": 1747387124,
"currency": "UGX",
"fee_amount": 0,
"net_amount": 1000,
"description": "",
"is_outgoing": false,
"payment_type": "purchase",
"pending_amount": 0,
"remote_paid_on": 1747387124,
"owned_bank_code": null,
"owned_bank_account": null,
"pending_unfreeze_on": null,
"owned_bank_account_id": null
},
"product": "purchases",
"user_id": null,
"brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
"order_id": null,
"platform": "api",
"purchase": {
"debt": 0,
"notes": "",
"total": 1000,
"currency": "UGX",
"language": "en",
"products": [
{
"name": "Test Purchase",
"price": 1000,
"category": "",
"discount": 0,
"quantity": "1.0000",
"tax_percent": "0.00",
"total_price_override": null
}
],
"timezone": "UTC",
"due_strict": false,
"email_message": "",
"total_override": null,
"shipping_options": [],
"subtotal_override": null,
"total_tax_override": null,
"has_upsell_products": false,
"payment_method_details": {},
"request_client_details": [],
"total_discount_override": null
},
"client_id": "dfb1fb80-0322-4daa-900f-b0a39cda0452",
"reference": "e44fe395-ddf4-4c0f-8386-c53dd8252985",
"viewed_on": 1747387118,
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1747387081,
"event_type": "purchase.paid",
"updated_on": 1747387123,
"invoice_url": null,
"can_retrieve": false,
"checkout_url": "https://gate.paytota.com/p/05b0b12b-1702-4719-8e53-e3a2ee2d5e20/invoice/",
"send_receipt": false,
"skip_capture": false,
"creator_agent": "",
"referral_code": null,
"can_chargeback": false,
"issuer_details": {
"website": "",
"brand_name": "TOTAL PAYMENTS",
"legal_city": "Kamplaa",
"legal_name": "PAYTOTA",
"tax_number": "",
"bank_accounts": [
{
"bank_code": "EQBLUGKAXXX",
"bank_account": "1036200000000"
}
],
"legal_country": "UG",
"legal_zip_code": "23235",
"registration_number": "80000000000000",
"legal_street_address": "Venture Labs, Plot 23 Binayomba Road, Bugolobi"
},
"marked_as_paid": false,
"status_history": [
{
"status": "created",
"timestamp": 1747387081
},
{
"status": "viewed",
"timestamp": 1747387118
},
{
"status": "pending_execute",
"timestamp": 1747387118
},
{
"status": "paid",
"timestamp": 1747387124
}
],
"cancel_redirect": "",
"created_from_ip": "54.86.50.139",
"direct_post_url": null,
"force_recurring": false,
"recurring_token": null,
"failure_redirect": "",
"success_callback": "",
"success_redirect": "",
"transaction_data": {
"flow": "payform",
"extra": {
"payload": {
"bank": {
"bank_code": "",
"bank_name": "",
"account_name": "",
"account_number": ""
},
"client": {
"city": "Kampala",
"email": "example@gmail.com",
"state": "Nakawa",
"country": "UG",
"zip_code": "124538",
"full_name": "",
"tax_number": "",
"personal_code": "",
"street_address": "Ntinda"
},
"message": "Transaction check successful",
"return_code": "200",
"transaction": {
"amount": 1000,
"mobile": "256770123456",
"status": "successful",
"country": "UG",
"currency": "UGX",
"operator": "SANDBOX",
"description": "",
"destination": "mobile",
"transaction_type": "purchase",
"external_reference": "05b0b12b-1702-4719-8e53-e3a2ee2d5e20:102479",
"internal_reference": "97AE66FC9CD7A040EA17AC7911C82EAD",
"operator_reference": "ea8c7ece-768d-43ed-893a-921613121936"
}
}
},
"country": "",
"attempts": [
{
"flow": "payform",
"type": "execute",
"error": null,
"extra": {
"payload": {
"bank": {
"bank_code": "",
"bank_name": "",
"account_name": "",
"account_number": ""
},
"client": {
"city": "Kampala",
"email": "example@gmail.com",
"state": "Nakawa",
"country": "UG",
"zip_code": "124538",
"full_name": "",
"tax_number": "",
"personal_code": "",
"street_address": "Ntinda"
},
"message": "Transaction check successful",
"return_code": "200",
"transaction": {
"amount": 1000,
"mobile": "256770123456",
"status": "successful",
"country": "UG",
"currency": "UGX",
"operator": "SANDBOX",
"description": "",
"destination": "mobile",
"transaction_type": "purchase",
"external_reference": "05b0b12b-1702-4719-8e53-e3a2ee2d5e20:102479",
"internal_reference": "97AE66FC9CD7A040EA17AC7911C82EAD",
"operator_reference": "ea8c7ece-768d-43ed-893a-921613121936"
}
}
},
"country": "",
"client_ip": "",
"fee_amount": 0,
"successful": true,
"payment_method": "paytota_proxy",
"processing_time": 1747387124
}
],
"payment_method": "paytota_proxy"
},
"upsell_campaigns": [],
"refundable_amount": 1000,
"is_recurring_token": false,
"billing_template_id": null,
"currency_conversion": null,
"reference_generated": "PT1418",
"refund_availability": "none",
"referral_campaign_id": null,
"retain_level_details": null,
"referral_code_details": null,
"referral_code_generated": null,
"payment_method_whitelist": null
}
```
### Check Collection/Purchase Status
## This method is used to query the collections/purchases transaction status using the transaction ID. Please note that this API also requires authorization using the Secret Key.
`GET` `{base url}/api/v1/purchases/{id}/`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | --------------------------- |
| Content-Type\* | String | application/json |
| Authorization\* | String | Bearer **`{{secret key}}`** |
{% tabs %}
{% tab title="200: OK " %}
{% endtab %}
{% endtabs %}
# Bank Payout
## Step 1 - Initiate
## This API method is used to initiate a disbursement/payout request for which you will receive a JSON response.
`POST` `{base url}/api/v1/payouts/`
{% tabs %}
{% tab title="Payload" %}
```json5
{
"client": {
"email": "example@gmail.com",
"phone": "256700123123",
"bank_account": "123456789012",
"country": "UG",
// "full_name": "Jane Rose",
// "personal_code": "10231",
// "tax_number": "70002307552",
// "city": "Kampala",
// "street_address": "Ntinda",
// "zip_code": "124538",
// "state": "Nakawa"
},
"payment": {
"currency": "UGX",
"amount": "500",
"description": "Test Payout"
},
"reference": "Your unique transaction reference",
"brand_id": "{{BrandId}}"
}
```
{% endtab %}
{% tab title="Response" %}
```json5
{
"id": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"type": "payout",
"client": {
"cc": [],
"bcc": [],
"city": "",
"email": "example@gmail.com",
"phone": "256700123123",
"state": "",
"country": "UG",
"zip_code": "",
"bank_code": "",
"full_name": "",
"brand_name": "",
"legal_name": "",
"tax_number": "",
"client_type": null,
"bank_account": "123456789013",
"personal_code": "",
"shipping_city": "",
"shipping_state": "",
"street_address": "",
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
],
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"status": "initialized",
"is_test": false,
"payment": {
"amount": 500,
"paid_on": null,
"currency": "UGX",
"fee_amount": 0,
"net_amount": 500,
"description": "Test Payout",
"is_outgoing": true,
"payment_type": "payout",
"pending_amount": 0,
"remote_paid_on": null,
"owned_bank_code": null,
"owned_bank_account": null,
"pending_unfreeze_on": null,
"owned_bank_account_id": null
},
"user_id": null,
"brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
"reference": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1747308302,
"event_type": "payout.created",
"updated_on": 1747308302,
"sender_name": "",
"execution_url": "https://gate.paytota.com/po/7c4ea981-55b1-418a-be23-ea9f5f3e1a91/paytota_proxy/",
"status_history": [
{
"status": "initialized",
"timestamp": 1747308302
}
],
"transaction_data": {
"flow": "payform",
"extra": {},
"country": "",
"attempts": [],
"payment_method": ""
},
"reference_generated": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"recipient_card_brand": null,
"recipient_card_country": "",
"payout_method_whitelist": null
}
```
{% endtab %}
{% tab title="Headers" %}
| Name | Type | Description |
| ----------------------------------------------- | ------ | -------------------- |
| Authorization\* | String | Bearer Token |
| Token\* | String | **`{{secret key}}`** |
| Content-Type\* | String | application/json |
{% endtab %}
{% tab title="Response Status" %}
201: Created
{% endtab %}
{% endtabs %}
## Step 2 - Execute
## Utilize the {{execution\_url}} obtained in step 1 to submit a second request.
`POST` `{{execution_url}}`
{% tabs %}
{% tab title="Payload" %}
```json5
{
"payout_type": "bank",
"bank_name": "Stanbic Bank",
"bank_code": "SBICUGKX",
"bank_account_name": "Jane Rose",
"bank_account_number": "123456789012"
}
```
{% endtab %}
{% tab title="Response" %}
```json5
// If excute is successful
{
"status": "pending",
"details": {
"return_code": "200",
"message": "Transaction received for processing",
"transaction": {
"status": "pending",
"internal_reference": "35F1496D9E17485A800D4847F22BC720"
}
}
}
```
```json5
{
"status": "error",
"error": {
"code": "insufficient_funds",
"message": "Insufficient funds to proceed with operation."
}
}
```
{% endtab %}
{% tab title="Headers" %}
| Name | Type | Description |
| ----------------------------------------------- | ------ | -------------------- |
| Content-Type\* | String | application/json |
| Authorization\* | String | Bearer Token |
| Token\* | String | **`{{secret key}}`** |
| {% endtab %} | | |
{% tab title="Response Status" %}
200: OK
{% endtab %}
{% endtabs %}
{% hint style="info" %}
You will receive a callback on your webhook URL regarding the status of the transaction
```
Successful transaction (status = success)
Failed transaction (status = error)
```
{% endhint %}
Callback Example
```json5
{
"id": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"type": "payout",
"client": {
"cc": [],
"bcc": [],
"city": "",
"email": "example@gmail.com",
"phone": "256700123123",
"state": "",
"country": "UG",
"zip_code": "",
"bank_code": "",
"full_name": "",
"brand_name": "",
"legal_name": "",
"tax_number": "",
"client_type": null,
"bank_account": "123456789013",
"personal_code": "",
"shipping_city": "",
"shipping_state": "",
"street_address": "",
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
],
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"status": "success",
"is_test": false,
"payment": {
"amount": 500,
"paid_on": 1747308344,
"currency": "UGX",
"fee_amount": 0,
"net_amount": 500,
"description": "Test Payout",
"is_outgoing": true,
"payment_type": "payout",
"pending_amount": 0,
"remote_paid_on": 1747308344,
"owned_bank_code": null,
"owned_bank_account": null,
"pending_unfreeze_on": null,
"owned_bank_account_id": null
},
"user_id": null,
"brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
"reference": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1747308302,
"event_type": "payout.success",
"updated_on": 1747308344,
"sender_name": "",
"execution_url": "https://gate.paytota.com/po/7c4ea981-55b1-418a-be23-ea9f5f3e1a91/paytota_proxy/",
"status_history": [
{
"status": "initialized",
"timestamp": 1747308302
},
{
"status": "pending",
"timestamp": 1747308339
},
{
"status": "success",
"timestamp": 1747308344
}
],
"transaction_data": {
"flow": "server_to_server",
"extra": {
"webhook_payload": {
"bank": {
"bank_code": "SBICUGKX",
"bank_name": "Stanbic Bank",
"account_name": "Jane Rose",
"account_number": "123456789012"
},
"client": {
"city": "",
"email": "example@gmail.com",
"state": "",
"zip_code": "",
"full_name": "",
"tax_number": "",
"personal_code": "",
"street_address": ""
},
"message": "Transaction successful",
"return_code": "200",
"transaction": {
"amount": 500,
"mobile": "256700123123",
"status": "successful",
"country": "UG",
"currency": "UGX",
"operator": "SANDBOX",
"description": "",
"destination": "bank",
"transaction_type": "payout",
"external_reference": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"internal_reference": "35F1496D9E17485A800D4847F22BC720",
"operator_reference": "7d795431-a622-42c5-88a3-1354a90621d2"
}
}
},
"country": "",
"attempts": [
{
"flow": "server_to_server",
"error": null,
"extra": {
"webhook_payload": {
"bank": {
"bank_code": "SBICUGKX",
"bank_name": "Stanbic Bank",
"account_name": "Jane Rose",
"account_number": "123456789012"
},
"client": {
"city": "",
"email": "example@gmail.com",
"state": "",
"zip_code": "",
"full_name": "",
"tax_number": "",
"personal_code": "",
"street_address": ""
},
"message": "Transaction successful",
"return_code": "200",
"transaction": {
"amount": 500,
"mobile": "256700123123",
"status": "successful",
"country": "UG",
"currency": "UGX",
"operator": "SANDBOX",
"description": "",
"destination": "bank",
"transaction_type": "payout",
"external_reference": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"internal_reference": "35F1496D9E17485A800D4847F22BC720",
"operator_reference": "7d795431-a622-42c5-88a3-1354a90621d2"
}
}
},
"country": "",
"client_ip": "",
"fee_amount": 0,
"successful": true,
"payment_method": "paytota_proxy",
"processing_time": 1747308344
}
],
"payment_method": "paytota_proxy"
},
"reference_generated": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"recipient_card_brand": "paytota_proxy",
"recipient_card_country": "",
"payout_method_whitelist": null
}
```
## Check Disbursement/Payout Status
## This API method is used to query the payouts/disbursement transaction status using the transaction ID.
`GET` `{base url}/api/v1/payouts/{id}/`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | -------------------- |
| Content-Type\* | String | application/json |
| Authorization\* | String | Bearer Token |
| Token\* | String | **`{{secret key}}`** |
{% tabs %}
{% tab title="200: OK " %}
{% endtab %}
{% endtabs %}
# Disbursement/Payout
### Step 1 - Initiate
## This API method is used to initiate an a disbursement/payout request for which you will receive a JSON response.
`POST` `{base url}/api/v1/payouts/`
{% tabs %}
{% tab title="Payload" %}
{% endtab %}
{% tab title="Response" %}
```json5
{
"id": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"type": "payout",
"client": {
"cc": [],
"bcc": [],
"city": "",
"email": "example@gmail.com",
"phone": "256700123123",
"state": "",
"country": "UG",
"zip_code": "",
"bank_code": "",
"full_name": "",
"brand_name": "",
"legal_name": "",
"tax_number": "",
"client_type": null,
"bank_account": "123456789013",
"personal_code": "",
"shipping_city": "",
"shipping_state": "",
"street_address": "",
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
],
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"status": "initialized",
"is_test": false,
"payment": {
"amount": 500,
"paid_on": null,
"currency": "UGX",
"fee_amount": 0,
"net_amount": 500,
"description": "Test Payout",
"is_outgoing": true,
"payment_type": "payout",
"pending_amount": 0,
"remote_paid_on": null,
"owned_bank_code": null,
"owned_bank_account": null,
"pending_unfreeze_on": null,
"owned_bank_account_id": null
},
"user_id": null,
"brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
"reference": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1747308302,
"event_type": "payout.created",
"updated_on": 1747308302,
"sender_name": "",
"execution_url": "https://gate.paytota.com/po/7c4ea981-55b1-418a-be23-ea9f5f3e1a91/paytota_proxy/",
"status_history": [
{
"status": "initialized",
"timestamp": 1747308302
}
],
"transaction_data": {
"flow": "payform",
"extra": {},
"country": "",
"attempts": [],
"payment_method": ""
},
"reference_generated": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"recipient_card_brand": null,
"recipient_card_country": "",
"payout_method_whitelist": null
}
```
{% endtab %}
{% tab title="Headers" %}
| Name | Type | Description |
| ----------------------------------------------- | ------ | --------------------------- |
| Authorization\* | | Bearer **`{{secret key}}`** |
| Content-Type\* | String | application/json |
| {% endtab %} | | |
{% tab title="Respose Status" %}
201: Created
{% endtab %}
{% endtabs %}
{% hint style="success" %}
The transaction ID in JSON response is then used to execute request(Step 2).
{% endhint %}
### Step 2 - Execute
## Utilize the {{execution\_url}} obtained in step 1 to submit a second request.
`POST` `{{execution_url}}`
{% tabs %}
{% tab title="Payload" %}
```json5
{
"payout_type": "mobile"
}
```
{% endtab %}
{% tab title="Response" %}
```json5
// If excute is successful
{
"status": "pending",
"details": {
"return_code": "200",
"message": "Transaction received for processing",
"transaction": {
"status": "pending",
"internal_reference": "35F1496D9E17485A800D4847F22BC720"
}
}
}
```
```json5
// If you have insufficient balance
{
"status": "error",
"error": {
"code": "insufficient_funds",
"message": "Insufficient funds to proceed with operation."
}
}
```
{% endtab %}
{% tab title="Headers" %}
| Name | Type | Description |
| ---------------------------------------------- | ------ | ---------------- |
| Content-Type\* | String | application/json |
{% endtab %}
{% tab title="Response Status" %}
200: OK
{% endtab %}
{% endtabs %}
{% hint style="info" %}
You will receive a callback on your webhook URL regarding the status of the transaction
```
Successful transaction (status = success)
Failed transaction (status = error)
```
{% endhint %}
Callback Example
```json5
{
"id": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"type": "payout",
"client": {
"cc": [],
"bcc": [],
"city": "",
"email": "example@gmail.com",
"phone": "256700123123",
"state": "",
"country": "UG",
"zip_code": "",
"bank_code": "",
"full_name": "",
"brand_name": "",
"legal_name": "",
"tax_number": "",
"client_type": null,
"bank_account": "123456789013",
"personal_code": "",
"shipping_city": "",
"shipping_state": "",
"street_address": "",
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
],
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"status": "success",
"is_test": false,
"payment": {
"amount": 500,
"paid_on": 1747308344,
"currency": "UGX",
"fee_amount": 0,
"net_amount": 500,
"description": "Test Payout",
"is_outgoing": true,
"payment_type": "payout",
"pending_amount": 0,
"remote_paid_on": 1747308344,
"owned_bank_code": null,
"owned_bank_account": null,
"pending_unfreeze_on": null,
"owned_bank_account_id": null
},
"user_id": null,
"brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
"reference": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1747308302,
"event_type": "payout.success",
"updated_on": 1747308344,
"sender_name": "",
"execution_url": "https://gate.paytota.com/po/7c4ea981-55b1-418a-be23-ea9f5f3e1a91/paytota_proxy/",
"status_history": [
{
"status": "initialized",
"timestamp": 1747308302
},
{
"status": "pending",
"timestamp": 1747308339
},
{
"status": "success",
"timestamp": 1747308344
}
],
"transaction_data": {
"flow": "server_to_server",
"extra": {
"webhook_payload": {
"bank": {
"bank_code": "SBICUGKX",
"bank_name": "Stanbic Bank",
"account_name": "Jane Rose",
"account_number": "123456789012"
},
"client": {
"city": "",
"email": "example@gmail.com",
"state": "",
"zip_code": "",
"full_name": "",
"tax_number": "",
"personal_code": "",
"street_address": ""
},
"message": "Transaction successful",
"return_code": "200",
"transaction": {
"amount": 500,
"mobile": "256700123123",
"status": "successful",
"country": "UG",
"currency": "UGX",
"operator": "SANDBOX",
"description": "",
"destination": "bank",
"transaction_type": "payout",
"external_reference": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"internal_reference": "35F1496D9E17485A800D4847F22BC720",
"operator_reference": "7d795431-a622-42c5-88a3-1354a90621d2"
}
}
},
"country": "",
"attempts": [
{
"flow": "server_to_server",
"error": null,
"extra": {
"webhook_payload": {
"bank": {
"bank_code": "SBICUGKX",
"bank_name": "Stanbic Bank",
"account_name": "Jane Rose",
"account_number": "123456789012"
},
"client": {
"city": "",
"email": "example@gmail.com",
"state": "",
"zip_code": "",
"full_name": "",
"tax_number": "",
"personal_code": "",
"street_address": ""
},
"message": "Transaction successful",
"return_code": "200",
"transaction": {
"amount": 500,
"mobile": "256700123123",
"status": "successful",
"country": "UG",
"currency": "UGX",
"operator": "SANDBOX",
"description": "",
"destination": "bank",
"transaction_type": "payout",
"external_reference": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"internal_reference": "35F1496D9E17485A800D4847F22BC720",
"operator_reference": "7d795431-a622-42c5-88a3-1354a90621d2"
}
}
},
"country": "",
"client_ip": "",
"fee_amount": 0,
"successful": true,
"payment_method": "paytota_proxy",
"processing_time": 1747308344
}
],
"payment_method": "paytota_proxy"
},
"reference_generated": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"recipient_card_brand": "paytota_proxy",
"recipient_card_country": "",
"payout_method_whitelist": null
}
```
### Check Disbursement/Payout Status
## This API method is used to query the payouts/disbursement transaction status using the transaction ID.
`GET` `{base url}/api/v1/payouts/{id}/`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | --------------------------- |
| Content-Type\* | String | application/json |
| Authorization\* | String | Bearer **`{{secret key}}`** |
{% tabs %}
{% tab title="Respose Status" %}
200: OK
{% endtab %}
{% endtabs %}
# Company Statements
## Schedule a statement generation
`POST` `{base url}/api/v1/company_statements/`
This request allows you to schedule statement generation for a company. The response will include an object with fields such as `id`, `status`, and `download_url`. These are the key fields to focus on.
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | -------------------- |
| Content-Type\* | String | application/json |
| Authorization\* | String | Bearer |
| Token\* | String | **`{{secret key}}`** |
{% tabs %}
{% tab title="201: Created " %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Payload" %}
```json
{
"format": "csv",
"timezone": "UTC"
}
```
{% endtab %}
{% tab title="Response" %}
{% code overflow="wrap" fullWidth="false" %}
```json
{
"format": "csv",
"timezone": "UTC",
"is_test": false,
"company_uid": "706d0675-b131-468c-940d-bc0ea3599e7f",
"query_string": "",
"status": "pending",
"download_url": null,
"began_on": null,
"finished_on": null,
"created_on": 1698322275,
"updated_on": 1698322275,
"type": "statement_request",
"id": "1dd24660-527d-422a-9bfa-937c5b752eb0"
}
```
{% endcode %}
{% endtab %}
{% tab title="Optional Parameters" %}
| Name | Description |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **from** integer(query) | Filter result set to only include values older or equal to the provided Unix timestamp |
| **to** integer(query) | Filter result set to only include values younger than the provided Unix timestamp |
| **paid\_from** integer(query) | Filter paid result set to only include values older or equal to the provided Unix timestamp |
| **paid\_to** integer(query) | Filter paid result set to only include values younger than the provided Unix timestamp |
| **updated\_from** integer(query) | Filter result set to only include values older or equal to the provided last modification time Unix timestamp |
| **updated\_to** integer(query) | Filter result set to only include values younger than the provided last modification time Unix timestamp |
| **brand\_id** string($uuid)(query) | Filter result set to only include the specified brand UUID(s) |
| **shop\_id** string($uuid)(query) | Filter result set to only include the specified shop UUID(s) |
| **q** string($string)(query) | Filter result set to only include results including a specified text (search over a ton of text fields) |
| **products** string($string)(query) | Filter result set to only include results including a specified text in products |
| **total** string($float)(query) | Filter result set to only include results with a total between min and max value. Must include 2 values, if any - (min, max). |
| **currency** string(query) | Filter result set to only include specified currency(ies) |
| **payment\_method** string(query) |
Filter result set to only include specified payment methods(s).
Available values : maestro, mastercard, unknown, visa
|
| | |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **three\_d\_secure** string($bool)(query) | Filter result set to only include results with a 3-D verification. |
| **country** string($ISO 3166-1 alpha-2)(query) | Filter result set to only include specified client country(ies) in ISO 3166-1 alpha-2 format |
| **status** string($string)(query) | Filter result set to only include results with a specific status. |
| **product** string(query) |
Filter result set to only include specified products(s).
