{"openapi":"3.1.0","info":{"title":"BolrachPay API","version":"v1","description":"Merchant payments API. Authenticate with a merchant secret key as a bearer token; test and live keys are distinguished by their prefix, so a key cannot be moved between modes by accident. Creating a payment intent or a refund REQUIRES an Idempotency-Key — money movement must survive a retry without happening twice.","contact":{"url":"https://api.bolrachpay.com/api/v1"}},"servers":[{"url":"https://api.bolrachpay.com","description":"Production"}],"tags":[{"name":"payments","description":"Intents, links, refunds, invoices."},{"name":"service","description":"Liveness."}],"paths":{"/api/v1":{"get":{"operationId":"getV1","summary":"This catalogue","tags":["payments"],"security":[],"responses":{"200":{"description":"Success."}}}},"/api/v1/ping":{"get":{"operationId":"getV1Ping","summary":"Liveness","tags":["payments"],"security":[],"responses":{"200":{"description":"Success."}}}},"/api/v1/me":{"get":{"operationId":"getV1Me","tags":["payments"],"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key is not permitted here."}}}},"/api/v1/payments":{"get":{"operationId":"getV1Payments","description":"Requires the payments:read scope.","tags":["payments"],"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:read scope."}}}},"/api/v1/payment_intents":{"post":{"operationId":"postV1PaymentIntents","description":"Requires the payments:write scope.","tags":["payments"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Idempotency key. Replaying the same key returns the original result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","return_url"],"properties":{"amount":{"type":"string","description":"Integer MINOR units as a string: 250000 is NGN 2,500.00. Sent as a string so no JSON parser can round it.","example":"250000"},"currency":{"type":"string","description":"Three-letter ISO code.","example":"NGN"},"return_url":{"type":"string","description":"Absolute https URL the buyer returns to after 3-D Secure.","example":"https://example.com/thanks"},"description":{"type":"string","maxLength":500},"method":{"type":"string","description":"Preferred method; the router still decides what is available."},"buyer_country":{"type":"string","description":"Two-letter country of the buyer, for routing.","example":"NG"},"request_3ds":{"type":"string","enum":["auto","any"],"description":"'any' forces a challenge, for testing the 3-DS path."},"customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}}}}}}}},"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"201":{"description":"Created."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:write scope."},"409":{"description":"A different request already used this Idempotency-Key."}}}},"/api/v1/payment_intents/{id}":{"get":{"operationId":"getV1PaymentIntentsId}","description":"Requires the payments:read scope.","tags":["payments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:read scope."}}}},"/api/v1/payment_links":{"post":{"operationId":"postV1PaymentLinks","description":"Requires the payments:write scope.","tags":["payments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","amount","currency"],"properties":{"name":{"type":"string","maxLength":200,"description":"Labels the link and forms its slug.","example":"August workshop ticket"},"amount":{"type":"string","description":"Integer minor units as a string.","example":"250000"},"currency":{"type":"string","example":"NGN"},"kind":{"type":"string","enum":["one_time","reusable","donation"],"default":"one_time"},"success_url":{"type":"string","description":"Absolute https URL."},"cancel_url":{"type":"string","description":"Absolute https URL."}}}}}},"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"201":{"description":"Created."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:write scope."}}},"get":{"operationId":"getV1PaymentLinks","description":"Requires the payments:read scope.","tags":["payments"],"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:read scope."}}}},"/api/v1/refunds":{"post":{"operationId":"postV1Refunds","description":"Requires the payments:write scope.","tags":["payments"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Idempotency key. Replaying the same key returns the original result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment"],"properties":{"payment":{"type":"string","description":"The payment id to refund.","example":"pay_1a2b3c"},"amount":{"type":"string","description":"Integer minor units. Omit to refund the whole payment."},"reason":{"type":"string","maxLength":200}}}}}},"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"201":{"description":"Created."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:write scope."},"409":{"description":"A different request already used this Idempotency-Key."}}},"get":{"operationId":"getV1Refunds","description":"Requires the payments:read scope.","tags":["payments"],"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:read scope."}}}},"/api/v1/refunds/{id}":{"get":{"operationId":"getV1RefundsId}","description":"Requires the payments:read scope.","tags":["payments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:read scope."}}}},"/api/v1/invoices":{"post":{"operationId":"postV1Invoices","description":"Requires the payments:write scope.","tags":["payments"],"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"201":{"description":"Created."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:write scope."}}},"get":{"operationId":"getV1Invoices","description":"Requires the payments:read scope.","tags":["payments"],"security":[{"merchantKey":[]}],"responses":{"200":{"description":"Success."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Key lacks the payments:read scope."}}}},"/api/health":{"get":{"operationId":"getHealth","summary":"Service health + DB","tags":["service"],"security":[],"responses":{"200":{"description":"Success."}}}}},"components":{"securitySchemes":{"merchantKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer sk_test_... or sk_live_.... Scopes: payments:read, payments:write, *."}}}}