Visa and Mastercard

POST /api/card/collect

Start a hosted Visa or Mastercard checkout.

Authentication

HTTP Basic, as described in Authentication. No extra scope is checked.

Headers

Header	Required	Description
Authorization	Yes	Basic base64(api_user_id:api_key).
Content-Type	Yes	application/json
Accept	No	application/json

Body

Field	Required	Rules	Description
externalReference string	Yes	required|unique|max:255	Your order reference.
amount number	Yes	required|numeric|min:500	Amount in UGX.
currency string	Yes	required|in:UGX	Must be UGX.
reason string	Yes	required|min:2|max:150	Shown as the payment description.
name string	Yes	required|min:2|max:100	Cardholder name.
email string	Yes	required|email|max:255	Cardholder email.
success_callback string	No	nullable|url|max:255	Server notification after success.
failure_callback string	No	nullable|url|max:255	Server notification after failure.
redirect_url string	No	nullable|url|max:255	Browser return URL after a successful checkout.

Behavior

• Redirect the cardholder to data.checkoutUrl. Do not embed card numbers in your own page.
• The wallet is credited only after PegPay confirms the payment.
• The fee is the organization card-collection policy. The published schedule is 5 percent. Some organizations have a different rate.
• API validation allows UGX 500 and above. The hosted checkout and card policy band used for new merchants is UGX 500 to 7,000,000.
• redirect_url is the browser return after a successful card payment. success_callback and failure_callback are server POSTs.

Idempotency. externalReference must be unique. A failed initiation rolls back the API request so the reference can be reused.

Rate limit. No rate limit is configured on the API.

Example request

{
    "externalReference": "card-1001",
    "amount": 10000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "redirect_url": "https://example.com/orders/1001"
}

Success · HTTP 200

{
    "response": "OK",
    "data": {
        "transactionStatus": "PENDING",
        "ssentezoWalletReference": "generated-uuid",
        "externalReference": "card-1001",
        "checkoutUrl": "https://wallet.ssentezo.com/pegpay/card/checkout/generated-uuid"
    }
}

Errors

Status	When
401 NO_AUTHORIZATION_HEADER	The Authorization header is missing.
403 INVALID_AUTHORIZATION_HEADER	The header must start with "Basic ".
403 MISSING_USER_OR_KEY	The decoded value must be api_user_id:api_key.
403 INVALID_USER_OR_KEY	The API user or key was not recognized.
403 ORGANIZATION_SUSPENDED	The organization user is suspended.
422	Validation failed. error.errors contains the field messages.
400	Card checkout could not be created.
500	Unexpected card-collection error.

Code

curl

curl --request POST \
  --url "$SSENTEZO_BASE_URL/api/card/collect" \
  --header "Authorization: Basic $SSENTEZO_BASIC_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "externalReference": "card-1001",
    "amount": 10000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "redirect_url": "https://example.com/orders/1001"
}'

php

$client = new Ssentezo\Wallet\SsentezoClient(
    getenv('SSENTEZO_API_USER'),
    getenv('SSENTEZO_API_KEY'),
    getenv('SSENTEZO_BASE_URL')
);

$result = $client->request('POST', '/api/card/collect', json_decode(<<<'JSON'
{
    "externalReference": "card-1001",
    "amount": 10000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "redirect_url": "https://example.com/orders/1001"
}
JSON, true));

javascript

const token = Buffer.from(process.env.SSENTEZO_API_USER + ':' + process.env.SSENTEZO_API_KEY).toString('base64');
const response = await fetch(process.env.SSENTEZO_BASE_URL + '/api/card/collect', {
  method: 'POST',
  headers: {
    Authorization: 'Basic ' + token,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "externalReference": "card-1001",
    "amount": 10000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "redirect_url": "https://example.com/orders/1001"
}),
});
const payload = await response.json();

python

import base64, json, os, urllib.request

token = base64.b64encode(f"{os.environ['SSENTEZO_API_USER']}:{os.environ['SSENTEZO_API_KEY']}".encode()).decode()
request = urllib.request.Request(
    os.environ['SSENTEZO_BASE_URL'] + '/api/card/collect',
    data=json.dumps({
    "externalReference": "card-1001",
    "amount": 10000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "redirect_url": "https://example.com/orders/1001"
}).encode(),
    headers={'Authorization': f'Basic {token}', 'Accept': 'application/json', 'Content-Type': 'application/json'},
    method='POST',
)
with urllib.request.urlopen(request, timeout=20) as response:
    payload = json.load(response)

java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(System.getenv("SSENTEZO_BASE_URL") + "/api/card/collect"))
    .timeout(Duration.ofSeconds(20))
    .header("Authorization", "Basic " + Base64.getEncoder().encodeToString((System.getenv("SSENTEZO_API_USER") + ":" + System.getenv("SSENTEZO_API_KEY")).getBytes(StandardCharsets.UTF_8)))
    .header("Accept", "application/json")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"externalReference\":\"card-1001\",\"amount\":10000,\"currency\":\"UGX\",\"reason\":\"Order 1001\",\"name\":\"Ada Lovelace\",\"email\":\"ada@example.com\",\"redirect_url\":\"https://example.com/orders/1001\"}"))
    .build();

Set SSENTEZO_API_USER, SSENTEZO_API_KEY, and SSENTEZO_BASE_URL. SSENTEZO_BASIC_TOKEN is the base64 of user:key.