Payouts

v1.0.3Sandbox ready

Pay customers, agents and suppliers from your float. Payouts are asynchronous: you get an id immediately and the result on your callback URL.

New in 1.0.3Bank payouts now return the receiving bank's reference in the callback.

DownloadOpenAPI (JSON)OpenAPI (YAML)Postman collection Generated clients

Authentication

Swap your keys for a token

Send your app's consumer key and secret to the token endpoint using HTTP Basic auth. You get a bearer token that lasts one hour. Send it in the Authorization header of every call.

Sandbox base URL https://devportal.softwaregroup.com/api/sandbox

Get keys for Treasury

curl -X POST 'https://devportal.softwaregroup.com/api/sandbox/oauth/v1/token' \
  -u "$LANGO_KEY:$LANGO_SECRET" \
  -d 'grant_type=client_credentials'

Result by callbackMoves money

Send a payout

POST/payouts/v1/send

Moves money out of your float. Each reference can be used once.

Request body

amountintegerrequired: Whole currency units. In the sandbox, 1 triggers the low-float scenario.min 10
currencystringrequired: KES · TZS · UGX
destinationobjectrequired
typestringrequired: mobile · bank
phoneNumberstring: Required when type is mobile.
bankCodestring: Required when type is bank.
accountNumberstring: Required when type is bank.
referencestringrequired: Unique per payout. Reusing one returns 409.max length 32
reasonstring: Salary · Supplier · Refund · Commission · Other
callbackUrlurirequired

Responses

202Payout queued.Fields

202 body

payoutIdstring
statusstring: QUEUED

409The reference was already used.Fields

409 body

errorstring
messagestring
requestIdstring

Sandbox scenarios

Payout succeedsdefault

202 + callback

Float too lowamount = 1

202 + callback

Duplicate referencereference = "DUPLICATE"

409

curl -X POST 'https://devportal.softwaregroup.com/api/sandbox/payouts/v1/send' \
  -H "Authorization: Bearer $LANGO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "KES",
    "destination": {
      "type": "mobile",
      "phoneNumber": "254712345678"
    },
    "reference": "PAYRUN-0917-044",
    "reason": "Salary",
    "callbackUrl": "https://example.com/hooks/lango"
  }'

Try it in the sandboxno keys needed

POST/payouts/v1/send

{
  "amount": 25000,
  "currency": "KES",
  "destination": {
    "type": "mobile",
    "phoneNumber": "254712345678"
  },
  "reference": "PAYRUN-0917-044",
  "reason": "Salary",
  "callbackUrl": "https://example.com/hooks/lango"
}

Choose what happens

Check a payout

GET/payouts/v1/{payoutId}

Path parameters

payoutIdstringrequired

Responses

200Current state of the payout.Fields

200 body

payoutIdstring
statusstring: QUEUED · DELIVERED · FAILED
amountinteger
receiptstring

Sandbox scenarios

Delivereddefault

200

curl -X GET 'https://devportal.softwaregroup.com/api/sandbox/payouts/v1/pay_3n7c2q8d' \
  -H "Authorization: Bearer $LANGO_TOKEN"

Try it in the sandboxno keys needed

GET/payouts/v1/pay_3n7c2q8d

Choose what happens