Register Payment Order

This page is your complete guide to WagaPay’s payment order registration endpoint — the first step in initiating a transaction through our gateway. Here, you’ll learn how to structure your request, interpret the response, and handle key parameters with confidence. We’ve also included details on how to test your integration using our sandbox environment, so you can build and validate without ever touching real funds. Whether you’re just getting started or fine-tuning your flow, this endpoint is where the Waga journey begins.

Endpoint

This endpoint kicks off the payment journey by registering a new payment order with WagaPay. Once successfully called, it returns a secure, one-time checkout URL that you can redirect your user to in order to complete the transaction.

POST https://api.wagapay.net/api/v1/register

Request

Headers

Name	Required	Type	Description
apiKey	Yes	string	The API Key generated in the merchant dashboard. Use the test key with the sandbox environment and the live key for production.

Example: WAGA-LIVE.HDPC6.09ZNPIW5XAXPBHF5IR2NDMYDFQUGHTPCIBMD33K74S |

Request Body

Content-Type: application/json
Schema:

{
  "order_number": "string",
  "return_url": "string",
  "webhook_url": "string", // Optional
  "amount": "string",
  "currency": "string",
  "reason": "string",
  "customer_phone": "string"
}

Parameters:

Name	Required	Type	Description
order_number	Yes	string	The unique identifier for the order.
return_url	Yes	string	The URL to which the user will be redirected after payment.
webhoook_url	No	string	The Webhook URL where you can receive status updates. see Webhooks for further details.
amount	Yes	string	The total amount for the order.
currency	Yes	string	The currency code (e.g., ETB, USD).
reason	Yes	string	The reason for the payment.
customer_phone	Yes	string	The phone number of the customer.

Example Request

http
 
POST /register HTTP/1.1
Host: api.wagapay.net
Content-Type: application/json
apiKey: WAGA-LIVE.HDPC6.09ZNPIW5XAXPBHF5IR2NDMYDFQUGHTPCIBMD33K74S
 
{
  "order_number": "123456",
  "return_url": "https://yourdomain.com/return",
  "amount": "100.00",
  "currency": "ETB",
  "reason": "Payment for order #123456",
  "customer_phone": "+1234567890"
}

Responses

Success Response

201 Created

Order registration successful.

{
  "code": 1,
  "message": "Order registration successful",
  "data": {
    "checkout_url": "https://checkout.wagapay.net/api/55e529a3-33e6-4060-a866-718c07728698"
  }
}

✅

Order Registration Successful: Your payment order has been successfully registered. Use the provided checkout_url to complete the payment process.

Error Responses

400 Bad Request

The request could not be processed due to invalid input.

{
  "code": 400,
  "message": "Bad request"
}

⚠️

Bad Request: It seems like there was an issue with your request. Please check the input data and ensure all required fields are provided correctly.

401 Unauthorized

Authentication failed. Ensure the API key is correct.

{
  "code": 401,
  "message": "Unauthorized"
}

❌

Unauthorized: Your API key is invalid or missing. Please provide a valid API key in the request header.

403 Forbidden

Access to the resource is forbidden.

{
  "code": 403,
  "message": "Forbidden"
}

🚫

Forbidden: You do not have permission to access this resource. Please ensure you have the necessary permissions.

404 Not Found

The endpoint or resource could not be found.

{
  "code": 404,
  "message": "Not found"
}

🔍

Not Found: The requested endpoint or resource could not be found. Please check the URL and try again.

500 Internal Server Error

Server Error: An error occurred on the server side.

{
  "code": 500,
  "message": "Internal server error"
}

💥

Internal Server Error: We encountered an unexpected error on our side. Please try again later or contact support if the problem persists.

Testing

To test the "Register a Payment Order" endpoint, you can use the sandbox environment provided by Waga. Follow the steps below:

Set Up Your API Key:

Ensure you have your test API key ready. You can find this in the Waga merchant dashboard under the "API Keys" section. Use the test key for the sandbox environment.

Prepare the Request:

Create a request to the following URL:

Sandbox URL: https://sandbox.wagapay.net/api/v1/register (opens in a new tab)

Set Up Request Headers:

Include the API key in the header of your request. Here’s an example using curl:

const fetch = require('node-fetch');
 
const testAPIKey = 'your-test-key'; // In a production setting, the API key should be retrieved from an env file.
const wagaURL = 'https://sandbox.wagapay.net';
const registerEndpoint = '/api/v1/register';
 
const requestBody = {
  order_number: "ZJ2Xk132l8uy",
  return_url: "http://google.com",
  amount: "1",
  currency: "ETB",
  reason: "Testing",
  business_name: "Apple Inc.",
  customer_phone: "0911121314"
};
 
const headers = {
  "Content-Type": "application/json",
  "apiKey": testAPIKey
};
 
fetch(wagaURL + registerEndpoint, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(requestBody)
})
.then(response => {
  console.log(response.status);
  return response.json();
})
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Note: Replace YOUR_TEST_API_KEY with your actual test API key and update the JSON payload with your test data.

Send the Request:

Send the request using your preferred method (curl, Postman, etc.). If the request is successful, you should receive a response similar to the example response above with a checkout URL.

Handle the Response:

Check the response code and message. If the order is registered successfully, use the provided checkout URL to proceed with the payment process.

Example Successful Response:

{
  "code": 1,
  "message": "Order registration successful",
  "data": {
    "checkout_url": "https://checkout.wagapay.net/api/55e529a3-33e6-4060-a866-718c07728698"
  }
}

Note: Use the checkout URL to test the payment process in the sandbox environment.

If the request fails, refer to the error responses provided above and adjust your request accordingly. For instance, if you receive a 400 Bad Request error, verify that all required fields are correctly filled and retry the request.

This testing guide should help you verify the functionality of the "Register a Payment Order" endpoint in a controlled environment before moving to production.

Authentication Payment order status