> For the complete documentation index, see [llms.txt](https://ro-proxy.gitbook.io/integration/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ro-proxy.gitbook.io/integration/payments.md).

# Payments

Top up balance, buy sessions, extend sessions, and inspect payment history.

## List available top-up methods

> Return the set of payment methods currently enabled for top-ups. \*\*Public endpoint.\*\*

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[],"paths":{"/api/payment/method":{"get":{"tags":["Payments"],"summary":"List available top-up methods","description":"Return the set of payment methods currently enabled for top-ups. **Public endpoint.**","responses":{"200":{"description":"Methods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupMethodListEnvelope"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"schemas":{"TopupMethodListEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TopupMethod"}}}},"TopupMethod":{"type":"object","properties":{"method":{"type":"string"},"name":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}
```

## List the caller's payments

> Paginated history of payments (top-ups, purchases, extensions) made by the user.

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"ListUserPaymentEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/ListUserPaymentResponse"}}},"ListUserPaymentResponse":{"type":"object","properties":{"total":{"type":"integer","format":"int64"},"page":{"type":"integer"},"size":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ListUserPaymentItem"}}}},"ListUserPaymentItem":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double"},"pay_amount":{"type":"number","format":"double"},"method":{"type":"string"},"action":{"type":"string","description":"Underlying action attached to this payment (e.g. topup, buy, extend)."},"pay_status":{"type":"string","enum":["pending","paid","failed"]},"action_status":{"type":"string","enum":["pending","done","error"]},"action_error":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment":{"get":{"tags":["Payments"],"summary":"List the caller's payments","description":"Paginated history of payments (top-ups, purchases, extensions) made by the user.","parameters":[{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1}},{"in":"query","name":"size","schema":{"type":"integer","minimum":1,"maximum":120,"default":20}},{"in":"query","name":"order_by","schema":{"type":"string","enum":["created_at","updated_at","amount","pay_amount"]}},{"in":"query","name":"order_dir","schema":{"type":"string","enum":["asc","desc"]}},{"in":"query","name":"pay_status","schema":{"type":"string","enum":["pending","paid","failed"]}},{"in":"query","name":"action_status","schema":{"type":"string","enum":["pending","done","error"]}}],"responses":{"200":{"description":"Payment list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListUserPaymentEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Get the status of a payment

> Inspect the current \`pay\_status\` (payment side) and \`action\_status\`\
> (fulfillment side) of a payment by its numeric ID. Poll this endpoint after\
> creating a crypto/VietQR top-up to detect completion.<br>

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"parameters":{"PaymentId":{"in":"path","name":"id","required":true,"schema":{"type":"integer","minimum":1},"description":"Payment ID."}},"schemas":{"PaymentStatusEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/PaymentStatusResponse"}}},"PaymentStatusResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"pay_status":{"type":"string","enum":["pending","paid","failed"]},"action_status":{"type":"string","enum":["pending","done","error"]},"action_error":{"type":"string","nullable":true}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/{id}/status":{"get":{"tags":["Payments"],"summary":"Get the status of a payment","description":"Inspect the current `pay_status` (payment side) and `action_status`\n(fulfillment side) of a payment by its numeric ID. Poll this endpoint after\ncreating a crypto/VietQR top-up to detect completion.\n","parameters":[{"$ref":"#/components/parameters/PaymentId"}],"responses":{"200":{"description":"Payment status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentStatusEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Top up balance via VietQR bank transfer

> Create a VietQR top-up. The response includes \`payment\_url\` (or \`bank\_id\` +\
> \`account\_no\`) that the user must pay. Poll \`GET /api/payment/{id}/status\`\
> until \`pay\_status = paid\` to detect completion.<br>

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"TopupRequest":{"type":"object","required":["amount","method"],"properties":{"amount":{"type":"number","format":"double","exclusiveMinimum":0},"method":{"type":"string","enum":["vietqr"]}}},"TopupPaymentEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/TopupPaymentResponse"}}},"TopupPaymentResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double"},"payment_url":{"type":"string","description":"URL to redirect the payer to (VietQR)."},"bank_id":{"type":"string"},"account_no":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/topup":{"post":{"tags":["Payments"],"summary":"Top up balance via VietQR bank transfer","description":"Create a VietQR top-up. The response includes `payment_url` (or `bank_id` +\n`account_no`) that the user must pay. Poll `GET /api/payment/{id}/status`\nuntil `pay_status = paid` to detect completion.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupRequest"}}}},"responses":{"200":{"description":"Top-up created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupPaymentEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Top up balance with USDT (TRC-20)

> Create a crypto top-up. Send \`pay\_amount\` USDT to \`wallet\_address\` on the TRON\
> network, then call \`POST /api/payment/verify-crypto\` with the on-chain \`txid\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"TopupCryptoRequest":{"type":"object","required":["amount","method"],"properties":{"amount":{"type":"number","format":"double","minimum":5},"method":{"type":"string","enum":["tron"]}}},"TopupCryptoEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/TopupCryptoResponse"}}},"TopupCryptoResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double","description":"Amount in USD requested."},"pay_amount":{"type":"number","format":"double","description":"Actual USDT amount the payer must send (may differ from amount due to fees)."},"wallet_address":{"type":"string"},"qr_code_url":{"type":"string","description":"URL of a QR code encoding the wallet address."}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/topup-crypto":{"post":{"tags":["Payments"],"summary":"Top up balance with USDT (TRC-20)","description":"Create a crypto top-up. Send `pay_amount` USDT to `wallet_address` on the TRON\nnetwork, then call `POST /api/payment/verify-crypto` with the on-chain `txid`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupCryptoRequest"}}}},"responses":{"200":{"description":"Crypto top-up created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupCryptoEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Verify a crypto payment by on-chain txid

> Submit the TRON transaction ID after sending USDT to the wallet address returned\
> by \`POST /api/payment/topup-crypto\*\`. The platform verifies the on-chain transfer\
> and credits the user's balance (and runs any attached \`buy\`/\`extend\` action).<br>

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"VerifyCryptoPaymentRequest":{"type":"object","required":["code","txid","method"],"properties":{"code":{"type":"string","description":"Payment code returned by topup-crypto."},"txid":{"type":"string","description":"On-chain transaction ID of the USDT transfer."},"method":{"type":"string","enum":["tron"]}}},"EmptyEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/verify-crypto":{"post":{"tags":["Payments"],"summary":"Verify a crypto payment by on-chain txid","description":"Submit the TRON transaction ID after sending USDT to the wallet address returned\nby `POST /api/payment/topup-crypto*`. The platform verifies the on-chain transfer\nand credits the user's balance (and runs any attached `buy`/`extend` action).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCryptoPaymentRequest"}}}},"responses":{"200":{"description":"Verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Buy proxy sessions using existing balance

> Purchase \`quantity\` sessions of \`plan\_id\` for \`day\` days each, paid from the\
> account balance. The response includes the gateway credentials for every new session.<br>

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"BuyRequest":{"type":"object","required":["plan_id","day"],"properties":{"plan_id":{"type":"integer","minimum":1},"day":{"type":"integer","minimum":1,"description":"Duration in days for each session."},"quantity":{"type":"integer","minimum":1,"maximum":100,"default":1}}},"BuyPaymentEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/BuyPaymentResponse"}}},"BuyPaymentResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double"},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/BuySessionInfo"}}}},"BuySessionInfo":{"type":"object","properties":{"session_id":{"type":"integer"},"username":{"type":"string"},"password":{"type":"string"},"gateway_host":{"type":"string"},"gateway_http_port":{"type":"integer"},"gateway_socks5_port":{"type":"integer"},"strategy":{"type":"string","enum":["bind","request","time"]},"duration":{"type":"integer","nullable":true},"expired_at":{"type":"string","format":"date-time","nullable":true}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/buy":{"post":{"tags":["Payments"],"summary":"Buy proxy sessions using existing balance","description":"Purchase `quantity` sessions of `plan_id` for `day` days each, paid from the\naccount balance. The response includes the gateway credentials for every new session.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyRequest"}}}},"responses":{"200":{"description":"Purchased.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyPaymentEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Extend the expiry of existing sessions

> Extend each of \`session\_ids\` by \`day\` days, paid from the account balance.

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"ExtendRequest":{"type":"object","required":["session_ids","day"],"properties":{"session_ids":{"type":"array","minItems":1,"maxItems":120,"items":{"type":"integer","minimum":1}},"day":{"type":"integer","minimum":1}}},"ExtendEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/ExtendResponse"}}},"ExtendResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double"},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/ExtendSessionInfo"}}}},"ExtendSessionInfo":{"type":"object","properties":{"session_id":{"type":"integer"},"expired_at":{"type":"string","format":"date-time","nullable":true}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/extend":{"post":{"tags":["Payments"],"summary":"Extend the expiry of existing sessions","description":"Extend each of `session_ids` by `day` days, paid from the account balance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendRequest"}}}},"responses":{"200":{"description":"Extended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Top up via VietQR and buy sessions atomically

> Create a single VietQR payment that both credits the balance and triggers a \`buy\`\
> once the funds are confirmed. Useful when the user has insufficient balance.<br>

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"TopupAndBuyRequest":{"type":"object","required":["amount","method","plan_id","day"],"properties":{"amount":{"type":"number","format":"double","exclusiveMinimum":0},"method":{"type":"string","enum":["vietqr"]},"plan_id":{"type":"integer","minimum":1},"day":{"type":"integer","minimum":1},"quantity":{"type":"integer","minimum":1,"maximum":100,"default":1}}},"TopupPaymentEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/TopupPaymentResponse"}}},"TopupPaymentResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double"},"payment_url":{"type":"string","description":"URL to redirect the payer to (VietQR)."},"bank_id":{"type":"string"},"account_no":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/topup-and-buy":{"post":{"tags":["Payments"],"summary":"Top up via VietQR and buy sessions atomically","description":"Create a single VietQR payment that both credits the balance and triggers a `buy`\nonce the funds are confirmed. Useful when the user has insufficient balance.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupAndBuyRequest"}}}},"responses":{"200":{"description":"Combined top-up + buy created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupPaymentEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Top up via VietQR and extend sessions atomically

> Create a single VietQR payment that both credits the balance and triggers an \`extend\` once the funds are confirmed.

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"TopupAndExtendRequest":{"type":"object","required":["amount","method","session_ids","day"],"properties":{"amount":{"type":"number","format":"double","exclusiveMinimum":0},"method":{"type":"string","enum":["vietqr"]},"session_ids":{"type":"array","minItems":1,"maxItems":120,"items":{"type":"integer","minimum":1}},"day":{"type":"integer","minimum":1}}},"TopupPaymentEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/TopupPaymentResponse"}}},"TopupPaymentResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double"},"payment_url":{"type":"string","description":"URL to redirect the payer to (VietQR)."},"bank_id":{"type":"string"},"account_no":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/topup-and-extend":{"post":{"tags":["Payments"],"summary":"Top up via VietQR and extend sessions atomically","description":"Create a single VietQR payment that both credits the balance and triggers an `extend` once the funds are confirmed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupAndExtendRequest"}}}},"responses":{"200":{"description":"Combined top-up + extend created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupPaymentEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Top up via crypto and buy sessions atomically

> Create a single USDT (TRC-20) payment that both credits the balance and triggers\
> a \`buy\` after the on-chain transfer is verified via \`POST /api/payment/verify-crypto\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"TopupAndBuyCryptoRequest":{"type":"object","required":["amount","method","plan_id","day"],"properties":{"amount":{"type":"number","format":"double","minimum":5},"method":{"type":"string","enum":["tron"]},"plan_id":{"type":"integer","minimum":1},"day":{"type":"integer","minimum":1},"quantity":{"type":"integer","minimum":1,"maximum":100,"default":1}}},"TopupCryptoEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/TopupCryptoResponse"}}},"TopupCryptoResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double","description":"Amount in USD requested."},"pay_amount":{"type":"number","format":"double","description":"Actual USDT amount the payer must send (may differ from amount due to fees)."},"wallet_address":{"type":"string"},"qr_code_url":{"type":"string","description":"URL of a QR code encoding the wallet address."}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/topup-crypto-and-buy":{"post":{"tags":["Payments"],"summary":"Top up via crypto and buy sessions atomically","description":"Create a single USDT (TRC-20) payment that both credits the balance and triggers\na `buy` after the on-chain transfer is verified via `POST /api/payment/verify-crypto`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupAndBuyCryptoRequest"}}}},"responses":{"200":{"description":"Combined crypto top-up + buy created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupCryptoEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Top up via crypto and extend sessions atomically

> Create a single USDT (TRC-20) payment that both credits the balance and triggers an \`extend\` after verification.

```json
{"openapi":"3.0.3","info":{"title":"RoProxy Integration API","version":"1.0.0"},"tags":[{"name":"Payments","description":"Top up balance, buy sessions, extend sessions, and inspect payment history."}],"servers":[{"url":"https://integration-api.ro-proxy.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key minted via `POST /api/key`, sent as\n`Authorization: Bearer <token>`.\n"}},"schemas":{"TopupAndExtendCryptoRequest":{"type":"object","required":["amount","method","session_ids","day"],"properties":{"amount":{"type":"number","format":"double","minimum":5},"method":{"type":"string","enum":["tron"]},"session_ids":{"type":"array","minItems":1,"maxItems":120,"items":{"type":"integer","minimum":1}},"day":{"type":"integer","minimum":1}}},"TopupCryptoEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/TopupCryptoResponse"}}},"TopupCryptoResponse":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"amount":{"type":"number","format":"double","description":"Amount in USD requested."},"pay_amount":{"type":"number","format":"double","description":"Actual USDT amount the payer must send (may differ from amount due to fees)."},"wallet_address":{"type":"string"},"qr_code_url":{"type":"string","description":"URL of a QR code encoding the wallet address."}}},"ErrorEnvelope":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}},"required":["message"]}},"responses":{"BadRequest":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/api/payment/topup-crypto-and-extend":{"post":{"tags":["Payments"],"summary":"Top up via crypto and extend sessions atomically","description":"Create a single USDT (TRC-20) payment that both credits the balance and triggers an `extend` after verification.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupAndExtendCryptoRequest"}}}},"responses":{"200":{"description":"Combined crypto top-up + extend created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupCryptoEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ro-proxy.gitbook.io/integration/payments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.