Get Payment Transaction Status
curl --request GET \
--url https://sandbox.fapshi.com/payment-status/{transId} \
--header 'apikey: <api-key>' \
--header 'apiuser: <api-key>'const options = {method: 'GET', headers: {apiuser: '<api-key>', apikey: '<api-key>'}};
fetch('https://sandbox.fapshi.com/payment-status/{transId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.fapshi.com/payment-status/{transId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"apikey: <api-key>",
"apiuser: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://sandbox.fapshi.com/payment-status/{transId}"
headers = {
"apiuser": "<api-key>",
"apikey": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)HttpResponse<String> response = Unirest.get("https://sandbox.fapshi.com/payment-status/{transId}")
.header("apiuser", "<api-key>")
.header("apikey", "<api-key>")
.asString();package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://sandbox.fapshi.com/payment-status/{transId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("apiuser", "<api-key>")
req.Header.Add("apikey", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"transId": "<string>",
"status": "CREATED",
"medium": "mobile money",
"serviceName": "<string>",
"transType": "Collection",
"amount": 123,
"revenue": 123,
"payerName": "<string>",
"email": "jsmith@example.com",
"redirectUrl": "<string>",
"externalId": "<string>",
"userId": "<string>",
"webhook": "<string>",
"reason": "<string>",
"financialTransId": "<string>",
"dateInitiated": "2023-12-25",
"dateConfirmed": "2023-12-25"
}{
"message": "<string>"
}{
"message": "<string>"
}{
"message": "<string>"
}Endpoints
Get Payment Transaction Status
Retrieve the status of a payment transaction using its transaction ID.
GET
/
payment-status
/
{transId}
Get Payment Transaction Status
curl --request GET \
--url https://sandbox.fapshi.com/payment-status/{transId} \
--header 'apikey: <api-key>' \
--header 'apiuser: <api-key>'const options = {method: 'GET', headers: {apiuser: '<api-key>', apikey: '<api-key>'}};
fetch('https://sandbox.fapshi.com/payment-status/{transId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.fapshi.com/payment-status/{transId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"apikey: <api-key>",
"apiuser: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://sandbox.fapshi.com/payment-status/{transId}"
headers = {
"apiuser": "<api-key>",
"apikey": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)HttpResponse<String> response = Unirest.get("https://sandbox.fapshi.com/payment-status/{transId}")
.header("apiuser", "<api-key>")
.header("apikey", "<api-key>")
.asString();package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://sandbox.fapshi.com/payment-status/{transId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("apiuser", "<api-key>")
req.Header.Add("apikey", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"transId": "<string>",
"status": "CREATED",
"medium": "mobile money",
"serviceName": "<string>",
"transType": "Collection",
"amount": 123,
"revenue": 123,
"payerName": "<string>",
"email": "jsmith@example.com",
"redirectUrl": "<string>",
"externalId": "<string>",
"userId": "<string>",
"webhook": "<string>",
"reason": "<string>",
"financialTransId": "<string>",
"dateInitiated": "2023-12-25",
"dateConfirmed": "2023-12-25"
}{
"message": "<string>"
}{
"message": "<string>"
}{
"message": "<string>"
}Endpoint
GET /payment-status/:transId
Check the status of a payment by transaction ID.
Status Values
| Status | Meaning |
|---|---|
| CREATED | Payment not yet attempted. |
| PENDING | User is in process of payment. |
| SUCCESSFUL | Payment completed successfully. |
| FAILED | Payment failed. The reason is not provided (see below). |
| EXPIRED | This means 24 hours have passed since the payment link was generated and no successful payment attempt was made in that time interval OR the link got manually expired to prevent payment. |
No payments can be made after the status is SUCCESSFUL or EXPIRED.
Fapshi does not collect partial payments. It always collects the full
amount you passed to the API, so a SUCCESSFUL status means that exact amount was collected. The revenue field is the amount you receive after Fapshi’s 3% fee. See Amounts and Fees.A
FAILED status does not indicate why the payment failed. Fapshi does not distinguish between insufficient funds, a declined or cancelled payment, or a prompt the customer did not respond to, because operator messages are usually too vague to tell with certainty. See Failed Transactions.Error Responses
| HTTP status | When it happens |
|---|---|
| 400 | The transId supplied is not a valid transaction ID (e.g., malformed). |
| 404 | The transId is well-formed but no transaction with that ID was issued by Fapshi for your service. |
| 429 | You exceeded the rate limit for this transId (see below). |
message field explaining the error. Never treat a 400 or 404 response as a payment failure: it means the transaction does not exist.
For a given transaction ID, you can make at most 6 requests per minute. Exceeding this limit returns a 429 response.It is generally better to rely on webhook notifications to know when a payment status changes, rather than polling this endpoint.
Path Parameters
Transaction ID of the payment.
Response
Payment status retrieved successfully
Transaction ID of the payment.
Transaction status
Available options:
CREATED, PENDING, SUCCESSFUL, FAILED, EXPIRED Payment method
Available options:
mobile money, orange money, fapshi Name of the service in use
Type of transaction
Available options:
Collection, Payout Transaction amount
Amount received when Fapshi fees (3% of amount) have been deducted
Client name
Client email
URL to redirect after payment
The transaction ID on your application
ID of the client on your application
The webhook you defined for your service
Typically appears when a payout via fapshi fails
Transaction ID with the payment operator
Date when the payment was initiated
Date when the payment was made