Partner API Integration Basics

A reliable integration begins with the public API contract, one controlled credential, and a small verified request flow. Build against MangoOTP's documented fields and status codes rather than copying assumptions from another service.

Create the active API key

A user can have at most one active API key. The raw value is shown only at creation, so store it in a protected secret system and do not expect the list page to reveal it later.

For Partner API Integration Basics, treat “Create the active API key” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Configure the mandatory IP whitelist

Every key requires a non-empty IPv4 or CIDR whitelist. Requests must originate from an allowed address resolved by the platform.

For Partner API Integration Basics, treat “Configure the mandatory IP whitelist” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Authenticate with X-API-Key

Partner endpoints accept X-API-Key, not a USER JWT. Send the credential over HTTPS and never place it in a query string, browser page, source repository, or log.

For Partner API Integration Basics, treat “Authenticate with X-API-Key” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Discover catalog before ordering

Use the documented activation or rental catalog and price calls. Price responses expose a platform price and stock estimate, not a reservation.

For Partner API Integration Basics, treat “Discover catalog before ordering” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Use partnerOrderNo for idempotency

Generate a stable partnerOrderNo for each business attempt. Retrying the same number with the same parameters returns the same logical result; changed parameters are rejected.

For Partner API Integration Basics, treat “Use partnerOrderNo for idempotency” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Apply maxPrice correctly

Activation createOrder requires maxPrice and is rejected before funds are frozen if the current platform price is higher. Rental V1 does not accept maxPrice.

For Partner API Integration Basics, treat “Apply maxPrice correctly” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Query the existing order

After an ambiguous timeout, query by the same order reference instead of creating a new partnerOrderNo. Keep pagination bounded and validate known statuses.

For Partner API Integration Basics, treat “Query the existing order” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Handle code and traceId

Use the stable error code for program logic and retain traceId for support. Human messages can change with locale and must not drive automation.

For Partner API Integration Basics, treat “Handle code and traceId” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Practical checklist

1. Verify create the active api key, record the result, and continue only when the next action is clear.
2. Verify configure the mandatory ip whitelist, record the result, and continue only when the next action is clear.
3. Verify authenticate with x-api-key, record the result, and continue only when the next action is clear.
4. Verify discover catalog before ordering, record the result, and continue only when the next action is clear.
5. Verify use partnerorderno for idempotency, record the result, and continue only when the next action is clear.
6. Verify apply maxprice correctly, record the result, and continue only when the next action is clear.
7. Verify query the existing order, record the result, and continue only when the next action is clear.
8. Verify handle code and traceid, record the result, and continue only when the next action is clear.

Use the final platform status and account history as the source of truth. Do not share passwords, full verification codes, authentication secrets, access tokens, or API keys in screenshots or support messages. More guidance is available in the MangoOTP Help Center.