{"openapi":"3.0.3","info":{"title":"Collect","version":"1.2.0","summary":"Ask a customer to pay from their phone.","description":"Send a payment prompt to a customer's phone. The customer approves with their PIN and you receive the result on your callback URL."},"x-lango":{"slug":"collect","auth":"oauth2_client_credentials","changelog":"Added `description` to the push request and the DUPLICATE_REFERENCE error."},"paths":{"/collect/v1/push":{"post":{"operationId":"createPush","summary":"Send a payment prompt","description":"Starts a payment. The response only confirms the prompt was sent. The final result arrives on `callbackUrl` a few seconds later.","x-lango":{"destructive":true,"async":true},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushRequest"},"example":{"shortCode":"600100","amount":1500,"currency":"KES","phoneNumber":"254712345678","reference":"INV-2041","description":"Order 2041","callbackUrl":"https://example.com/hooks/lango"}}}},"responses":{"202":{"description":"Prompt sent to the customer's phone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushAccepted"}}}},"400":{"description":"The request failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-sandbox-scenarios":[{"key":"paid","title":"Customer pays","default":true,"status":202,"delayMs":120,"response":{"checkoutId":"{{id:chk}}","status":"PENDING","customerMessage":"Enter your PIN on your phone to pay KES {{body.amount}}."},"callback":{"delayMs":4000,"body":{"checkoutId":"{{checkoutId}}","reference":"{{body.reference}}","resultCode":0,"resultDescription":"Payment received.","amount":"{{body.amount}}","receipt":"{{id:RCT}}","phoneNumber":"{{body.phoneNumber}}","paidAt":"{{now}}"}}},{"key":"insufficient_funds","title":"Insufficient funds","match":{"field":"body.amount","equals":1},"status":202,"delayMs":120,"response":{"checkoutId":"{{id:chk}}","status":"PENDING","customerMessage":"Enter your PIN on your phone to pay KES {{body.amount}}."},"callback":{"delayMs":3000,"body":{"checkoutId":"{{checkoutId}}","reference":"{{body.reference}}","resultCode":1001,"resultDescription":"The customer has insufficient funds."}}},{"key":"cancelled","title":"Customer cancels the prompt","match":{"field":"body.amount","equals":2},"status":202,"delayMs":120,"response":{"checkoutId":"{{id:chk}}","status":"PENDING","customerMessage":"Enter your PIN on your phone to pay KES {{body.amount}}."},"callback":{"delayMs":2500,"body":{"checkoutId":"{{checkoutId}}","reference":"{{body.reference}}","resultCode":1032,"resultDescription":"The customer cancelled the request."}}},{"key":"no_answer","title":"Customer never responds","match":{"field":"body.amount","equals":3},"status":202,"delayMs":120,"response":{"checkoutId":"{{id:chk}}","status":"PENDING","customerMessage":"Enter your PIN on your phone to pay KES {{body.amount}}."},"callback":{"delayMs":9000,"body":{"checkoutId":"{{checkoutId}}","reference":"{{body.reference}}","resultCode":1037,"resultDescription":"The customer did not respond in time."}}},{"key":"invalid_phone","title":"Invalid phone number","match":{"field":"body.phoneNumber","equals":"254700000000"},"status":400,"delayMs":40,"response":{"error":"INVALID_PHONE_NUMBER","message":"phoneNumber must be a reachable mobile number in international format.","requestId":"{{id:req}}"}}]}},"/collect/v1/push/{checkoutId}":{"get":{"operationId":"getPush","summary":"Check a payment prompt","description":"Use this when a callback has not arrived and you need the current state.","parameters":[{"name":"checkoutId","in":"path","required":true,"schema":{"type":"string"},"example":"chk_8f2k1m9x"}],"responses":{"200":{"description":"Current state of the prompt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushStatus"}}}},"404":{"description":"No prompt with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-sandbox-scenarios":[{"key":"completed","title":"Completed","default":true,"status":200,"delayMs":60,"response":{"checkoutId":"{{path.checkoutId}}","status":"COMPLETED","resultCode":0,"amount":1500,"receipt":"{{id:RCT}}"}},{"key":"not_found","title":"Unknown id","match":{"field":"path.checkoutId","equals":"chk_missing"},"status":404,"delayMs":30,"response":{"error":"NOT_FOUND","message":"No payment prompt with that id.","requestId":"{{id:req}}"}}]}}},"components":{"schemas":{"PushRequest":{"type":"object","required":["shortCode","amount","currency","phoneNumber","reference","callbackUrl"],"properties":{"shortCode":{"type":"string","description":"The till or paybill number receiving the money."},"amount":{"type":"integer","minimum":1,"description":"Whole currency units. In the sandbox, 1, 2 and 3 trigger failure scenarios."},"currency":{"type":"string","enum":["KES","TZS","UGX"]},"phoneNumber":{"type":"string","description":"Customer's number in international format, no plus sign."},"reference":{"type":"string","maxLength":24,"description":"Your own reference. Shown to the customer and returned in the callback."},"description":{"type":"string","maxLength":64},"callbackUrl":{"type":"string","format":"uri","description":"Where the final result is posted."}}},"PushAccepted":{"type":"object","properties":{"checkoutId":{"type":"string"},"status":{"type":"string","enum":["PENDING"]},"customerMessage":{"type":"string"}}},"PushStatus":{"type":"object","properties":{"checkoutId":{"type":"string"},"status":{"type":"string","enum":["PENDING","COMPLETED","FAILED"]},"resultCode":{"type":"integer"},"amount":{"type":"integer"},"receipt":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"servers":[{"url":"https://devportal.softwaregroup.com/api/sandbox","description":"Sandbox"},{"url":"https://devportal.softwaregroup.com/api/live","description":"Production"}]}