Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OluwagbeminiyiA/agro_pulse-API/llms.txt

Use this file to discover all available pages before exploring further.

AgroPulse uses a multi-stage payment pipeline to protect both buyers and farmers. When a buyer pays for an order, funds are not released to the farmer immediately — they are held in escrow until the buyer’s delivery is confirmed. After confirmation, the platform calculates a PaymentSplit and initiates separate payouts to the farmer and the transporter. Every step of this flow involves the Squad payment gateway, which handles checkout, webhook callbacks, and bank transfers.

​
Initialize payment

When a buyer is ready to pay for a PENDING order, they call: 
POST /api/payments/initialize_payment/

{
  "order": "<order_id>"
}
The API creates a Payment record linked to the order and calls the Squad API to generate a hosted checkout session. The response includes a checkout_url that the buyer’s client should redirect to or open in a browser. 
{
  "id": "<payment_id>",
  "payment_status": "PENDING",
  "amount": "15000.00",
  "currency": "NGN",
  "checkout_url": "https://checkout.squadco.com/...",
  "escrow_enabled": true
}
The buyer completes the payment on Squad’s hosted checkout page using their preferred channel (CARD, TRANSFER, USSD, or VIRTUAL-ACCOUNT).

​
Webhook callback

After a successful payment, Squad sends a signed POST request to: 
POST /api/payments/webhook_callback/
AgroPulse verifies the payload signature, then:
  1. Sets payment_status to SUCCESS on the Payment record
  2. Records the squad_transaction_id returned by Squad
  3. Sets webhook_received and webhook_verified to true
  4. Advances the linked Order.order_status from PENDING to PAID
  5. Creates an EscrowAccount holding the full payment amount at release_status: "HELD"
The buyer does not need to take any action at this stage — the webhook is handled server-side automatically.

​
Verify payment

If a buyer needs to manually confirm whether their payment was captured (for example, after a network timeout during checkout), they can call: 
POST /api/payments/{id}/verify_payment/
This queries Squad’s API for the current state of squad_transaction_id and reconciles it against the local Payment record. The response reflects the current payment_status.

​
Escrow

Escrow is enabled by default on all payments (escrow_enabled: true). The EscrowAccount model holds funds on behalf of the farmer until delivery is confirmed.
FieldTypeDescription
amount_helddecimalTotal amount held in escrow
release_statusenumCurrent state: HELD, RELEASED, or DISPUTED
released_atdatetimeTimestamp of release, set when delivery is confirmed
Funds remain HELD through the PROCESSING and IN_TRANSIT order stages. Release is triggered automatically when the transporter calls POST /api/deliveries/{id}/delivery_confirmation/, which sets release_status to RELEASED and records released_at. To release funds manually (e.g., in a dispute resolution flow): 
POST /api/escrow/{id}/release_funds/
If a delivery cannot be completed and the order is disputed, release_status is set to DISPUTED and funds are held pending resolution.

​
Payment splits

Immediately after escrow release, AgroPulse creates a PaymentSplit record that divides the total payment into three components:
FieldTypeDescription
farmer_amountdecimalAmount owed to the farmer for the produce
rider_amountdecimalAmount owed to the transporter for delivery
platform_feedecimalAgroPulse’s platform fee retained from the transaction
farmer_processed and rider_processed are boolean flags that track whether each payout has been initiated. For PICKUP orders, rider_amount is 0.00 and rider_processed is set to true immediately.

​
Payouts

A Payout record is created for each recipient — one for the farmer (payout_type: "FARMER") and, for delivery orders, one for the transporter (payout_type: "RIDER"). Each payout tracks disbursement to the recipient’s virtual account. Payout statuses
payout_statusMeaning
PENDINGPayout created, not yet initiated
PROCESSINGTransfer request sent to Squad
COMPLETEDFunds successfully disbursed to recipient’s account
FAILEDTransfer failed; bank_reference may contain error details
To mark a payout as completed after the transfer is confirmed: 
POST /api/payouts/{id}/mark_completed/
The completed_at timestamp is recorded when a payout reaches COMPLETED.

​
Payment statuses

The Payment.payment_status field tracks the overall state of the buyer’s payment:
StatusMeaning
PENDINGPayment initialized; buyer has not yet completed checkout
SUCCESSSquad confirmed payment; escrow is active
FAILEDPayment attempt was unsuccessful at the gateway
REFUNDEDPayment was reversed after a cancellation or dispute

​
Full payment flow

1

Buyer initializes payment

POST /api/payments/initialize_payment/ creates a Payment record and returns a checkout_url. payment_status is PENDING.
2

Buyer completes checkout

The buyer pays via the Squad-hosted checkout page using card, USSD, transfer, or virtual account.
3

Squad sends webhook

Squad calls POST /api/payments/webhook_callback/. AgroPulse verifies the signature, sets payment_status to SUCCESS, records squad_transaction_id, and creates the EscrowAccount with release_status: "HELD". The order advances to PAID.
4

Farmer processes and transporter delivers

The order moves through PROCESSING and IN_TRANSIT. Escrow remains HELD throughout this period.
5

Delivery confirmed — escrow released

POST /api/deliveries/{id}/delivery_confirmation/ triggers escrow release (release_status → RELEASED). A PaymentSplit is created, dividing the amount into farmer_amount, rider_amount, and platform_fee.
6

Payouts created and processed

A Payout record is created for each recipient with payout_status: "PENDING". The platform initiates Squad transfers and updates status to PROCESSING, then COMPLETED via POST /api/payouts/{id}/mark_completed/.

Build docs developers (and LLMs) love

Get started for freeTalk to us