{"openapi":"3.1.0","info":{"title":"Yusr API","version":"1.0.0","description":"Accept bank-transfer payments in Nigeria with dynamic virtual accounts. All amounts are integers in kobo (₦1 = 100 kobo). Authenticate with `Authorization: Bearer sk_test_…` or `sk_live_…`.","contact":{"email":"support@yusr.ng"}},"servers":[{"url":"https://api.yusr.ng/v1","description":"Test and live (the key decides the mode)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Transactions"},{"name":"Sandbox"},{"name":"Settlements"},{"name":"Balance"},{"name":"Webhook endpoints"},{"name":"Events"},{"name":"Banks"}],"paths":{"/transactions":{"post":{"tags":["Transactions"],"operationId":"createTransaction","summary":"Create a transaction","description":"Issues a one-time account number for the payer to transfer the exact `payment.amount` to before `payment.expires_at`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key (≤ 255 chars). Retrying with the same key and body within 24 h returns the original response.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"maximum":100000000000,"description":"Amount in kobo. ₦25,000.00 is 2500000."},"currency":{"default":"NGN","type":"string","const":"NGN"},"reference":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._\\-:/]+$","description":"Your unique reference for this payment."},"description":{"type":"string","maxLength":200},"customer":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":200,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","pattern":"^\\+?[0-9]{7,15}$"}},"required":["name","email"]},"expires_in":{"default":1800,"description":"Seconds until the account expires. Default 1800 (30 minutes).","type":"integer","minimum":600,"maximum":259200},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"required":["amount","reference","customer"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (duplicate reference, idempotency conflict, invalid state)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Amount out of range or limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error — retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Processing error — the payment account could not be issued; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable — retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Transactions"],"operationId":"listTransactions","summary":"List transactions","parameters":[{"name":"reference","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","paid","underpaid","overpaid","expired","late_payment","reversed","failed","cancelled"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","description":"Cursor: the `next_cursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of transactions","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Yusr transaction ID, prefixed txn_."},"object":{"type":"string","const":"transaction"},"mode":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["pending","paid","underpaid","overpaid","expired","late_payment","reversed","failed","cancelled"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount requested, in kobo."},"amount_received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sum of all payments received, in kobo."},"fee":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Yusr fee in kobo."},"fee_bearer":{"type":"string","enum":["merchant","customer"]},"net_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount settled to you after fees, in kobo."},"currency":{"type":"string","const":"NGN"},"reference":{"type":"string"},"description":{"type":["string","null"]},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":["string","null"]}},"required":["name","email","phone"],"additionalProperties":false},"payment":{"type":"object","properties":{"account_number":{"type":"string"},"bank_name":{"type":"string"},"account_name":{"type":"string"},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Exact amount the payer must transfer, in kobo."},"expires_at":{"type":"string"}},"required":["account_number","bank_name","account_name","amount","expires_at"],"additionalProperties":false},"flags":{"type":"object","properties":{"overpaid":{"type":"boolean"},"underpaid":{"type":"boolean"},"late":{"type":"boolean"}},"required":["overpaid","underpaid","late"],"additionalProperties":false},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"payer_name":{"type":["string","null"]},"payer_bank":{"type":["string","null"]},"payer_account_number":{"description":"Masked, last 4 digits only.","type":["string","null"]},"received_at":{"type":"string"}},"required":["id","amount","payer_name","payer_bank","payer_account_number","received_at"],"additionalProperties":false}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"paid_at":{"type":["string","null"]},"expires_at":{"type":"string"}},"required":["id","object","mode","status","amount","amount_received","fee","fee_bearer","net_amount","currency","reference","description","customer","payment","flags","payments","metadata","created_at","updated_at","paid_at","expires_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions/{id}":{"get":{"tags":["Transactions"],"operationId":"getTransaction","summary":"Retrieve a transaction","description":"Use for polling when a webhook is late. Poll at most once per second per transaction; 5 seconds is recommended.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"responses":{"200":{"description":"The transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions/{id}/cancel":{"post":{"tags":["Transactions"],"operationId":"cancelTransaction","summary":"Cancel a pending transaction","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key (≤ 255 chars). Retrying with the same key and body within 24 h returns the original response.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (duplicate reference, idempotency conflict, invalid state)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions/{id}/client-token":{"post":{"tags":["Transactions"],"operationId":"createClientToken","summary":"Create a browser client token","description":"Short-lived (30 min), read-only token scoped to one transaction, for subscribing a browser to realtime updates without exposing your secret key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"responses":{"201":{"description":"Token","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"object":{"type":"string","const":"client_token"},"token":{"type":"string"},"transaction":{"type":"string"},"expires_at":{"type":"string"}},"required":["object","token","transaction","expires_at"],"additionalProperties":false}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sandbox/transactions/{id}/simulate":{"post":{"tags":["Sandbox"],"operationId":"simulatePayment","summary":"Simulate a payment outcome (test mode only)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"outcome":{"type":"string","enum":["paid","underpaid","overpaid","late","expired"]},"amount":{"description":"Amount the simulated payer transfers. Defaults depend on outcome.","type":"integer","exclusiveMinimum":0,"maximum":100000000000},"payer_name":{"type":"string","maxLength":100}},"required":["outcome"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (duplicate reference, idempotency conflict, invalid state)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settlements":{"get":{"tags":["Settlements"],"operationId":"listSettlements","summary":"List settlements","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","description":"Cursor: the `next_cursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of settlements","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"settlement"},"mode":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["pending","processing","completed","failed","on_hold"]},"currency":{"type":"string","const":"NGN"},"period_start":{"type":"string"},"period_end":{"type":"string"},"gross":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fees":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"net":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"transaction_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bank_account":{"anyOf":[{"type":"object","properties":{"bank_name":{"type":"string"},"account_number":{"type":"string","description":"Masked"},"account_name":{"type":"string"}},"required":["bank_name","account_number","account_name"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"amount_received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"net_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","reference","amount_received","fee","net_amount"],"additionalProperties":false}}},"required":["id","object","mode","status","currency","period_start","period_end","gross","fees","net","transaction_count","bank_account","created_at","completed_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settlements/{id}":{"get":{"tags":["Settlements"],"operationId":"getSettlement","summary":"Retrieve a settlement with its transactions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"stl_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"responses":{"200":{"description":"The settlement","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settlement"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"tags":["Balance"],"operationId":"getBalance","summary":"Retrieve balances","responses":{"200":{"description":"Balances","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"object":{"type":"string","const":"balance"},"mode":{"type":"string","enum":["test","live"]},"currency":{"type":"string","const":"NGN"},"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Collected, not yet available for settlement."},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Ready for the next settlement."},"settled":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total paid out to your bank to date."}},"required":["object","mode","currency","pending","available","settled"],"additionalProperties":false}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/banks":{"get":{"tags":["Banks"],"operationId":"listBanks","summary":"List Nigerian banks","responses":{"200":{"description":"Banks","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"tags":["Webhook endpoints"],"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"webhook_endpoint"},"mode":{"type":"string","enum":["test","live"]},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["transaction.paid","transaction.underpaid","transaction.overpaid","transaction.expired","transaction.late_payment","transaction.reversed","transaction.cancelled","settlement.completed"]}},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"secret":{"description":"Signing secret. Returned only on create.","type":"string"},"disabled_reason":{"description":"Why the endpoint was disabled automatically, if it was.","type":["string","null"]},"failing_since":{"description":"When deliveries started failing continuously; null when healthy.","type":["string","null"]},"created_at":{"type":"string"}},"required":["id","object","mode","url","events","description","enabled","disabled_reason","failing_since","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Webhook endpoints"],"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint","description":"The response includes the signing `secret` once. Live endpoints must use HTTPS and resolve to a public IP.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key (≤ 255 chars). Retrying with the same key and body within 24 h returns the original response.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"events":{"default":["transaction.paid","transaction.underpaid","transaction.overpaid","transaction.expired","transaction.late_payment","transaction.reversed","transaction.cancelled","settlement.completed"],"minItems":1,"type":"array","items":{"type":"string","enum":["transaction.paid","transaction.underpaid","transaction.overpaid","transaction.expired","transaction.late_payment","transaction.reversed","transaction.cancelled","settlement.completed"]}},"description":{"type":"string","maxLength":200},"enabled":{"default":true,"type":"boolean"}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"get":{"tags":["Webhook endpoints"],"operationId":"getWebhookEndpoint","summary":"Retrieve a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"whk_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"responses":{"200":{"description":"Endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Webhook endpoints"],"operationId":"updateWebhookEndpoint","summary":"Update a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"whk_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["transaction.paid","transaction.underpaid","transaction.overpaid","transaction.expired","transaction.late_payment","transaction.reversed","transaction.cancelled","settlement.completed"]}},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"enabled":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Webhook endpoints"],"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"whk_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["id","object","deleted"],"properties":{"id":{"type":"string"},"object":{"const":"webhook_endpoint"},"deleted":{"const":true}}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"tags":["Webhook endpoints"],"operationId":"testWebhookEndpoint","summary":"Send a signed sample event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"whk_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"responses":{"200":{"description":"The delivery attempt, with the response your endpoint returned","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"webhook_delivery"},"event_id":{"type":"string"},"event_type":{"type":["string","null"]},"endpoint_id":{"type":"string"},"url":{"type":"string"},"attempt":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","succeeded","failed"]},"status_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"latency_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"response_body":{"type":["string","null"]},"error":{"type":["string","null"]},"next_retry_at":{"type":["string","null"]},"delivered_at":{"type":["string","null"]},"is_test":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","event_id","event_type","endpoint_id","url","attempt","status","status_code","latency_ms","response_body","error","next_retry_at","delivered_at","is_test","created_at","updated_at"],"additionalProperties":false}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/roll-secret":{"post":{"tags":["Webhook endpoints"],"operationId":"rollWebhookSecret","summary":"Roll the signing secret","description":"During the overlap (default 24 h, max 72 h) every delivery carries two signatures — one per secret — so you can deploy the new secret without dropping events.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"whk_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"overlap_hours":{"type":"integer","minimum":0,"maximum":72,"default":24}}}}}},"responses":{"200":{"description":"New secret","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"object":{"type":"string","const":"webhook_secret"},"secret":{"type":"string","description":"The new signing secret. Shown once."},"previous_secret_expires_at":{"description":"Until this time deliveries are signed with both the new and the previous secret.","type":["string","null"]}},"required":["object","secret","previous_secret_expires_at"],"additionalProperties":false}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"List events","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["transaction.paid","transaction.underpaid","transaction.overpaid","transaction.expired","transaction.late_payment","transaction.reversed","transaction.cancelled","settlement.completed"]}},{"name":"transaction","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","description":"Cursor: the `next_cursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of events","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"event"},"type":{"type":"string","enum":["transaction.paid","transaction.underpaid","transaction.overpaid","transaction.expired","transaction.late_payment","transaction.reversed","transaction.cancelled","settlement.completed"]},"mode":{"type":"string","enum":["test","live"]},"created_at":{"type":"string"},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","object","type","mode","created_at","data"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}":{"get":{"tags":["Events"],"operationId":"getEvent","summary":"Retrieve an event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"evt_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"responses":{"200":{"description":"Event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}/resend":{"post":{"tags":["Events"],"operationId":"resendEvent","summary":"Resend an event to your webhook endpoints","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"evt_01JA9Q3K7M2V8X4N6P0R2T5W7Y"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","required":["object","queued"],"properties":{"object":{"const":"resend"},"queued":{"type":"integer","description":"Number of deliveries queued"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"transaction.paid":{"post":{"summary":"transaction.paid","description":"Signed with `X-Yusr-Signature: v1=<hex HMAC-SHA256(secret, \"<X-Yusr-Timestamp>.<raw body>\")>`. Respond 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"transaction.underpaid":{"post":{"summary":"transaction.underpaid","description":"Signed with `X-Yusr-Signature: v1=<hex HMAC-SHA256(secret, \"<X-Yusr-Timestamp>.<raw body>\")>`. Respond 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"transaction.overpaid":{"post":{"summary":"transaction.overpaid","description":"Signed with `X-Yusr-Signature: v1=<hex HMAC-SHA256(secret, \"<X-Yusr-Timestamp>.<raw body>\")>`. Respond 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"transaction.expired":{"post":{"summary":"transaction.expired","description":"Signed with `X-Yusr-Signature: v1=<hex HMAC-SHA256(secret, \"<X-Yusr-Timestamp>.<raw body>\")>`. Respond 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"transaction.late_payment":{"post":{"summary":"transaction.late_payment","description":"Signed with `X-Yusr-Signature: v1=<hex HMAC-SHA256(secret, \"<X-Yusr-Timestamp>.<raw body>\")>`. Respond 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"transaction.reversed":{"post":{"summary":"transaction.reversed","description":"Signed with `X-Yusr-Signature: v1=<hex HMAC-SHA256(secret, \"<X-Yusr-Timestamp>.<raw body>\")>`. Respond 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"transaction.cancelled":{"post":{"summary":"transaction.cancelled","description":"Signed with `X-Yusr-Signature: v1=<hex HMAC-SHA256(secret, \"<X-Yusr-Timestamp>.<raw body>\")>`. Respond 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"settlement.completed":{"post":{"summary":"settlement.completed","description":"Signed with `X-Yusr-Signature: v1=<hex HMAC-SHA256(secret, \"<X-Yusr-Timestamp>.<raw body>\")>`. Respond 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Acknowledged"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Secret key: sk_test_… or sk_live_…"}},"schemas":{"Transaction":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Yusr transaction ID, prefixed txn_."},"object":{"type":"string","const":"transaction"},"mode":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["pending","paid","underpaid","overpaid","expired","late_payment","reversed","failed","cancelled"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount requested, in kobo."},"amount_received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sum of all payments received, in kobo."},"fee":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Yusr fee in kobo."},"fee_bearer":{"type":"string","enum":["merchant","customer"]},"net_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount settled to you after fees, in kobo."},"currency":{"type":"string","const":"NGN"},"reference":{"type":"string"},"description":{"type":["string","null"]},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":["string","null"]}},"required":["name","email","phone"],"additionalProperties":false},"payment":{"type":"object","properties":{"account_number":{"type":"string"},"bank_name":{"type":"string"},"account_name":{"type":"string"},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Exact amount the payer must transfer, in kobo."},"expires_at":{"type":"string"}},"required":["account_number","bank_name","account_name","amount","expires_at"],"additionalProperties":false},"flags":{"type":"object","properties":{"overpaid":{"type":"boolean"},"underpaid":{"type":"boolean"},"late":{"type":"boolean"}},"required":["overpaid","underpaid","late"],"additionalProperties":false},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"payer_name":{"type":["string","null"]},"payer_bank":{"type":["string","null"]},"payer_account_number":{"description":"Masked, last 4 digits only.","type":["string","null"]},"received_at":{"type":"string"}},"required":["id","amount","payer_name","payer_bank","payer_account_number","received_at"],"additionalProperties":false}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"paid_at":{"type":["string","null"]},"expires_at":{"type":"string"}},"required":["id","object","mode","status","amount","amount_received","fee","fee_bearer","net_amount","currency","reference","description","customer","payment","flags","payments","metadata","created_at","updated_at","paid_at","expires_at"],"additionalProperties":false},"Settlement":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"settlement"},"mode":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["pending","processing","completed","failed","on_hold"]},"currency":{"type":"string","const":"NGN"},"period_start":{"type":"string"},"period_end":{"type":"string"},"gross":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fees":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"net":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"transaction_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bank_account":{"anyOf":[{"type":"object","properties":{"bank_name":{"type":"string"},"account_number":{"type":"string","description":"Masked"},"account_name":{"type":"string"}},"required":["bank_name","account_number","account_name"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"amount_received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"net_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","reference","amount_received","fee","net_amount"],"additionalProperties":false}}},"required":["id","object","mode","status","currency","period_start","period_end","gross","fees","net","transaction_count","bank_account","created_at","completed_at"],"additionalProperties":false},"WebhookEndpoint":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"webhook_endpoint"},"mode":{"type":"string","enum":["test","live"]},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["transaction.paid","transaction.underpaid","transaction.overpaid","transaction.expired","transaction.late_payment","transaction.reversed","transaction.cancelled","settlement.completed"]}},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"secret":{"description":"Signing secret. Returned only on create.","type":"string"},"disabled_reason":{"description":"Why the endpoint was disabled automatically, if it was.","type":["string","null"]},"failing_since":{"description":"When deliveries started failing continuously; null when healthy.","type":["string","null"]},"created_at":{"type":"string"}},"required":["id","object","mode","url","events","description","enabled","disabled_reason","failing_since","created_at"],"additionalProperties":false},"Event":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"event"},"type":{"type":"string","enum":["transaction.paid","transaction.underpaid","transaction.overpaid","transaction.expired","transaction.late_payment","transaction.reversed","transaction.cancelled","settlement.completed"]},"mode":{"type":"string","enum":["test","live"]},"created_at":{"type":"string"},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","object","type","mode","created_at","data"],"additionalProperties":false},"Error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","authentication_failed","permission_denied","sandbox_only","merchant_not_live","merchant_suspended","email_not_verified","account_locked","invalid_credentials","invalid_code","invalid_token","csrf_failed","ip_not_allowed","not_found","duplicate_reference","idempotency_conflict","idempotency_in_progress","invalid_state","amount_out_of_range","limit_exceeded","rate_limited","processing_error","service_unavailable","internal_error"]},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}