Pay with Nyuza.One checkout integration.

Overview

Add Pay with Nyuza to your application with express checkout: authenticate, create a checkout, redirect the customer, and confirm payment. Nyuza creates the order, invoice and payment in a single request.

Before you begin

Start in Nyuza Console under Organization profile → API Clients. Create a client to generate your client ID and secret, then use those credentials to obtain a token. Have your organization identifier, institution, channel and payment-provider configuration ready, along with an HTTPS callback endpoint and a customer return page.

Where your code runs

Browser → your backend → Nyuza API. Your backend returns paymentUrl to the browser. Nyuza sends callbacks directly to your backend, even if the customer closes the browser.

Prepare your integration values

Choose your integration

Environment and examples

Express checkout nonproduction origin:

https://dev.nonprod.rolengiapps.com

Endpoint paths are shown independently of the origin. Use the authentication and payment API environment URLs supplied during onboarding.

Use the environment URLs supplied during onboarding. Values in {{doubleBraces}} are placeholders; replace them with your configuration or transaction data. Example identifiers, amounts and enum values are illustrative.

Your first test payment

Follow one purchase, ORDER-DEMO-001, from setup to confirmation. Complete this in your test environment before accepting customer payments.

Walkthrough defaults

The examples below use provisional defaults to make the walkthrough concrete. Verify the URLs, units, required fields and response mappings against your environment before using them in production.

Keep a purchase record

{
  "purchaseReference": "ORDER-DEMO-001",
  "invoiceId": "{{invoiceId}}",
  "paymentId": "{{paymentId}}",
  "paymentUrl": "{{paymentUrl}}"
}

This is an example record for your application, not an API response. Store the purchase’s expected amount and currency alongside it so you can verify the payment outcome.

Authentication

Create your API credentials

Sign in to Nyuza Console and open Organization profile → API Clients. Your organization can create as many API clients as needed, each with its own client ID and secret.

Use separate API clients when you need independent credentials for different applications or integrations. The API Clients list provides Copy for the client ID, Copy Secret, and Delete actions.

Obtain an authentication token

Nyuza uses OAuth 2.0 with Keycloak. Client applications obtain an opaque token through the Nyuza authentication service.

Request

Content-Type: application/json

{
  "clientId": "{{clientId}}",
  "clientSecret": "{{clientSecret}}"
}

Token request with cURL

Run this on your development machine or backend. Save your credentials as auth.json using the JSON structure above; keep that file out of source control. The URL below expands the authentication URL in the supplied test collection.

curl --request POST \
  'https://dev.nonprod.rolengiapps.com/uhasibu/auth/token/opaque' \
  --header 'Content-Type: application/json' \
  --data-binary @auth.json

Store the token returned by the authentication service on your backend and send it with its token type. Follow the expiry returned by the service; obtain a new token when needed. A new token does not require a new API client.

Authenticated requests

Send the token and its returned token type in the Authorization header. The integration reference uses Opaque as the default token type.

Authorization: {{tokenType}} {{authToken}}

Payment API headers

Credential handling

Make authenticated requests from your application backend. Store client secrets and tokens securely and exclude them from logs. Keep request identifiers separate from authentication tokens.

Illustrative token response

Example response mapping only. The actual response may use a different envelope or field names; map the values returned by your authentication endpoint.

{
  "access_token": "example-token",
  "token_type": "Opaque",
  "expires_in": 3600
}

In this example, access_token becomes NYUZA_TOKEN and token_type becomes NYUZA_TOKEN_TYPE. expires_in is an illustrative lifetime in seconds, not a guaranteed Nyuza token lifetime.

Express checkout

Submit your order details using your organizationId in the path. Nyuza creates a new order, creates its invoice and payment, and saves the invoice and payment references against the order.

Send the request

The request combines order details with payment configuration. The full nested structure is available in Request reference.

Send checkout with cURL

Save your checkout JSON as checkout.json. Set NYUZA_ORGANIZATION_ID, NYUZA_TOKEN_TYPE, NYUZA_TOKEN, NYUZA_INSTITUTION, NYUZA_CHANNEL, NYUZA_REQUEST_ID and NYUZA_TIMESTAMP in your local shell. Use a fresh timestamp in the format required by your endpoint configuration.

curl --request POST \
  "https://dev.nonprod.rolengiapps.com/duka-manager/v1/api/orders/${NYUZA_ORGANIZATION_ID}/checkout/express" \
  --header "Authorization: ${NYUZA_TOKEN_TYPE} ${NYUZA_TOKEN}" \
  --header "institution: ${NYUZA_INSTITUTION}" \
  --header "channel: ${NYUZA_CHANNEL}" \
  --header "request-id: ${NYUZA_REQUEST_ID}" \
  --header "timestamp: ${NYUZA_TIMESTAMP}" \
  --header 'accept-language: en' \
  --header 'Content-Type: application/json' \
  --data-binary @checkout.json

Save the result and redirect

The checkout data object contains three fields:

