Collect

v1.2.0Sandbox ready

Send a payment prompt to a customer's phone. The customer approves with their PIN and you receive the result on your callback URL.

New in 1.2.0Added description to the push request and the DUPLICATE_REFERENCE error.

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 Payments

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 payment prompt

POST/collect/v1/push

Starts a payment. The response only confirms the prompt was sent. The final result arrives on callbackUrl a few seconds later.

Request body

shortCodestringrequired: The till or paybill number receiving the money.
amountintegerrequired: Whole currency units. In the sandbox, 1, 2 and 3 trigger failure scenarios.min 1
currencystringrequired: KES · TZS · UGX
phoneNumberstringrequired: Customer's number in international format, no plus sign.
referencestringrequired: Your own reference. Shown to the customer and returned in the callback.max length 24
descriptionstring: max length 64
callbackUrlurirequired: Where the final result is posted.

Responses

202Prompt sent to the customer's phone.Fields

202 body

checkoutIdstring
statusstring: PENDING
customerMessagestring

400The request failed validation.Fields

400 body

errorstring
messagestring
requestIdstring

Sandbox scenarios

Customer paysdefault

202 + callback

Insufficient fundsamount = 1

202 + callback

Customer cancels the promptamount = 2

202 + callback

Customer never respondsamount = 3

202 + callback

Invalid phone numberphoneNumber = "254700000000"

400

curl -X POST 'https://devportal.softwaregroup.com/api/sandbox/collect/v1/push' \
  -H "Authorization: Bearer $LANGO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shortCode": "600100",
    "amount": 1500,
    "currency": "KES",
    "phoneNumber": "254712345678",
    "reference": "INV-2041",
    "description": "Order 2041",
    "callbackUrl": "https://example.com/hooks/lango"
  }'

Try it in the sandboxno keys needed

POST/collect/v1/push

{
  "shortCode": "600100",
  "amount": 1500,
  "currency": "KES",
  "phoneNumber": "254712345678",
  "reference": "INV-2041",
  "description": "Order 2041",
  "callbackUrl": "https://example.com/hooks/lango"
}

Choose what happens

Check a payment prompt

GET/collect/v1/push/{checkoutId}

Use this when a callback has not arrived and you need the current state.

Path parameters

checkoutIdstringrequired

Responses

200Current state of the prompt.Fields

200 body

checkoutIdstring
statusstring: PENDING · COMPLETED · FAILED
resultCodeinteger
amountinteger
receiptstring

404No prompt with that id.Fields

404 body

errorstring
messagestring
requestIdstring

Sandbox scenarios

Completeddefault

200

Unknown idcheckoutId = "chk_missing"

404

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

Try it in the sandboxno keys needed

GET/collect/v1/push/chk_8f2k1m9x

Choose what happens