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 processes payments through the Squad payment gateway. When a buyer is ready to pay for an order, your client calls initialize_payment to create a payment record and receive a Squad-hosted checkout_url. The buyer completes payment on that page, after which Squad notifies AgroPulse via webhook and/or you can call verify_payment to confirm the outcome. Successful payments automatically create an escrow account and a payment split record.

​
Endpoints

MethodPathAuthDescription
GET/api/payments/RequiredList payments visible to the authenticated user
POST/api/payments/initialize_payment/RequiredStart a new payment and receive a checkout URL
POST/api/payments/{id}/verify_payment/RequiredConfirm payment status against Squad
POST/api/payments/webhook_callback/NoneSquad webhook receiver
GET/api/payments/my_payments/RequiredCurrent user’s payments
GET/api/payments/pending_payments/RequiredAll payments with PENDING status

​
Initialize payment

Creates a Payment record linked to the given order and returns a Squad checkout_url to redirect the buyer to.
​
order_id
string
required
UUID of the order to pay for. The order must not already have a successful payment.
curl -X POST https://api.agropulse.example/api/payments/initialize_payment/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

{
  "payment_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "squad_transaction_id": "SQUAD_TXN_REF_abc123",
  "checkout_url": "https://checkout.squadco.com/pay/SQUAD_TXN_REF_abc123",
  "amount": "15000.00"
}
Redirect the buyer to checkout_url. Squad handles card, bank transfer, USSD, and virtual-account channels.

​
Verify payment

Queries Squad directly for the current transaction status and updates the payment record. If the payment is successful and escrow is enabled, an EscrowAccount and PaymentSplit are created automatically. 
curl -X POST https://api.agropulse.example/api/payments/f47ac10b-58cc-4372-a567-0e02b2c3d479/verify_payment/ \
  -H "Authorization: Bearer <token>"
Returns the full Payment object on success, or {"error": "Payment verification failed"} with 400 on failure.

​
Webhook

Squad calls POST /api/payments/webhook_callback/ automatically after every transaction outcome. This endpoint requires no authentication but validates the x-squad-signature header using HMAC-SHA512. Expected payload structure: 
{
  "transaction_reference": "SQUAD_TXN_REF_abc123",
  "status": "success",
  "payment_method": "card",
  "amount": 1500000,
  "currency": "NGN",
  "merchant_id": "YOUR_MERCHANT_ID",
  "gateway_ref": "GW_REF_xyz"
}
status will be "success" or "failed". AgroPulse responds {"status": "received"} with 200 on success.

​
Payment status values

ValueMeaning
PENDINGPayment initiated, buyer has not completed checkout
SUCCESSPayment confirmed by Squad
FAILEDSquad reported a failure or verification failed
REFUNDEDPayment was refunded

​
Payment object

​
id
string
UUID of the payment record.
​
buyer
string
UUID of the BuyerProfile who initiated the payment.
​
order
string
UUID of the associated order.
​
payment_status
string
One of PENDING, SUCCESS, FAILED, REFUNDED.
​
amount
string
Total amount in NGN (decimal string).
​
currency
string
NGN or USD.
​
channel
string
Payment channel used: CARD, USSD, TRANSFER, or VIRTUAL-ACCOUNT.
​
checkout_url
string
Squad-hosted checkout URL. Redirect the buyer here to complete payment.
​
squad_transaction_id
string
Transaction reference assigned by Squad.
​
escrow_enabled
boolean
Whether funds are held in escrow after a successful payment. Defaults to true.
​
created_at
string
ISO 8601 timestamp of payment creation.

Build docs developers (and LLMs) love

Get started for freeTalk to us