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`

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.

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.

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

  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