Developers
REST API
GuidesErrorsLogin
Get API Keys
API Navigation
  • Overview
  • Quick start
  • Authentication
  • Collect a payment
  • Payment status
  • Refunds
  • Testing
  • Production
  • Security
API reference
  • Create API keys POST
  • List API keys GET
  • Get API key GET
  • Delete API key DEL
  • Collect with MTN POST
  • MTN payment status GET
  • Collect with Airtel POST
    Create and pay
  • Create order POST
  • Order fee POST
  • Pay order with card POST
  • Pay order with bank POST
    • Status and verify
  • Order status POST
  • Verify order POST
    • Cards and tokens
  • Save card POST
  • Tokenize charge GET
    • Refunds
  • Refund order POST
    • Lists and stats
  • List orders GET
  • Get order GET
  • List banks GET
  • Order stats GET
  • List transactions GET
  • Get transaction GET
  • Transaction statuses GET
Errors and limits
  1. Docs
  3. API reference
  5. Create order

Create order

Create a TransactPay order for the signed-in merchant.

OpenAPI SpecRun in Postman
POST/payment/zibapay/order/createAPI
Authentication:Bearer token•Authorization: Bearer <token>(Bearer token for server-to-server API calls)
Security requirement: 403 CSRF Protection
Auth guide →

Direct server-to-server calls authenticated via Bearer tokens do not require CSRF headers. If you instead invoke mutation endpoints from a web browser using cookie-based sessions, you must include the following header:

X-Requested-With: XMLHttpRequest

Request body

FieldTypeRequiredDescription
order.amountnumberRequiredStored on the Ziba Pay order and sent to TransactPay.
order.currencystringRequired3-letter currency sent to TransactPay. Examples use RWF to match the default configured mobile-money market. Illustrative example.
order.descriptionstringRequiredNarrative description of order goods or service.
order.referencestringOptionalIgnored. The service assigns the unique order reference.
redirectUrlstringRequiredSent to TransactPay as payment.RedirectUrl.
import axios from "axios";

const url = "https://payment-service-mh2d.onrender.com/api/payment/zibapay/order/create";

const headers = {
    Authorization: `Bearer ${process.env.ZIBA_TOKEN}`,
    "Content-Type": "application/json",
};

const payload = {
  "order": {
    "amount": 1000,
    "currency": "RWF",
    "description": "Order 1042"
  },
  "redirectUrl": "https://merchant.example/return"
};

try {
  const response = await axios.post(url, payload, {
    headers,
    timeout: 15000,
  });
  console.log("Success:", response.status, response.data);
} catch (error) {
  console.error("Request failed:", error.response?.data || error.message);
}
Auth guide

Response fields

FieldTypePresenceDescription
statusstringAlways returnedsuccess
data.orderIdstringAlways returnedZiba Pay assigned order reference ID.
data.referencestringAlways returnedReference assigned to this transaction.
data.amountnumberAlways returnedOrder monetary amount in currency units.
data.currencystringAlways returnedCurrency code (e.g. NGN, RWF, GHS, USD).
data.descriptionstringAlways returnedOrder description provided during creation.
data.statusstringAlways returnedInitial order status: PENDING.
data.redirectUrlstringAlways returnedMerchant return URL after customer checkout.
data.checkoutUrlstringOptionalTransactPay hosted checkout link.

Status codes

HTTP StatusMeaning
201Order created successfully.
401No merchant session. Missing Bearer token.
403KYC is not VERIFIED. Complete KYC verification in merchant dashboard.
404{ message: "User Not Found" } when the session has no user.

Notes

  • The merchant kycStatus must be VERIFIED. Otherwise the response is 403 { message: "User must complete KYC to create an order" }.
  • The customer name, email, country, and phone are taken from the signed-in user, not from this body.
  • HTTP 201 returns the JSON produced by the TransactPay create-order call, without a Ziba Pay envelope.

Related

Pay order with cardPay order with bankOrder status
Was this page helpful?

Let us know how we can make our API documentation better.

PreviousCollect with Airtel
NextOrder fee