Transaction Status

Check the status of any payin or payout transaction using its transaction ID. This endpoint is useful for polling payment status when webhooks are not available or as a fallback to confirm a transaction's final state.

Endpoint Parameters Response Status Values Examples

Endpoint

GET /api/v1/merchant/transactions/{trx_id} Check transaction status

You can also use the alias endpoint /api/v1/merchant/status/{trx_id} — both return the same response.

Authentication required

Include your X-API-KEY header. You can only query transactions created with your own API key. See Authentication for details.

Path Parameters

Parameter	Type	Required	Description
`trx_id`	string	Required	The transaction ID returned in the payin or payout response (e.g. `PAY_NEFGOQN6QWT4_1788451423`)

Response

Success Response (200)

JSON 200 OK — Transaction found

{
    "success": true,
    "status": "initiated",
    "transaction_id": "PAY_NEFGOQN6QWT4_1788451423",
    "type": "payin",
    "provider": "jeko",
    "provider_ref": "6c7f6824-74e8-43ff-bc0f-9d1d0850078d",
    "created_at": "2026-09-03 16:03:43",
    "updated_at": "2026-09-03 16:03:43",
    "data": {
        "status": "initiated",
        "message": "Redirect to payment page required.",
        "provider": "jeko",
        "provider_ref": "6c7f6824-74e8-43ff-bc0f-9d1d0850078d",
        "action_url": "https://pay.wave.com/c/cos-2722qt5482jyw?a=100&c=XOF",
        "fee_percent": 3.5,
        "fee_amount": 3.5,
        "net_amount": 96.5
    }
}

Response Fields

Field	Type	Description
`success`	boolean	`true` if the transaction was found
`status`	string	Current transaction status (see Status Values)
`transaction_id`	string	The transaction reference ID
`type`	string	`payin` or `payout`
`provider`	string	Payment provider used (e.g. `jeko`, `intouch`)
`provider_ref`	string	Provider's internal reference ID
`created_at`	string	Transaction creation timestamp (UTC)
`updated_at`	string	Last update timestamp (UTC)
`data`	object	Additional transaction details (fee, net amount, action URL, etc.)
`data.action_url`	string	Payment redirect URL (for payin transactions awaiting customer action)
`data.fee_percent`	float	Fee percentage applied to the transaction
`data.fee_amount`	float	Fee amount collected
`data.net_amount`	float	Net amount credited to the merchant wallet
`data.confirmation_type`	string\|null	How the customer confirms: `redirect` (operator payment link), `operator_push` (PIN confirmation on the phone), `sms_ussd` (customer receives an SMS and must dial the USSD code to approve), `otp` (OTP collected on the hosted checkout page)
`data.otp_required`	boolean\|null	`true` when the transaction is parked waiting for the customer to submit their Orange Money OTP on the hosted checkout page
`data.ussd_code`	string\|null	USSD fallback code shown to the customer (e.g. `#144#` for Orange Money)
`data.instructions`	array\|null	Step-by-step customer instructions displayed on the hosted checkout page

Error Response (404)

JSON 404 — Transaction not found

{
    "success": false,
    "status": "failed",
    "code": "NOT_FOUND",
    "message": "Transaction not found.",
    "transaction_id": null,
    "data": null
}

Common cause of 404

The transaction is filtered by the API key owner. If you use an API key that belongs to a different merchant account, you will get a 404 even if the transaction exists. Always use the API key that was used to create the transaction.

Status Values

Status	Description
pending	Transaction created, waiting for provider response
initiated	Provider has initiated the payment, customer action required (e.g. redirect to payment page)
timeout_review	Provider outcome is ambiguous. Do not retry, refund, or create a new transaction until reconciliation confirms the final state.
success	Transaction completed successfully, funds credited to merchant wallet
failed	Transaction explicitly failed at the provider level. A timeout alone is not considered a failure.
rejected	Transaction was rejected by the provider
refunded	Transaction was refunded to the customer

Examples

cURL

Bash Check transaction status

curl -X GET "https://envoifacile.com/api/v1/merchant/transactions/PAY_NEFGOQN6QWT4_1788451423" \
  -H "X-API-KEY: ef_live_your_api_key_here"

Using the /status/ alias

Bash Alias endpoint (same response)

curl -X GET "https://envoifacile.com/api/v1/merchant/status/PAY_NEFGOQN6QWT4_1788451423" \
  -H "X-API-KEY: ef_live_your_api_key_here"

PHP (cURL)

PHP PHP example

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://envoifacile.com/api/v1/merchant/transactions/PAY_NEFGOQN6QWT4_1788451423");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-KEY: ef_live_your_api_key_here",
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['status']; // e.g. "success"

JavaScript (fetch)

JavaScript fetch example

const response = await fetch(
  "https://envoifacile.com/api/v1/merchant/transactions/PAY_NEFGOQN6QWT4_1788451423",
  {
    headers: {
      "X-API-KEY": "ef_live_your_api_key_here",
    },
  }
);

const data = await response.json();
console.log(data.status); // e.g. "success"

Polling recommendation

If you're polling this endpoint while waiting for a payment to complete, we recommend checking every 3–5 seconds. Once the status becomes success or failed, you should stop polling. For real-time updates, consider using Webhooks instead.