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/

Payload

{
    "client": {
        "email": "[email protected]",
        "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}}"
}

Response

Headers

Response Status

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.

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}/

Payload

Name	Type	Value
s2s*	String	true
pm*	String	paytota_proxy

Response

Request Headers

Response Status

You will receive a callback on your webhook URL regarding the status of the transaction

Successful transaction  (status = paid)
Failed transaction (status = error)

Callback Example

{
  "id": "05b0b12b-1702-4719-8e53-e3a2ee2d5e20",
  "due": 1747390681,
  "type": "purchase",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "Kampala",
    "email": "[email protected]",
    "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": "[email protected]",
          "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": "[email protected]",
              "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}}

200: OK