{
  "invoiceId": "{{invoiceId}}",
  "paymentUrl": "{{paymentUrl}}",
  "paymentId": "{{paymentId}}"
}

Save invoiceId and paymentId against your purchase, then redirect the customer to the exact paymentUrl returned. This URL identifies the hosted checkout for the invoice. A successful response means checkout has been initiated; confirm the payment before fulfillment.

Starter checkout body

Save this illustrative starter body as checkout.json and replace the identifier placeholders. It is a compact starting point, not a validated minimum schema; your organization may require additional order or audit fields.

{
  "details": {
    "referenceNumber": "ORDER-DEMO-001",
    "description": "Demo service purchase",
    "saleOrderLines": [
      {
        "productSaleOrders": [
          {
            "productName": "Demo service",
            "productType": "SERVICE_PRODUCT",
            "quantity": 1,
            "price": 1500,
            "total": 1500,
            "fulfillmentType": "SALE"
          }
        ],
        "total": 1500
      }
    ],
    "total": 1500
  },
  "organizationId": "{{organizationId}}",
  "paymentProviderId": "{{paymentProviderId}}",
  "paymentSource": "WEB",
  "returnUrl": "https://merchant.example/payment/result"
}

Confirm payment

Use webhook notifications to follow payment lifecycle updates. Retrieve the payment when you need to check or reconcile its current outcome.

Use the paymentId returned by express checkout. Match the result to your purchase and verify the payment outcome, amount and currency before fulfillment. A customer reaching your return page does not confirm payment; they may also close checkout before returning.

Recover an interrupted checkout

Keep your purchase reference and request identifier. If checkout times out or fails after processing begins, reconcile any existing order, invoice or payment before creating another checkout. Records may already have been created.

Find payment and transaction records

These endpoints list payments and transactions respectively. Match records using the relevant payment or correlation identifier. A list response alone is not confirmation that the current payment succeeded.

Troubleshoot the first payment

Illustrative payment mapping

The following is an application-side example, not a confirmed Nyuza response schema. Map the actual payment response into your own record before applying business rules.

{
  "purchaseReference": "ORDER-DEMO-001",
  "paymentId": "{{paymentId}}",
  "status": "succeeded",
  "amount": 1500,
  "currency": "KES"
}

For your application, a simple status model can use pending, succeeded and failed. These are local example labels, not documented API enum values. Map the provider’s actual statuses explicitly; keep unknown outcomes unresolved until verified.

Webhooks

Configure and test your callback before starting the first checkout. This ensures your backend can receive the resulting lifecycle events.

Subscribe to lifecycle events so your backend receives payment updates independently of the customer’s browser. Configure a callback endpoint, process notifications, and use delivery history to investigate or resend events.

Configure in Console

Open console.nyuza.com and navigate to Settings → Tools & Integrations → Webhooks. On the Webhooks & Integrations page, open the Configuration tab.

Understand the URLs

Process lifecycle events

Validate your configured authentication headers and match the notification to the stored payment and purchase. Use the reported payment outcome to update your records, and verify amount and currency before fulfillment.

Duplicate deliveries, including manual resends, retain the same reference keys. Record successful processing against those references and acknowledge duplicates without repeating fulfillment or other business actions. If processing previously failed, allow the resent event to complete the work.

A payment can receive multiple lifecycle updates. Deduplicate the same event while allowing later updates for that payment; paymentId alone is not sufficient to distinguish them.

Review history and resend

Open the History tab under Settings → Tools & Integrations → Webhooks. Each row shows the callback time, payment ID, destination URL, HTTP status and delivery success. Filter by a preset period or date range, then select Search. Use the page controls to browse results.

To redeliver an event, locate its row, check the payment ID and destination, and select Resend. The resent event keeps the same reference keys and does not create a new payment.

HTTP status and Success describe callback delivery. A 200 response confirms that your endpoint responded successfully; determine payment success from the event data or payment lookup.

Configure through the API

Configure your application callback destination and customer return URL using the shared payment API headers.

{
  "webHookSettings": {
    "enabled": true,
    "paymentStatusCallbackUrl": "{{callbackUrl}}",
    "notifyAnkaraStatus": false,
    "headers": {
      "X-Client-Key": "{{callbackKey}}"
    }
  },
  "paymentReturnUrlSettings": [
    {
      "paymentSource": "WEB",
      "channel": "{{channel}}",
      "returnUrl": "{{returnUrl}}"
    }
  ]
}

The example enables external callbacks and disables Ankara notification routing. The headers object sets custom headers for callback requests; X-Client-Key is an example.

Read back the settings after configuration and verify the callback URL, headers and return URL.

Test callbacks during local development

Implement a POST route on your backend, for example /webhooks/nyuza. Make it reachable through a public HTTPS development endpoint or tunnel; Nyuza cannot reach a localhost address on your laptop. Configure that public URL and your chosen authentication header in Console.

