Collection — Tricsoft Pay Documentation

Overview

A collection begins when your application creates a payment request and ends when the final transaction status is confirmed.

Mobile Money collections

Use POST {{base_url}}/payments/collect to initiate a Mobile Money collection with mtn_ug or airtel_ug.

The request body is the same for Personal and Business accounts. Only the Authorization header changes according to the client configured during Environment Setup.

Request fields

Field	Type	Description
provider_code	string	The Mobile Money provider. Use mtn_ug or airtel_ug.
amount	integer	The collection amount in whole UGX. For example, 50000 represents UGX 50,000.
customer_phone	string	The customer's phone number using digits only. It must start with country code 256.
external_id	string	A unique ID generated for this request. Webhooks return it so your application can identify the related collection.

Personal account collection

Use the Bearer-authenticated paymentGateway configured with the Personal account access token.

const t = await paymentGateway.post("{{base_url}}/payments/collect", {
  provider_code: "mtn_ug",
  amount: 50000,
  customer_phone: "256700000000",
  external_id: "txn_20260717_001",
});

if (t.status !== 201) throw new Error("Collection request failed");

payload, _ := json.Marshal(map[string]any{
    "provider_code": "mtn_ug",
    "amount": 50000,
    "customer_phone": "256700000000",
    "external_id": "txn_20260717_001",
})
req, _ := http.NewRequest(http.MethodPost, "{{base_url}}/payments/collect", bytes.NewReader(payload))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err == nil && resp.StatusCode != http.StatusCreated {
    return fmt.Errorf("unexpected status: %d", resp.StatusCode)
}

let response = reqwest::Client::new()
    .post("{{base_url}}/payments/collect")
    .bearer_auth(&access_token)
    .json(&serde_json::json!({
        "provider_code": "mtn_ug",
        "amount": 50000,
        "customer_phone": "256700000000",
        "external_id": "txn_20260717_001"
    }))
    .send()
    .await?;

assert_eq!(response.status(), reqwest::StatusCode::CREATED);

String body = """
    {
      "provider_code":"mtn_ug",
      "amount":50000,
      "customer_phone":"256700000000",
      "external_id":"txn_20260717_001"
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("{{base_url}}/payments/collect"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = paymentGateway.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 201) throw new RuntimeException("Collection request failed");

using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;

paymentGateway.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);
var response = await paymentGateway.PostAsJsonAsync("{{base_url}}/payments/collect", new
{
    provider_code = "mtn_ug",
    amount = 50000,
    customer_phone = "256700000000",
    external_id = "txn_20260717_001",
});
if (response.StatusCode != HttpStatusCode.Created)
    throw new HttpRequestException("Collection request failed");

Business account collection

Use the API-key-authenticated paymentGateway configured with the Business account API key ID and secret.

const t = await paymentGateway.post("{{base_url}}/payments/collect", {
  provider_code: "airtel_ug",
  amount: 50000,
  customer_phone: "256700000000",
  external_id: "txn_20260717_002",
});

if (t.status !== 201) throw new Error("Collection request failed");

payload, _ := json.Marshal(map[string]any{
    "provider_code": "airtel_ug",
    "amount": 50000,
    "customer_phone": "256700000000",
    "external_id": "txn_20260717_002",
})
req, _ := http.NewRequest(http.MethodPost, "{{base_url}}/payments/collect", bytes.NewReader(payload))
req.Header.Set("Authorization", "ApiKey "+apiKeyID+":"+apiSecret)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err == nil && resp.StatusCode != http.StatusCreated {
    return fmt.Errorf("unexpected status: %d", resp.StatusCode)
}

let response = reqwest::Client::new()
    .post("{{base_url}}/payments/collect")
    .header("Authorization", format!("ApiKey {}:{}", api_key_id, api_secret))
    .json(&serde_json::json!({
        "provider_code": "airtel_ug",
        "amount": 50000,
        "customer_phone": "256700000000",
        "external_id": "txn_20260717_002"
    }))
    .send()
    .await?;

assert_eq!(response.status(), reqwest::StatusCode::CREATED);

String body = """
    {
      "provider_code":"airtel_ug",
      "amount":50000,
      "customer_phone":"256700000000",
      "external_id":"txn_20260717_002"
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("{{base_url}}/payments/collect"))
    .header("Authorization", "ApiKey " + apiKeyId + ":" + apiSecret)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = paymentGateway.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 201) throw new RuntimeException("Collection request failed");

using System.Net;
using System.Net.Http.Json;

paymentGateway.DefaultRequestHeaders.TryAddWithoutValidation(
    "Authorization",
    $"ApiKey {apiKeyId}:{apiSecret}"
);
var response = await paymentGateway.PostAsJsonAsync("{{base_url}}/payments/collect", new
{
    provider_code = "airtel_ug",
    amount = 50000,
    customer_phone = "256700000000",
    external_id = "txn_20260717_002",
});
if (response.StatusCode != HttpStatusCode.Created)
    throw new HttpRequestException("Collection request failed");

Successful Mobile Money request

A successful collection request returns HTTP 201 Created. The response includes payment_id; store it so you can retrieve the payment and check its latest status.

Card collections

Use POST {{base_url}}/payments/collect with provider_code set to tricsoftpay_card_ug to initiate a card collection.

Card collections use the same Personal or Business account authentication configured on the Environment Setup page.

