API Docs

Safon Automation API Integration Documentation. The definitive guide to connecting your backend architecture securely with our automated SMS payment webhook engine.

Hello! If you are using "Safon Automation" as your automatic bank SMS payment verification engine, this document is for you. The app reads bank SMS receipts from your mobile phone and forwards the extracted JSON data to your backend server via a Webhook.

Below is the exact architecture and matching logic you need to write in your backend (PHP, Node, Python, etc.) to accept the webhook securely and process user payments.

1. Database Setup

Create a new table named incoming_transactions. It should have these columns:

  • id (Auto increment)
  • transaction_number (Unique - String/Varchar)
  • amount (Decimal)
  • status (Enum: 'unclaimed' or 'claimed', default 'unclaimed')
  • raw_sms (Text)

2. Webhook Endpoint

This handles receiving data from the Safon App. The app will send a POST request with the following JSON payload structure:

POST /webhook 
{
  "transaction_id": "FT2345678X",
  "amount": "500.00",
  "sender": "telebirr",
  "bank": "Telebirr",
  "type": "DEPOSIT"
}

When this Webhook receives the request:
a. It MUST verify the authenticity of the request using an X-API-KEY header.
b. If the incoming request is a GET request, it means the App is doing a "Connection Test". It should return a 200 OK response with "Connected Successfully".
c. If it is a POST request, it should insert the extracted details into the incoming_transactions table with the status as "unclaimed".
d. Then, it should immediately query your pending users to see if there is any user whose transaction_id and amount perfectly matches. If found, it should automatically mark the user as 'Active/Approved' and change the SMS status to 'claimed'.

3. User Payment Submission Endpoint

This is the endpoint where your users submit their payment proof on your own site.

  • a. First, check the incoming_transactions table to ensure this Transaction ID has not been used ('claimed') by another user already (Duplication & Fraud Prevention).
  • b. If the transaction is 'unclaimed', STRICTLY verify if the Amount entered by the user matches the exact Amount in the SMS transaction record. If it matches 100%, approve the user and mark the SMS as 'claimed'. If the amounts do not match, REJECT the user request immediately (Fraud Prevention).
  • c. If the transaction has not arrived yet via the webhook, save the user's status as "Pending" and store their submitted Transaction ID and Amount so that the Webhook can auto-approve them later whenever the SMS finally hits the server.