Send a local test request to verify your route accepts JSON and validates the header. Then complete a test checkout using the test procedure supplied for your configured provider. Inspect Console → Webhooks → History and your application logs. Select Resend to verify that the same event does not repeat fulfillment.

A delivery test checks connectivity. Verify business processing separately: the callback must match the purchase, update the payment outcome correctly and handle repeated deliveries.

Illustrative event mapping

Use this example to structure your handler’s internal event record. It does not define the Nyuza webhook payload or its reference-key names.

{
  "eventReference": "example-event-001",
  "purchaseReference": "ORDER-DEMO-001",
  "paymentId": "{{paymentId}}",
  "eventType": "payment.updated",
  "status": "succeeded",
  "amount": 1500,
  "currency": "KES"
}

Map the webhook’s actual duplicate reference keys to your internal eventReference. A resend maps to the same eventReference; a distinct lifecycle event must remain distinguishable. The example eventType and status are illustrative labels.

Separate-step integration

Choose this approach when you need control over each creation stage: create an order, create its invoice, create a payment, then initiate a payment transaction. The payment operations below follow order and invoice creation. Use the authenticated headers from Authentication.

Create a payment

{
  "externalReference": "{{externalReference}}",
  "amount": {"amount": 1500, "currency": "KES"},
  "paymentSource": "WEB",
  "description": "{{paymentDescription}}",
  "requestPayment": false,
  "phoneNumber": "{{paymentPhoneNumber}}",
  "paymentTerm": "PREPAID",
  "allowSplitPayments": true
}

Retain the payment identifier for the transaction request and subsequent lookup.

Create a transaction

{
  "paymentRefId": "{{paymentId}}",
  "paymentProviderType": "MPESA",
  "paymentSource": "WEB",
  "description": "{{paymentDescription}}",
  "amount": {"amount": 1500, "currency": "KES"},
  "externalTransactionId": "{{externalTransactionId}}",
  "correlationId": "{{correlationId}}",
  "customerRefId": "{{customerRefId}}",
  "requestPayment": true,
  "phoneNumber": "{{paymentPhoneNumber}}"
}

paymentRefId links the transaction to the payment record. Store the payment, transaction, external reference and correlation identifiers separately. The example uses MPESA, WEB, PREPAID and KES.

Request reference

Use this reference for the full express checkout structure and optional invoice metadata behavior. Include the fields needed for your use case and replace the example values with transaction data.

The full body is a field reference, not a minimum-required request. Required fields depend on request validation and your configuration. Use a validated request for your organization when testing.

Understand the amount fields

Use the currency and amount units configured for your payment integration. Do not infer amount units or charge calculation rules from the illustrative values in the field reference.

Invoice metadata

Nyuza copies invoiceMetadata, then applies the dedicated request values and the order-derived minimum. Other metadata keys are preserved.

Minimum amount

Each positive minimumOrderAmount contributes once to the sum. Missing, zero and negative values are excluded. Quantity is not multiplied into this calculation.

This example produces minimumAmount = 150. The calculation uses the saved order’s product entries.

Full request structure

{
  "details": {
    "saleOrderLines": [
      {
        "productSaleOrders": [
          {
            "productVariantId": "string",
            "productName": "Demo service",
            "productType": "SERVICE_PRODUCT",
            "variantName": "string",
            "quantity": 1,
            "price": 1500,
            "discount": 0,
            "total": 1500,
            "minimumOrderAmount": 0,
            "fulfillmentType": "SALE",
            "inventoryUnitId": "string",
            "serviceAssetAssignmentId": "string",
            "billable": true,
            "costed": true
          }
        ],
        "discount": 0,
        "total": 1500
      }
    ],
    "serviceAssetAssignmentId": "string",
    "referenceNumber": "ORDER-DEMO-001",
    "discount": 0,
    "total": 1500,
    "favorite": true,
    "description": "Demo purchase",
    "fulfillmentMethod": "PICKUP",
    "deliveryAddress": "string",
    "preferredRiderPhone": "string",
    "deliveryEstimate": 0,
    "fulfillmentAddress": "string",
    "fulfillmentContactName": "string",
    "fulfillmentContactPhone": "string",
    "fulfillmentInstructions": "string",
    "requestedFulfillmentAt": "string",
    "fulfillmentFee": 0
  },
  "audit": {
    "customers": [
      "string"
    ],
    "agentMemberId": "string",
    "creatorMemberId": "string",
    "organizationId": "string",
    "stageId": "string",
    "organizationBranchId": "string"
  },
  "recommendedAmount": 1500,
  "paymentProviderId": "paymentProviderId",
  "paymentSource": "WEB",
  "returnUrl": "https://merchant.example/payment/result",
  "standingOrderWalletRefId": "string",
  "invoiceMetadata": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  },
  "paymentAllocations": [
    {
      "standingOrderWalletRefId": "string",
      "paymentProviderId": "string",
      "amount": {
        "amount": 1500,
        "currency": "KES"
      }
    }
  ],
  "organizationId": "string"
}