Get Transaction Status

Check the status of a previously initiated debit request.

Endpoint

GET /api/v1/payment-providers/debit-requests/:reference

Authentication

Requires a valid Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Path Parameters

Parameter	Type	Required	Description
reference	string	Yes	FLUID transaction reference returned from charge request

Request

Example Request

curl --request GET \
  --url https://api.fluid-network.com/api/v1/payment-providers/debit-requests/FLU123456789 \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json'

Response

Success Response

Status Code: 200 OK

{
  "success": true,
  "data": {
    "reference": "FLU123456789",
    "status": "completed",
    "response": {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "timestamp": "2025-01-05T12:00:00Z",
      "processed_at": "2025-01-05T12:03:00Z",
      "completed_at": "2025-01-05T12:05:00Z",
      "bank_reference": "BNK987654321",
      "approval_method": "ussd",
      "error_message": null
    }
  },
  "meta": {
    "timestamp": "2025-01-05T12:10:00Z",
    "request_id": "xyz-789",
    "api_version": "v1"
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
data.reference	string	FLUID Network transaction reference
data.status	string	Current transaction status (see statuses below)
data.response.uuid	string	Unique transaction identifier
data.response.status	string	Current transaction status
data.response.timestamp	string	Transaction creation timestamp (ISO 8601)
data.response.processed_at	string	Processing start timestamp (null if not yet processed)
data.response.completed_at	string	Completion timestamp (null if not completed)
data.response.bank_reference	string	Bank's internal reference number (null if not provided)
data.response.approval_method	string	How customer approved: "ussd", "mobile_api", or "web"
data.response.error_message	string	Error details if transaction failed (null otherwise)

Transaction Statuses

Status	Description	Is Final?
pending	Awaiting customer approval	No
processing	Customer approved, payment in progress	No
completed	Payment successfully completed	Yes
failed	Transaction failed or declined	Yes
cancelled	Cancelled by customer or timeout	Yes

Final Statuses: Transactions with final statuses (completed, failed, cancelled) will not change. You can stop polling once a final status is reached.

Error Responses

Transaction Not Found

Status Code: 404 Not Found

{
  "success": false,
  "error": {
    "code": 3404,
    "message": "Transaction not found",
    "category": "transactions"
  }
}

Common Causes:

• Invalid or non-existent transaction reference
• Transaction belongs to a different payment provider
• Typo in reference number

Unauthorized

Status Code: 401 Unauthorized

{
  "success": false,
  "error": {
    "code": 1401,
    "message": "Unauthorized",
    "category": "authentication"
  }
}

Status Polling Strategy

Avoid Excessive Polling: Implement webhooks for real-time status updates instead of continuous polling.

If webhooks are not available, use this polling strategy:

1. Wait 5 seconds, then check status
2. If not final, wait 10 seconds
3. Continue with increasing delays: 15s, 20s, 30s...
4. Stop polling after 5 minutes (timeout)

Recommended Polling Intervals

• First check: 5 seconds after charge initiation
• Subsequent checks: Exponential backoff (10s, 15s, 20s, 30s, 30s, 60s, 60s)
• Maximum wait time: 5 minutes
• Stop condition: Final status reached (completed, failed, cancelled)

Recommended Approach

1. Create charge and store reference
2. Configure webhook endpoint to receive status updates (preferred method)
3. If webhook doesn't arrive within 60 seconds, start polling with exponential backoff
4. Once final status received, stop all polling

Use Cases

1. Verify Charge Initiation

After creating a charge, verify it was recorded correctly by immediately checking the transaction status.

2. Reconciliation

Check historical transactions for reconciliation by querying transaction status and comparing against your internal records.

3. Customer Support

Provide transaction details to customers by looking up status information using the FLUID reference number.

Best Practices

1. Cache Transaction Status

Once a transaction reaches a final status (completed, failed, cancelled), cache the result to avoid unnecessary API calls. Final statuses never change.

2. Handle Timeouts

Set request timeouts (recommended: 10 seconds) to avoid hanging requests. Retry failed requests with exponential backoff.

3. Display User-Friendly Status

Translate technical statuses into user-friendly messages:

• pending → "Waiting for approval - Please check your phone"
• processing → "Processing payment"
• completed → "Payment successful"
• failed → "Payment failed"
• cancelled → "Payment cancelled"

Rate Limits

• Production: 200 requests per minute per reference
• Sandbox: 60 requests per minute per reference

Rate Limit Scope: Rate limits are per transaction reference, not per API token. You can check multiple transactions simultaneously without hitting the limit.

Webhook Alternative

Instead of polling, configure webhooks to receive real-time status updates:

POST https://your-webhook-url.com/webhooks/fluid

{
  "event": "transaction.completed",
  "data": {
    "reference": "FLU123456789",
    "status": "completed",
    "amount": 100.00,
    "currency": "GHS",
    "partner_reference": "partner_tx_123456",
    "timestamp": "2025-01-05T12:05:00Z"
  },
  "signature": "sha256_signature_here"
}

Learn more: Webhook Configuration

Next Steps

• Configure webhooks for real-time updates
• Handle transaction failures
• Implement reconciliation
• Test complete payment flow