Overview

The base URLs for each environment are as follows:

Environment	Base Url
Sandbox (UAT)	https://api.staging.pipevest.com/v1
Production	https://api.pipevest.com/v1

Note

Use Sandbox (UAT) to build and test against non-production data, and Production once your account is live. Both run on Pipevest’s Cloudflare-fronted infrastructure; your Pipevest contact confirms access during onboarding.

USSD Base Url

After authenticating and receiving an access token, USSD requests are made under the /ussd path:

Environment	Base Url
UAT	https://api.staging.pipevest.com/v1/ussd
Production	https://api.pipevest.com/v1/ussd

The USSD API exposes exactly two endpoints: POST /v1/ussd/session (create a session) and POST /v1/ussd/process (advance the menu state machine). Both take a JSON body.

Screen size and paging

A USSD screen is bounded to 160 bytes and the GSM 03.38 alphabet, because that is what a handset session carries. Pipevest renders every screen inside that budget and paginates anything longer, so ussdText is always deliverable as returned.

Caution

Send ussdText to the handset as-is. Do not re-wrap, re-paginate, truncate or re-encode it. A single character outside GSM 03.38 forces the whole message into UCS-2, which halves a 160-byte screen to 80 characters — one emoji does not cost its own bytes, it costs half the screen.

Where a screen has to be split, continuation pages end with #=More; the customer sends # to advance. Nothing is dropped in a split.

List screens page rather than truncate. Every list states the range it is showing — My Assets 1-3 of 5 — and offers navigation keys where a page exists in that direction:

Key	Moves
6	Previous page
7	Next page
0	Out of the list

Page sizes differ per screen because the rows differ: 3 holdings, 4 pending requests, 2 transactions, 5 stocks in the browser. Read the keys off the options array rather than assuming a fixed set — 6 and 7 appear only when the page they point at exists.

Times on USSD screens render in Central Africa Time (Africa/Lusaka), the customer’s own wall clock, not UTC.

Using Authenticated Endpoints

All USSD endpoints are authenticated using OAuth 2.0 client credentials. A clientId and clientSecret are exchanged for a short-lived access token, which then authenticates further requests.

Caution

The curl examples on this page and in the USSD guides show only the authentication headers. Both USSD endpoints are POSTs to a partner surface, so each request must also carry:

• Signature and Signature-Input, plus a Content-Digest over the body — see Message Signature. An unsigned request is rejected with 401.
• an X-Idempotency-Key. Without one the request is rejected with 400 "X-Idempotency-Key header is required for this request".

Both are enforced in Sandbox (UAT) and Production alike — the sandbox is not the more permissive of the two. Only the token exchange, POST /v1/oauth/token, is unsigned.

Access Token Request

  curl --request POST \
    --url https://api.staging.pipevest.com/v1/oauth/token \
    --header 'Content-Type: application/json' \
    --data '{"clientId": "<client-id>", "clientSecret": "<client-secret>"}'

Create a USSD session

Tip

The access token is passed into the authorization header as a bearer token, alongside your x-client-id.

  curl --request POST \
    --url https://api.staging.pipevest.com/v1/ussd/session \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --data '{"customerId": "<customer-id>"}'

Advance the session with a choice

  curl --request POST \
    --url https://api.staging.pipevest.com/v1/ussd/process \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --data '{"sessionId": "<session-id>", "choice": "1"}'

Authentication Concepts

Check out the auth mechanisms used to keep the API secure

Authentication Guide

Understand how to create and revoke auth tokens