{"openapi":"3.1.0","info":{"title":"Deripay API","version":"v2","description":"Mobile money deposits and withdrawals for Deriv accounts. Server-to-server only: never call this API from a browser. Every response is `{success, data}` or `{success:false, error:{code,message,request_id}}`."},"servers":[{"url":"https://deriapi.site/api/v2"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Server API key `dpk_live_…` from the dashboard. `X-API-Key` also works."}},"schemas":{"Error":{"type":"object","properties":{"success":{"const":false},"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","examples":["AUTH_MISSING_API_KEY","AUTH_INVALID_API_KEY","AUTH_INSUFFICIENT_SCOPE","AUTH_IP_NOT_ALLOWED","ACCOUNT_SUSPENDED","RATE_LIMITED","INVALID_REQUEST","IDEMPOTENCY_KEY_REQUIRED","IDEMPOTENCY_KEY_REUSED","DERIV_APP_NOT_REGISTERED","CONNECTION_NOT_FOUND","TRANSACTION_NOT_FOUND","MARKET_NOT_AVAILABLE","INVALID_PHONE_NUMBER","OPERATOR_REQUIRED","AMOUNT_OUT_OF_RANGE","DEPOSITS_PAUSED","UPSTREAM_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}}}}},"Market":{"type":"object","properties":{"country":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"dialing_code":{"type":"string"},"national_number_length":{"type":"integer"},"deposit_limits":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"operators":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}},"requires_operator":{"type":"boolean"}}},"Markets":{"type":"object","properties":{"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}}},"Rates":{"type":"object","properties":{"country":{"type":"string"},"currency":{"type":"string"},"deposit_rate":{"type":"number","description":"Local units the customer pays per USD credited."},"withdraw_rate":{"type":"number","description":"Local units the customer receives per USD withdrawn."},"deposits_available":{"type":"boolean"},"deposit_limits":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"withdraw_limits_usd":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"effective_date":{"type":"string"},"fetched_at":{"type":"string"}}},"Connection":{"type":"object","properties":{"id":{"type":"string","examples":["con_6720f1a2b3c4d5e6f7a8"]},"object":{"const":"connection"},"client_id":{"type":"string"},"external_customer_id":{"type":["string","null"]},"deriv_login_id":{"type":["string","null"]},"accounts":{"type":"array","items":{"type":"object","properties":{"login_id":{"type":"string"},"currency":{"type":"string"},"is_virtual":{"type":"boolean"}}}},"authorization_status":{"type":"string"},"default_phone_number":{"type":["string","null"]},"created_at":{"type":"string"},"last_authorized_at":{"type":["string","null"]}}},"ConnectionList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"Balance":{"type":"object","properties":{"connection_id":{"type":"string"},"login_id":{"type":["string","null"]},"balance":{"type":"number"},"currency":{"type":"string"}}},"Transaction":{"type":"object","properties":{"id":{"type":"string","examples":["txn_6720f9e8d7c6b5a4f3e2"]},"object":{"const":"transaction"},"type":{"enum":["deposit","withdrawal"]},"state":{"enum":["pending","action_required","awaiting_code","processing","completed","failed"]},"status":{"type":"string","description":"Raw Deripay status, e.g. DEPOSIT_STK_PENDING."},"status_message":{"type":["string","null"]},"connection_id":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"operator":{"type":["string","null"]},"amount":{"type":["integer","null"],"description":"Local currency, whole units."},"amount_usd":{"type":["number","null"]},"phone_number":{"type":["string","null"],"description":"Masked."},"customer_action":{"type":["object","null"],"properties":{"step":{"enum":["otp","redirect","ussd"]},"redirect_url":{"type":["string","null"]},"instructions":{"type":"array","items":{"type":"string"}}}},"terminal":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"TransactionList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"Ping":{"type":"object","properties":{"ok":{"type":"boolean"},"developer_id":{"type":"string"},"key_prefix":{"type":"string"},"api_version":{"type":"string"},"deripay_reachable":{"type":"boolean"},"time":{"type":"string"}}},"WebhookEvent":{"type":"object","description":"Body POSTed to your endpoint. Verify `Deripay-Signature: t=<unix>,v1=<hex>` = HMAC-SHA256(secret, `${t}.${raw body}`).","properties":{"id":{"type":"string"},"type":{"enum":["transaction.updated","transaction.action_required","transaction.completed","transaction.failed"]},"created_at":{"type":"string"},"data":{"$ref":"#/components/schemas/Transaction"}}}}},"paths":{"/ping":{"get":{"summary":"Check a key and Deripay reachability","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Ping"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/markets":{"get":{"summary":"List open markets","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Markets"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rates":{"get":{"summary":"Rates and limits for one market","security":[{"bearer":[]}],"parameters":[{"name":"country","in":"query","required":false,"schema":{"description":"Market country code from GET /api/v2/markets (KE, TZ, UG). Defaults to KE.","type":"string","pattern":"^[A-Za-z]{2}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Rates"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections":{"post":{"summary":"Connect a customer with their Deriv access token","security":[{"bearer":[]}],"x-scope":"connections","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"client_id":{"type":"string","minLength":6,"maxLength":64,"description":"Your Deriv OAuth client ID, registered under Deriv apps."},"deriv_access_token":{"type":"string","minLength":10,"maxLength":4000,"description":"Access token from Deriv OAuth (PKCE), or the customer's personal access token, with scopes `trade account_manage payment`."},"token_expires_in":{"description":"Seconds until the token expires, from Deriv.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"external_customer_id":{"description":"Your own id for this customer, so you can look the connection up later.","type":"string","minLength":1,"maxLength":128},"preferred_account_id":{"type":"string","minLength":2,"maxLength":32,"description":"Deriv account to credit or debit (e.g. CR123456). Defaults to the connection's selected account."}},"required":["client_id","deriv_access_token"]}}}},"responses":{"201":{"description":"Created or refreshed","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Connection"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List connections","security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"external_customer_id","in":"query","required":false,"schema":{"type":"string","maxLength":128}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","format":"starts_with","pattern":"^con_.*"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/ConnectionList"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{id}":{"get":{"summary":"Get a connection","security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^con_"}},{"name":"refresh","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Connection"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{id}/balance":{"get":{"summary":"Deriv balance for a connection","security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^con_"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Balance"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{id}/default-phone":{"patch":{"summary":"Save the customer's default mobile number","security":[{"bearer":[]}],"x-scope":"connections","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^con_"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"phone_number":{"type":"string","minLength":6,"maxLength":20,"description":"Customer mobile money number, local (0712…) or international (254712…) format."}},"required":["phone_number"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Connection"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deposits":{"post":{"summary":"Start a deposit","security":[{"bearer":[]}],"x-scope":"deposits","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8-120 characters of letters, digits, `.`, `_`, `:` or `-`. Reuse it to retry safely.","schema":{"type":"string","minLength":8,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"connection_id":{"type":"string","format":"starts_with","pattern":"^con_.*","description":"Connection id from POST /api/v2/connections."},"country":{"description":"Market country code from GET /api/v2/markets (KE, TZ, UG). Defaults to KE.","type":"string","pattern":"^[A-Za-z]{2}$"},"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Amount the customer pays, in whole units of the market currency (KES, TZS, UGX)."},"phone_number":{"type":"string","minLength":6,"maxLength":20,"description":"Customer mobile money number, local (0712…) or international (254712…) format."},"operator":{"type":"string","minLength":2,"maxLength":32,"description":"Mobile money operator code from the market's `operators`. Required where the market lists more than one."},"account_login_id":{"type":"string","minLength":2,"maxLength":32,"description":"Deriv account to credit or debit (e.g. CR123456). Defaults to the connection's selected account."},"idempotency_key":{"description":"Alternative to the Idempotency-Key header.","type":"string"}},"required":["connection_id","amount","phone_number"]}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deposits/{id}/otp":{"post":{"summary":"Submit the customer's operator code","security":[{"bearer":[]}],"x-scope":"deposits","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^txn_"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"otp":{"type":"string","minLength":3,"maxLength":12,"description":"Code the customer received from their operator."}},"required":["otp"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/withdrawals":{"post":{"summary":"Start a withdrawal (Deriv emails the customer a code)","security":[{"bearer":[]}],"x-scope":"withdrawals","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8-120 characters of letters, digits, `.`, `_`, `:` or `-`. Reuse it to retry safely.","schema":{"type":"string","minLength":8,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"connection_id":{"type":"string","format":"starts_with","pattern":"^con_.*"},"country":{"description":"Market country code from GET /api/v2/markets (KE, TZ, UG). Defaults to KE.","type":"string","pattern":"^[A-Za-z]{2}$"},"amount_usd":{"type":"number","exclusiveMinimum":0,"multipleOf":0.01,"description":"Amount to take from the Deriv account, in USD."},"phone_number":{"type":"string","minLength":6,"maxLength":20,"description":"Customer mobile money number, local (0712…) or international (254712…) format."},"operator":{"type":"string","minLength":2,"maxLength":32,"description":"Mobile money operator code from the market's `operators`. Required where the market lists more than one."},"account_login_id":{"type":"string","minLength":2,"maxLength":32,"description":"Deriv account to credit or debit (e.g. CR123456). Defaults to the connection's selected account."},"idempotency_key":{"description":"Alternative to the Idempotency-Key header.","type":"string"}},"required":["connection_id","amount_usd","phone_number"]}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/withdrawals/{id}/resend":{"post":{"summary":"Resend the Deriv email code","security":[{"bearer":[]}],"x-scope":"withdrawals","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^txn_"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/withdrawals/{id}/confirm":{"post":{"summary":"Confirm with the customer's code","security":[{"bearer":[]}],"x-scope":"withdrawals","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^txn_"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"verification_code":{"type":"string","minLength":4,"maxLength":64,"description":"Code Deriv emailed to the customer after POST /api/v2/withdrawals."}},"required":["verification_code"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions":{"get":{"summary":"List transactions","security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"connection_id","in":"query","required":false,"schema":{"type":"string","format":"starts_with","pattern":"^con_.*"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["deposit","withdrawal"]}},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["pending","action_required","awaiting_code","processing","completed","failed"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","format":"starts_with","pattern":"^txn_.*"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/TransactionList"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions/{id}":{"get":{"summary":"Get a transaction (re-checks Deripay)","security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^txn_"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions/{id}/events":{"get":{"summary":"Live status as Server-Sent Events","description":"Events: status, complete, heartbeat, timeout (reconnect), error. Streams close after about 25 seconds.","security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^txn_"}}],"responses":{"200":{"description":"text/event-stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"transaction":{"post":{"summary":"Transaction events sent to your endpoint","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event."}}}}}}