Skip to main content

Create Order

Create Order is the first step of the payment process. It represents the act of registering a customer’s intended purchase with KidaPay so that the system can handle the payment securely.

When you call the Create Order API: You send order details to KidaPay Amount the customer needs to pay Currency Customer information (like email or ID) Metadata (your own reference IDs, notes, etc.) Callback/redirect URLs This tells KidaPay “a customer wants to make this payment.” KidaPay creates an Order record This order becomes a container for all payment-related information (amount, currency, customer, status). The order is linked to your merchant account so you can track it.

The Create Order API does two key things:

  1. Sends the customer’s order information to the KidaPay system This is the first step in the payment flow after the customer selects a product or service and is ready to pay. The order information include;
  • Amount the customer needs to pay
  • Currency
  • Customer information (like email or ID)
  • Metadata (your own reference IDs, notes, etc.)
  • Callback URL -Webhook URL

“Here is a customer, here’s what they want to pay for, here’s the amount, and here are the details.” KidaPay then stores this information as an order record in your merchant account.

  1. KidaPay creates an Order record

  • This order becomes a container for all payment-related information (merchant_order_id, amount, currency, customer, status, callback URL, webhook URL).

  • The order is always linked to your merchant account, allowing you to track and manage it. You can link the order using your own merchant_order_id (a unique reference you provide in the request body).

If you don’t include a merchant_order_id, KidaPay will automatically generate one for you. This ensures that every order is uniquely identifiable — whether by your system’s reference or by KidaPay’s autogenerated merchant_order_id.

  1. Returns a payment link
  • This is the unique link to KidaPay’s crypto payment page.
  • You redirect the customer to this page where they complete the transaction with their chosen cryptocurrency. If the customer’s email is provided in the order request, the payment link will also be sent directly to their email.

Example​

When integrating KidaPay’s Create Order API, there are two environments you can use:

Test / Sandbox Environment

The sandbox environment is designed for developers to safely test order creation, payments, and webhook integrations without using real money. Instead of real crypto, the sandbox uses test cryptocurrencies on blockchain test networks. These tokens have no real-world value and can be obtained for free from public faucets.

https://api-sandbox.kidapay.com/v1/orders

Some Supported Test Networks & Faucets

💡 Use these test tokens to simulate deposits, withdrawals, and full payment flows just like in production — but with no financial risk.

Request body​

curl -X POST \
  https://api-sandbox.kidapay.com/v1/orders \
  -H 'content-type: application/json' \
  -H 'x-api-key: test_O89dfT0rdQwkLqHYwC8btg86wMFue75T' \
  -d '{
	"merchant_order_id": "503a854998-6230-4338-adb7",
  "customer_email": "customer@email.com"
  "title": "Monthly Program x 1",
  "description": "Gaming for your family",
  "amount": 1,
  "currency": "USD",
  "pay_currency": "USDT",
  "callback_url": "https://ecards.com/api/success",
  "webhook_url": "https://ecards.com/ecardstatus?status=webhook",
}'

POST Body​

{
    "merchant_order_id": "503a854998-6230-4338-adb7",
  "customer_email": "customer@email.com"
  "title": "Monthly Program x 1",
  "description": "Gaming for your family",
  "amount": 1,
  "currency": "USD",
  "pay_currency": "USDT",
  "callback_url": "https://ecards.com/api/success",
  "webhook_url": "https://ecards.com/ecardstatus?status=webhook",
}

Body Params​

ParamTypeRequiredDescription
merchant_order_idstringMerchant's unique order ID. We recommend using the orderID from your application. It's a unique order ID for your reference. If you don’t include a merchant_order_id, KidaPay will automatically generate one for you. This ensures that every order is uniquely identifiable — whether by your system’s reference or by KidaPay’s autogenerated merchant_order_id.
currencystringYesThe currency in which you wish to price your customer; used to define price parameter. Example: NGN, KES, ZAR, LRD, GHS, USD, EUR.
amountdoubleYesThe amount to be paid in fiat currency
titlestringMax 200 characters. Example: product title (Apple iPhone X), order id (OnlineStore Order #4321), cart id (Cart #00003552).
descriptionstringMore details about this order. Max 800 characters. It can be cart items, product details or other information. Example: 1 x Apple iPhone X, 1 x Apple MacBook Air.
callback_urlstring

The URL to which the customer’s browser will be redirected after completing or canceling the payment.
Example: https://onlinestore.com/payments/callback

webhook_urlstringThe endpoint on your server where KidaPay will send payment event notifications (e.g. order success, failure, or cancellation). This allows your system to automatically update order status in real time. You can set or update the webhook URL from the Merchant Portal.

Result Format​

Success Response

If the API call is successful, KidaPay returns a 201 status code along with the created order details and the payment link.

{
    "status": 201,
	"message": "Order created successfully",
    "data": {
        "user_id": 32014,
        "merchant_order_id": "503a854998-6230-4338-adb7",
        "title": "Monthly Program x 1",
        "description": "Gaming for your family",
        "callback_url": "https://ecards.com/api/success",
		"webhook_url": "https://ecards.com/ecardstatus?status=webhook",
        "amount": 1,
        "currency": "USD",
        "amount": 1,
        "order_id": "94be2b2a-2905-4857-b701-b04e57e84593",
        "status": "NEW",
        "created_at": "2019-04-24T16:57:35.416Z",
        "updated_at": "2019-04-24T16:57:35.416Z"
    },
    "payment_url": "https://invoice.kidapay.com/invoices?id=94be2b2a-2905-4857-b701-b04e57e84593"
}

Error Format KidaPay Server will always return status 400. If API failed, it will return error_code and error as its object.

{
    "status": 400,
    "error_code": "PARAMETERS_MISSING",
    "error": "Missing parameters."
}

API Errors​

Most common API errors are as follows, including message, reason and status code.

Response example:

{
  "error": "API request limit is exceeded",
  "error_code": "API_LIMIT_EXCEEDED",
  "status": "400"
}
StatusError CodeDescription
400AUTHENTICATION_FAILEDAuthentication Token is not set or expired.
401Unauthorized

API credentials are not valid.
This error may also occur if you try to use a Sandbox (test) API key on the Live (prod) API endpoint, or vice versa.

404Not FoundPage or action not found.
500InternalServerErrorServer error in KidaPay.