{"openapi":"3.1.0","info":{"title":"Patronise Dev API","version":"1.0.0","description":"Accept Mobile Money in Central and West Africa. Docs: https://patronise.me/developers/docs","contact":{"email":"dev@patronise.me"}},"servers":[{"url":"https://api.patronise.me/v1"}],"security":[{"bearer":[]}],"paths":{"/payments":{"post":{"operationId":"createPayment","summary":"Create a payment","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Makes the request safe to retry for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentCreate"}}}},"responses":{"201":{"description":"Created (status pending)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listPayments","summary":"List payments","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","succeeded","failed","requires_review"]}},{"name":"reference","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/{id}":{"get":{"operationId":"getPayment","summary":"Retrieve a payment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout-sessions":{"post":{"operationId":"createCheckoutSession","summary":"Create a hosted checkout page","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Makes the request safe to retry for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout-sessions/{id}":{"get":{"operationId":"getCheckoutSession","summary":"Retrieve a checkout session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links":{"post":{"operationId":"createPaymentLink","summary":"Create a payment link","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Makes the request safe to retry for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","currency"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer","description":"Leave out to let the customer choose."},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"fee_bearer":{"type":"string","enum":["merchant","customer"]},"success_url":{"type":"string","format":"uri"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listPaymentLinks","summary":"List payment links","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}},"has_more":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links/{id}":{"get":{"operationId":"getPaymentLink","summary":"Retrieve a payment link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updatePaymentLink","summary":"Turn a payment link on or off","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts":{"post":{"operationId":"createPayout","summary":"Send a payout to a Mobile Money number","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Makes the request safe to retry for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listPayouts","summary":"List payouts","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}},"has_more":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}":{"get":{"operationId":"getPayout","summary":"Retrieve a payout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"operationId":"getBalance","summary":"Balance per currency","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"balance"},"livemode":{"type":"boolean"},"balances":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"available":{"type":"integer"},"pending":{"type":"integer"}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fees/quote":{"get":{"operationId":"quoteFee","summary":"Fee for an amount","parameters":[{"name":"amount","in":"query","required":true,"schema":{"type":"integer","description":"Smallest currency unit (FCFA: whole francs, multiple of 5)."}},{"name":"currency","in":"query","required":true,"schema":{"type":"string","enum":["XAF","XOF","CDF"]}},{"name":"operator","in":"query","required":true,"schema":{"type":"string"}},{"name":"fee_bearer","in":"query","schema":{"type":"string","enum":["merchant","customer"]}},{"name":"direction","in":"query","schema":{"type":"string","enum":["payin","payout"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer"},"charge":{"type":"integer"},"fee":{"type":"integer"},"net":{"type":"integer"},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"fee_bearer":{"type":"string"},"rate":{"type":"object","properties":{"percent":{"type":"number"},"fixed":{"type":"integer"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators":{"get":{"operationId":"listOperators","summary":"Payment methods and fees","parameters":[{"name":"country","in":"query","schema":{"type":"string"}},{"name":"currency","in":"query","schema":{"type":"string","enum":["XAF","XOF","CDF"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Operator"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/predict":{"post":{"operationId":"predictOperator","summary":"Find the operator of a phone number","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string"},"country":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"operator":{"type":"string"},"country":{"type":"string"},"phone":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"operationId":"listEvents","summary":"Recent events","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}":{"get":{"operationId":"getEvent","summary":"Retrieve an event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"event":{"post":{"summary":"Event sent to your endpoint. Verify Patronise-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>.","parameters":[{"name":"Patronise-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Return any 2xx within 10 seconds."}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"sk_test_… / sk_live_… (or pk_ for checkout sessions)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]}}}}},"PaymentCreate":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"Smallest currency unit (FCFA: whole francs, multiple of 5)."},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"operator":{"type":"string","description":"e.g. mtn_cm. Optional for Cameroonian numbers."},"phone":{"type":"string"},"reference":{"type":"string"},"description":{"type":"string"},"fee_bearer":{"type":"string","enum":["merchant","customer"]},"customer_email":{"type":"string"},"customer_name":{"type":"string"},"return_url":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":{"type":["string","number","boolean"]},"maxProperties":20}}},"Payment":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"payment"},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["pending","succeeded","failed","requires_review"]},"amount":{"type":"integer"},"charge":{"type":"integer"},"fee":{"type":"integer"},"net":{"type":"integer"},"fee_bearer":{"type":"string"},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"country":{"type":"string"},"operator":{"type":"string"},"phone":{"type":["string","null"]},"reference":{"type":["string","null"]},"description":{"type":["string","null"]},"customer":{"type":"object","properties":{"email":{"type":["string","null"]},"name":{"type":["string","null"]}}},"metadata":{"type":"object","additionalProperties":{"type":["string","number","boolean"]},"maxProperties":20},"next_action":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["ussd_prompt","redirect"]},"url":{"type":"string"},"ussd":{"type":"string"}}},"failure":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":["string","null"]}}},"checkout_session":{"type":["string","null"]},"payment_link":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"CheckoutSessionCreate":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"Smallest currency unit (FCFA: whole francs, multiple of 5)."},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"description":{"type":"string"},"reference":{"type":"string"},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"fee_bearer":{"type":"string","enum":["merchant","customer"]},"customer_email":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}},"expires_in_minutes":{"type":"integer","minimum":10,"maximum":1440},"metadata":{"type":"object","additionalProperties":{"type":["string","number","boolean"]},"maxProperties":20}}},"CheckoutSession":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"checkout_session"},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["open","complete","expired"]},"url":{"type":"string","format":"uri"},"amount":{"type":"integer"},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"description":{"type":["string","null"]},"reference":{"type":["string","null"]},"fee_bearer":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":["string","number","boolean"]},"maxProperties":20},"success_url":{"type":["string","null"]},"cancel_url":{"type":["string","null"]},"payment":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"PaymentLink":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"payment_link"},"livemode":{"type":"boolean"},"active":{"type":"boolean"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":["string","null"]},"amount":{"type":["integer","null"]},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"fee_bearer":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"PayoutCreate":{"type":"object","required":["amount","destination"],"properties":{"amount":{"type":"integer","description":"Smallest currency unit (FCFA: whole francs, multiple of 5)."},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"reference":{"type":"string"},"destination":{"type":"object","required":["operator","phone"],"properties":{"operator":{"type":"string"},"phone":{"type":"string"},"account_name":{"type":"string"}}}}},"Payout":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"payout"},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["awaiting_approval","pending","paid","failed","cancelled"]},"amount":{"type":"integer"},"fee":{"type":"integer"},"sent":{"type":"integer"},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"destination":{"type":"object","properties":{"country":{"type":"string"},"operator":{"type":"string"},"phone":{"type":"string"},"account_name":{"type":["string","null"]}}},"reference":{"type":["string","null"]},"failure":{"type":["object","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"Operator":{"type":"object","properties":{"operator":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["momo","card","wallet"]},"country":{"type":"string"},"currency":{"type":"string","enum":["XAF","XOF","CDF"]},"flow":{"type":"string","enum":["ussd_prompt","redirect"]},"min":{"type":"integer"},"max":{"type":"integer"},"fee":{"type":"object","properties":{"percent":{"type":"number"},"fixed":{"type":"integer"},"label":{"type":"string"}}},"payout_fee":{"type":["object","null"]}}},"Event":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"event"},"type":{"type":"string","enum":["payment.succeeded","payment.failed","payment.requires_review","checkout_session.completed","payout.paid","payout.failed","ping"]},"livemode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"object":{"type":"object"}}}}}}}}