Overview

Pipevest USSD API 1.0.0

The Pipevest USSD API. Exactly two endpoints drive the USSD menu state machine: POST /session creates a session and returns the HOME menu, and POST /process advances the session with the customer’s menu choice.

Both take a JSON body and are authenticated with an OAuth bearer token plus the x-client-id header. Customer identifiers are CUID strings; session identifiers are ussd_-prefixed hex strings.

Both endpoints are mutating partner requests, so in addition to the bearer token each one must carry an X-Idempotency-Key and an RFC 9421 Signature / Signature-Input pair plus a Content-Digest over the body. Missing or invalid signature material is a 401; a missing idempotency key is a 400. This is enforced identically in Sandbox (UAT) and Production.

Any authenticated call may additionally return 403 (client IP outside the credential’s allowlist), 429 (rate limit) or 500. See the error reference in the guides for the full taxonomy.

Information

• OpenAPI version: 3.0.3

Operations

POST

/session

POST

/process

Authentication

BearerAuth

Short-lived access token from POST /v1/oauth/token.

Security scheme type: http

Bearer format: JWT

ClientId

Your organization clientId. Must match the clientId in the bearer token.

Security scheme type: apiKey

Header parameter name: x-client-id