The request returns an action URL that the customer must open to continue the card payment.

Important: multiply every card amount by 100

Before sending a card collection, multiply the customer-facing amount by 100 and send the resulting integer. For example, USD 4.99 is sent as 499.

Apply this temporary scaling rule to every currency, including UGX. For example, UGX 5,000 is sent as 500000.

This differs from Mobile Money collections, where the amount is documented directly as a whole UGX value.

Card collection request fields

Field	Type	Required	Description
provider_code	string	Yes	Use tricsoftpay_card_ug.
amount	integer	Yes	The customer-facing amount multiplied by 100. For example, USD 4.99 is sent as 499 and UGX 5,000 is sent as 500000.
customer_email	string	Yes	The customer's valid email address.
customer_phone	string	Yes	The customer's phone number in international format, including the country code.
customer_first_name	string	Yes	The customer's first name.
customer_second_name	string	Yes	The customer's surname or last name.
customer_city	string	Yes	The customer's city.
customer_country	string	Yes	The customer's country name.
customer_state	string	Yes	The customer's state or region.
currency	string	Yes	An uppercase three-letter ISO 4217 currency code, such as UGX, USD, or KES.
external_id	string	Yes	A unique reference generated by your application for this collection.
description	string	No	An optional description of the payment.

Create a card collection

Use the paymentGateway configured for the account type and environment that will process the payment.

const response = await paymentGateway.post(
  "{{base_url}}/payments/collect",
  {
    provider_code: "tricsoftpay_card_ug",
    amount: 499,
    customer_email: "customer@example.com",
    customer_phone: "256700000000",
    customer_first_name: "Jane",
    customer_second_name: "Doe",
    customer_city: "Kampala",
    customer_country: "Uganda",
    customer_state: "Central Region",
    currency: "USD",
    external_id: "card_20260730_001",
    description: "Order INV-1001",
  },
);

if (response.status < 200 || response.status >= 300) {
  throw new Error("Card collection request failed");
}

payload, _ := json.Marshal(map[string]any{
    "provider_code": "tricsoftpay_card_ug",
    "amount": 499,
    "customer_email": "customer@example.com",
    "customer_phone": "256700000000",
    "customer_first_name": "Jane",
    "customer_second_name": "Doe",
    "customer_city": "Kampala",
    "customer_country": "Uganda",
    "customer_state": "Central Region",
    "currency": "USD",
    "external_id": "card_20260730_001",
    "description": "Order INV-1001",
})

req, _ := http.NewRequest(
    http.MethodPost,
    "{{base_url}}/payments/collect",
    bytes.NewReader(payload),
)
req.Header.Set("Content-Type", "application/json")
resp, err := paymentGateway.Do(req)
if err != nil {
    return err
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
    return fmt.Errorf("card collection failed: %s", resp.Status)
}

let response = payment_gateway
    .post("{{base_url}}/payments/collect")
    .json(&serde_json::json!({
        "provider_code": "tricsoftpay_card_ug",
        "amount": 499,
        "customer_email": "customer@example.com",
        "customer_phone": "256700000000",
        "customer_first_name": "Jane",
        "customer_second_name": "Doe",
        "customer_city": "Kampala",
        "customer_country": "Uganda",
        "customer_state": "Central Region",
        "currency": "USD",
        "external_id": "card_20260730_001",
        "description": "Order INV-1001"
    }))
    .send()
    .await?
    .error_for_status()?;

String body = """
    {
      "provider_code": "tricsoftpay_card_ug",
      "amount": 499,
      "customer_email": "customer@example.com",
      "customer_phone": "256700000000",
      "customer_first_name": "Jane",
      "customer_second_name": "Doe",
      "customer_city": "Kampala",
      "customer_country": "Uganda",
      "customer_state": "Central Region",
      "currency": "USD",
      "external_id": "card_20260730_001",
      "description": "Order INV-1001"
    }
    """;

HttpRequest request = requestBuilder("{{base_url}}/payments/collect")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = paymentGateway.send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
if (response.statusCode() < 200 || response.statusCode() >= 300) {
    throw new RuntimeException("Card collection request failed");
}

using System.Net.Http.Json;

var response = await paymentGateway.PostAsJsonAsync(
    "{{base_url}}/payments/collect",
    new
    {
        provider_code = "tricsoftpay_card_ug",
        amount = 499,
        customer_email = "customer@example.com",
        customer_phone = "256700000000",
        customer_first_name = "Jane",
        customer_second_name = "Doe",
        customer_city = "Kampala",
        customer_country = "Uganda",
        customer_state = "Central Region",
        currency = "USD",
        external_id = "card_20260730_001",
        description = "Order INV-1001",
    }
);
response.EnsureSuccessStatusCode();

Open the action URL

After a successful request, read the action URL from the response and present it to the customer.

The developer may embed the URL in an iframe, redirect the current browser window, open it in a new window or tab, or use another suitable presentation.

No presentation method is preferred by this guide; choose the option that fits the application's user experience and security requirements.

Confirm the card payment

Opening or completing the action URL is not final proof that the collection succeeded.

Use the Webhook integration to receive asynchronous updates, and use Transactions when the application needs to retrieve the latest payment status.

Only fulfil the order after a successful final payment status has been confirmed.

Card collection response

The exact card collection response fields and example payload will be added when the response contract is confirmed.

The response will include the action URL needed to continue the customer payment flow.