{"openapi":"3.0.3","info":{"title":"Payouts","version":"1.0.3","summary":"Send money to a phone number or bank account.","description":"Pay customers, agents and suppliers from your float. Payouts are asynchronous: you get an id immediately and the result on your callback URL."},"x-lango":{"slug":"payouts","auth":"oauth2_client_credentials","changelog":"Bank payouts now return the receiving bank's reference in the callback."},"paths":{"/payouts/v1/send":{"post":{"operationId":"sendPayout","summary":"Send a payout","description":"Moves money out of your float. Each `reference` can be used once.","x-lango":{"destructive":true,"async":true},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutRequest"},"example":{"amount":25000,"currency":"KES","destination":{"type":"mobile","phoneNumber":"254712345678"},"reference":"PAYRUN-0917-044","reason":"Salary","callbackUrl":"https://example.com/hooks/lango"}}}},"responses":{"202":{"description":"Payout queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutAccepted"}}}},"409":{"description":"The reference was already used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-sandbox-scenarios":[{"key":"sent","title":"Payout succeeds","default":true,"status":202,"delayMs":150,"response":{"payoutId":"{{id:pay}}","status":"QUEUED"},"callback":{"delayMs":3500,"body":{"payoutId":"{{payoutId}}","reference":"{{body.reference}}","resultCode":0,"resultDescription":"Payout delivered.","amount":"{{body.amount}}","receipt":"{{id:RCT}}","completedAt":"{{now}}"}}},{"key":"float_low","title":"Float too low","match":{"field":"body.amount","equals":1},"status":202,"delayMs":150,"response":{"payoutId":"{{id:pay}}","status":"QUEUED"},"callback":{"delayMs":2000,"body":{"payoutId":"{{payoutId}}","reference":"{{body.reference}}","resultCode":2001,"resultDescription":"Your float balance is too low for this payout."}}},{"key":"duplicate","title":"Duplicate reference","match":{"field":"body.reference","equals":"DUPLICATE"},"status":409,"delayMs":40,"response":{"error":"DUPLICATE_REFERENCE","message":"A payout with this reference already exists.","requestId":"{{id:req}}"}}]}},"/payouts/v1/{payoutId}":{"get":{"operationId":"getPayout","summary":"Check a payout","parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string"},"example":"pay_3n7c2q8d"}],"responses":{"200":{"description":"Current state of the payout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutStatus"}}}}},"x-sandbox-scenarios":[{"key":"delivered","title":"Delivered","default":true,"status":200,"delayMs":60,"response":{"payoutId":"{{path.payoutId}}","status":"DELIVERED","amount":25000,"receipt":"{{id:RCT}}"}}]}}},"components":{"schemas":{"PayoutRequest":{"type":"object","required":["amount","currency","destination","reference","callbackUrl"],"properties":{"amount":{"type":"integer","minimum":10,"description":"Whole currency units. In the sandbox, 1 triggers the low-float scenario."},"currency":{"type":"string","enum":["KES","TZS","UGX"]},"destination":{"$ref":"#/components/schemas/Destination"},"reference":{"type":"string","maxLength":32,"description":"Unique per payout. Reusing one returns 409."},"reason":{"type":"string","enum":["Salary","Supplier","Refund","Commission","Other"]},"callbackUrl":{"type":"string","format":"uri"}}},"Destination":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["mobile","bank"]},"phoneNumber":{"type":"string","description":"Required when type is mobile."},"bankCode":{"type":"string","description":"Required when type is bank."},"accountNumber":{"type":"string","description":"Required when type is bank."}}},"PayoutAccepted":{"type":"object","properties":{"payoutId":{"type":"string"},"status":{"type":"string","enum":["QUEUED"]}}},"PayoutStatus":{"type":"object","properties":{"payoutId":{"type":"string"},"status":{"type":"string","enum":["QUEUED","DELIVERED","FAILED"]},"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"}]}