Check Payment Order Status

This documentation section provides a clear and structured guide for users to test the "Check Payment Order Status" API using the sandbox environment. It includes all necessary steps, example requests, and responses, along with a practical example using curl.

Endpoint

This endpoint registers a payment order and returns a checkout URL for the user to complete the payment process.

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

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"
}

Parameters:

Name	Required	Type	Description
order_number	Yes	string	The unique identifier for the order.

Example Request

POST /api/v1/verify HTTP/1.1
Host: api.wagapay.net
Content-Type: application/json
apiKey: WAGA-LIVE.HDPC6.09ZNPIW5XAXPBHF5IR2NDMYDFQUGHTPCIBMD33K74S
 
{
  "order_number": "ORD123456789"
}

Responses

Success Response

200 OK

Order status retrieved successfully.

{
  "code": 200,
  "message": "Order status retrieved successfully",
  "data": {
    "order_id": "12345",
    "order_number": "ORD123456789",
    "status": "COMPLETED",
    "amount": "100.00",
    "deducted": "100.00",
    "currency": "ETB",
    "payment_option": "telebirr_wallet",
    "payment_type": "DIRECT",
    "customer_phone": "+251912345678",
    "reason": "Payment for Service",
    "created_timestamp": "2024-03-21T10:30:00Z",
    "updated_timestamp": "2024-03-21T10:31:00Z"
  }
}

Response Fields

Name	Type	Description
order_id	string	Internal ID of the order
order_number	string	Your provided order reference number
status	string	Current status of the payment
amount	string	Original transaction amount
deducted	string	Amount actually deducted
currency	string	Currency of the transaction
payment_option	string	Payment method used
payment_type	string	Type of payment (LINK/QR/DIRECT/API)
reason	string	Payment description
created_timestamp	string	Transaction creation time
updated_timestamp	string	Last status update time

✅

Transaction Found: The status of your payment order is retrieved successfully. The current status is shown in the response data. Possible status values - PENDING: Payment initiated but not completed - COMPLETED: Payment successfully completed - FAILED: Payment failed - EXPIRED: Payment session expired

Error Responses

400 Bad Request

The request could not be processed due to invalid input.

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

⚠️

Bad Request: There was an issue with your request. Please check the input data and ensure the order_number is 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 specified order number could not be found. Please check the order_number 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 status of a payment order, you can use the following sandbox server endpoint:

Sandbox Server URL: https://sandbox.wagapay.net/api/v1/verify (opens in a new tab) Steps to Test

Generate a Test API Key:

Create a Payment Order:

Use the /register endpoint to create a test payment order. Ensure you note the order_number from the response.

Check the Payment Order Status:

Use the following POST request to check the status of the payment order.

  POST /api/v1/verify HTTP/1.1
  Host: sandbox.wagapay.net
  Content-Type: application/json
  apiKey: YOUR_TEST_API_KEY
 
  {
    "order_number": "YOUR_ORDER_NUMBER"
  }

Verify the Response:

Check the response to ensure the status of the payment order is as expected.

Example using curl You can use curl to test the API from the command line:

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 verifyEndpoint = '/api/v1/verify';
 
const requestBody = {
  order_number: "ZJ2Xk132l8uy"
};
 
const headers = {
  "Content-Type": "application/json",
  "apiKey": testAPIKey
};
 
fetch(wagaURL + verifyEndpoint, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(requestBody)
})
.then(response => {
  console.log('Status Code:', response.status);
  return response.json();
})
.then(data => console.log('Response:', data))
.catch(error => console.error('Error:', error));

Note: Replace YOUR_TEST_API_KEY and YOUR_ORDER_NUMBER with your actual test API key and order number.

This will help you test the API in the sandbox environment before moving to production.