Account operations

These endpoints cover balances, refunds, payouts and dispute responses. They use the same keys and request helpers as the payment endpoints.

Endpoint	Purpose
`GET /api/account/balance`	Balance
`GET /api/account/available-balance`	Withdrawable balance
`POST /api/account/refunds`	Refund or void a payment
`GET /api/account/refunds[/{id}]`	List or retrieve refunds
`POST /api/account/withdrawals`	Request a USDT payout
`GET /api/account/withdrawals[/{id}]`	List or retrieve payouts
`GET /api/account/disputes[/{id}]`	List or retrieve disputes
`POST /api/account/disputes/{id}/evidence`	Respond to a dispute

Conventions

Signing, headers and Idempotency-Key work as described in Authentication.
A single item is returned as a plain JSON object; lists are returned as { "data": [...], "meta": {...} }.
Payment, refund, withdrawal and dispute IDs use LUVEI-ABCD-123456. Store the complete ID.
Balances and payouts use the system main currency; refunds and disputes use the currency of the payment.
201 or 202 means that the request was accepted, not completed. Track the status or the webhooks.
To test outcomes with a sandbox key, see Sandbox and test cards.

Pagination

Field	Type	Required	Description
`page`	`integer · query`	Optional	Page number, starting at `1`.
`per_page`	`integer · query`	Optional	Items per page, from `1` to `100`. Default: `20`.
`status`	`string · query`	Optional	Returns only items with this status.

Field	Type	Description
`page`	`integer`	Current page.
`per_page`	`integer`	Items per page.
`total`	`integer`	Number of matching items.
`total_pages`	`integer`	Number of pages (`0` if the list is empty).

Items are sorted newest first. A page beyond the last one returns 200 with an empty data. A page below 1, a per_page outside 1–100, an unknown status or an unknown parameter returns 422 1000001. Date filters are not supported.

List response · Example

{
  "data": [
    {
      "id": "LUVEI-RFND-100001",
      "operation": "refund",
      "status": "requested",
      "amount": "100.00",
      "currency": "USD",
      "reason": "Customer requested a full refund",
      "provider_reference": null,
      "provider_refunded_at": null,
      "created_at": "2026-11-02T09:00:00.000Z",
      "updated_at": null,
      "payment_id": "LUVEI-PAYN-123456",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

GET/api/account/balance

Balance

Retrieve your balance and the amount currently available for withdrawal. Both calls are read-only and report your API wallet, which holds the funds collected through this API. Other wallets in your panel are neither shown nor included.

Field	Type	Description
`currency_code`	`string`	Currency of all amounts: the system main currency.
`available_amount`	`string`	Settled funds in your API wallet that are available for use now. Unsettled and held amounts are excluded.
`pending_settlement_amount`	`string`	Funds from payments that have not yet settled. Always `0.00` in sandbox.
`environment`	`string`	`sandbox` or `live`.

cURLNode.jsPHPPython

./payniko.sh GET '/api/account/balance'

import {api} from './payniko.mjs';

const balance = await api('GET', '/api/account/balance');
console.log(balance);

<?php
require __DIR__ . '/payniko.php';

$balance = payniko_api('GET', '/api/account/balance');
print_r($balance);

from payniko import api

balance = api("GET", "/api/account/balance")
print(balance)

Response · Example

{
  "currency_code": "USD",
  "available_amount": "1250.00",
  "pending_settlement_amount": "300.00",
  "environment": "live"
}

Payments in other currencies are converted to the main currency. Fees and settlement dates are not included in this response.

GET/api/account/available-balance

Withdrawable balance

Field	Type	Description
`currency_code`	`string`	The system main currency.
`withdrawable_amount`	`string`	Settled funds in your API wallet that can be withdrawn now. This is exactly the amount that `POST /api/account/withdrawals` allows you to pay out.
`can_withdraw`	`boolean`	`false` while any of your balances is negative, in which case no payout is possible. `true` does not guarantee a payout.
`environment`	`string`	`sandbox` or `live`.

cURLNode.jsPHPPython

./payniko.sh GET '/api/account/available-balance'

import {api} from './payniko.mjs';

const available = await api('GET', '/api/account/available-balance');
console.log(available);

<?php
require __DIR__ . '/payniko.php';

$available = payniko_api('GET', '/api/account/available-balance');
print_r($available);

from payniko import api

available = api("GET", "/api/account/available-balance")
print(available)

Response · Example

{
  "currency_code": "USD",
  "withdrawable_amount": "1250.00",
  "can_withdraw": true,
  "environment": "live"
}

Amounts reserved for open payouts, unsettled funds and holds are excluded. The balance is checked again when you request a payout, so the request can still fail with 409 9000020.

POST/api/account/refundsIdempotency-Key required

Request a refund or void

Return the full amount of a successful payment to the payer. Each request is reviewed and processed by Payniko; 202 only confirms that the request was accepted.

Request body

Field	Type	Required	Description	Example
`payment_id`	`string · LUVEI-ABCD-123456`	Required	A `succeeded` payment created through `/api/payments` in the same environment. Any other ID returns `404` `9000009`.	`LUVEI-PAYN-123456`
`operation_type`	`string`	Required	The requested operation. `refundvoid`	`refund`
`reason`	`string`	Required	3–500 characters. Reviewed by the Payniko operations team.	`Customer requested a full refund`

There is no amount field; the full payment amount is returned. A payment can have only one refund or void at a time. While one is open or completed, or while the payment has a dispute that was not won, a new request returns 409 9000014.

cURLNode.jsPHPPython

KEY="$(openssl rand -hex 16)"  # store with the order before sending; reuse it after network errors
./payniko.sh POST '/api/account/refunds' '{
  "payment_id": "LUVEI-PAYN-123456",
  "operation_type": "refund",
  "reason": "Customer requested a full refund"
}' "$KEY"

import {api, randomUUID} from './payniko.mjs';

const key = randomUUID(); // Store this key with the order before sending; reuse it after network errors.
const refund = await api('POST', '/api/account/refunds', {
  "payment_id": "LUVEI-PAYN-123456",
  "operation_type": "refund",
  "reason": "Customer requested a full refund"
}, key);
console.log(refund);

<?php
require __DIR__ . '/payniko.php';

$key = bin2hex(random_bytes(16)); // store with the order; reuse it after network errors
$refund = payniko_api('POST', '/api/account/refunds', [
    "payment_id" => 'LUVEI-PAYN-123456',
    "operation_type" => 'refund',
    "reason" => 'Customer requested a full refund',
], $key);
print_r($refund);

from payniko import api
import uuid

key = str(uuid.uuid4())  # store with the order; reuse it after network errors
refund = api("POST", "/api/account/refunds", {
    "payment_id": "LUVEI-PAYN-123456",
    "operation_type": "refund",
    "reason": "Customer requested a full refund"
}, key)
print(refund)

Response · Example

{
  "id": "LUVEI-RFND-100001",
  "operation": "refund",
  "status": "requested",
  "amount": "100.00",
  "currency": "USD",
  "reason": "Customer requested a full refund",
  "provider_reference": null,
  "provider_refunded_at": null,
  "created_at": "2026-11-02T09:00:00.000Z",
  "updated_at": null,
  "payment_id": "LUVEI-PAYN-123456",
  "environment": "live"
}

Response · 202

Returns the refund. Resending the same key and body returns 202 with the same refund.

Possible errors

List and retrieve refunds

cURLNode.jsPHPPython

./payniko.sh GET '/api/account/refunds?status=completed&page=1&per_page=20'

import {api} from './payniko.mjs';

const refunds = await api('GET', '/api/account/refunds?status=completed&page=1&per_page=20');
console.log(refunds);

<?php
require __DIR__ . '/payniko.php';

$refunds = payniko_api('GET', '/api/account/refunds?status=completed&page=1&per_page=20');
print_r($refunds);

from payniko import api

refunds = api("GET", "/api/account/refunds?status=completed&page=1&per_page=20")
print(refunds)

Field	Type	Required	Description
`page`	`integer · query`	Optional	Page number, starting at `1`.
`per_page`	`integer · query`	Optional	Items per page, from `1` to `100`. Default: `20`.
`status`	`string · query`	Optional	Returns only refunds with this status.
`operation_type`	`string · query`	Optional	`refund` or `void`.

GET /api/account/refunds/{id} returns a single refund (404 9000009 if it does not exist). The list contains the refunds requested through the API.

Refund object

Field	Type	Description
`id`	`string · LUVEI-ABCD-123456`	Refund ID.
`operation`	`string`	`refund` or `void`, as sent in `operation_type`.
`status`	`string`	See the table below.
`amount`	`string`	Full amount of the payment.
`currency`	`string`	Currency of the payment.
`reason`	`string`	The reason provided in the request.
`provider_reference`	`string \| null`	Reference of the processed refund, once available.
`provider_refunded_at`	`string · date-time \| null`	Time at which the refund was processed, if known.
`created_at`	`string · date-time`	Time of the request.
`updated_at`	`string · date-time \| null`	Time of the last change.
`payment_id`	`string · LUVEI-ABCD-123456 \| null`	The refunded payment.
`environment`	`string`	`sandbox` or `live`.

Status	Meaning
`requested`	Accepted but not yet processed.
`processing`	Being processed.
`awaiting_provider_manual`	Being completed manually; this can take longer.
`completed`	Completed. Final status.
`rejected`	Rejected. Final status.
`failed`	Failed. Final status.
`cancelled`	Cancelled. Final status.

GET /api/account/refunds/{id} always returns the current status. The outcome is also delivered as a webhook.

POST/api/account/withdrawalsIdempotency-Key required

Request a payout

Pay out funds from your API wallet as USDT on the TRON network (TRC20). The amount is reserved and sent after review.

Request body

Field	Type	Required	Description	Example
`amount`	`string`	Required	Two decimal places, for example `50.00`; must not be `0.00` and must be at least your minimum. Together with today's requested and sent payouts, it must stay within your daily limit.	`"50.00"`
`address`	`string`	Required	TRC20 address: 34 characters, starting with `T`, with a valid checksum.	`YOUR_VERIFIED_TRC20_ADDRESS`
`address_acknowledged`	`boolean`	Required	Must be `true`, confirming that the address is correct.	`true`
`webhook_url`	`string · uri`	Required	Endpoint that receives the webhooks for this payout. The same rules as for payments apply.	`https://merchant.example/webhooks/withdrawals`

success_url and fail_url are not permitted in this request.

cURLNode.jsPHPPython

# Replace YOUR_VERIFIED_TRC20_ADDRESS with the address you confirmed with its owner.
KEY="$(openssl rand -hex 16)"  # store with the order before sending; reuse it after network errors
./payniko.sh POST '/api/account/withdrawals' '{
  "amount": "50.00",
  "address": "YOUR_VERIFIED_TRC20_ADDRESS",
  "address_acknowledged": true,
  "webhook_url": "https://merchant.example/webhooks/withdrawals"
}' "$KEY"

import {api, randomUUID} from './payniko.mjs';

// Replace YOUR_VERIFIED_TRC20_ADDRESS with the address you confirmed with its owner.
const key = randomUUID(); // Store this key with the order before sending; reuse it after network errors.
const withdrawal = await api('POST', '/api/account/withdrawals', {
  "amount": "50.00",
  "address": "YOUR_VERIFIED_TRC20_ADDRESS",
  "address_acknowledged": true,
  "webhook_url": "https://merchant.example/webhooks/withdrawals"
}, key);
console.log(withdrawal);

<?php
require __DIR__ . '/payniko.php';

// Replace YOUR_VERIFIED_TRC20_ADDRESS with the address you confirmed with its owner.
$key = bin2hex(random_bytes(16)); // store with the order; reuse it after network errors
$withdrawal = payniko_api('POST', '/api/account/withdrawals', [
    "amount" => '50.00',
    "address" => 'YOUR_VERIFIED_TRC20_ADDRESS',
    "address_acknowledged" => true,
    "webhook_url" => 'https://merchant.example/webhooks/withdrawals',
], $key);
print_r($withdrawal);

from payniko import api
import uuid

# Replace YOUR_VERIFIED_TRC20_ADDRESS with the address you confirmed with its owner.
key = str(uuid.uuid4())  # store with the order; reuse it after network errors
withdrawal = api("POST", "/api/account/withdrawals", {
    "amount": "50.00",
    "address": "YOUR_VERIFIED_TRC20_ADDRESS",
    "address_acknowledged": True,
    "webhook_url": "https://merchant.example/webhooks/withdrawals"
}, key)
print(withdrawal)

Response · Example

{
  "id": "LUVEI-WTHD-100002",
  "status": "requested",
  "amount": "50.00",
  "currency": "USD",
  "asset": "USDT",
  "network": "TRC20",
  "address": "YOUR_VERIFIED_TRC20_ADDRESS",
  "usdt_amount": "49.950000",
  "tx_hash": null,
  "rejection_reason": null,
  "requested_at": "2026-11-02T10:00:00.000Z",
  "processed_at": null,
  "created_at": "2026-11-02T10:00:00.000Z",
  "environment": "live"
}

Response · 201

Returns the payout with its status, usually requested. Resending the same key and body returns 201 with the same payout.

Possible errors

List and retrieve payouts

cURLNode.jsPHPPython

./payniko.sh GET '/api/account/withdrawals?status=requested&page=1&per_page=20'

import {api} from './payniko.mjs';

const withdrawals = await api('GET', '/api/account/withdrawals?status=requested&page=1&per_page=20');
console.log(withdrawals);

<?php
require __DIR__ . '/payniko.php';

$withdrawals = payniko_api('GET', '/api/account/withdrawals?status=requested&page=1&per_page=20');
print_r($withdrawals);

from payniko import api

withdrawals = api("GET", "/api/account/withdrawals?status=requested&page=1&per_page=20")
print(withdrawals)

Filter by status. GET /api/account/withdrawals/{id} returns a single payout (404 9000023 if it does not exist).

Withdrawal object

Field	Type	Description
`id`	`string · LUVEI-ABCD-123456`	Payout ID.
`status`	`string`	See the table below. `requestedsentrejected`
`amount`	`string`	Requested amount in the main currency.
`currency`	`string`	The main currency.
`asset`	`string`	Always `USDT`.
`network`	`string`	Always `TRC20`.
`address`	`string`	Destination address.
`usdt_amount`	`string`	USDT amount to be sent (six decimal places).
`tx_hash`	`string \| null`	Blockchain transaction hash, once known.
`rejection_reason`	`string \| null`	Reason for the rejection.
`requested_at`	`string · date-time`	Time of the request.
`processed_at`	`string · date-time \| null`	Time at which the payout was sent or rejected.
`created_at`	`string · date-time`	Time of creation.
`environment`	`string`	`sandbox` or `live`.

Status	Meaning
`requested`	Created; the amount is reserved but not yet sent.
`sent`	Sent. Final status. `tx_hash` can initially be `null` and is added later.
`rejected`	Not sent; the reserved amount is returned to your available balance. See `rejection_reason`. Final status.

The Payniko team sends or rejects each payout and then sets processed_at, together with tx_hash or rejection_reason. During maintenance, a new payout request can return 503 1000014.

GET/api/account/disputes

List and retrieve disputes

A dispute (chargeback) is opened when a cardholder contests a payment with their bank. When the dispute opens, the amount is usually deducted from your balance; it is returned if you win and remains deducted if you lose. Respond before the deadline.

cURLNode.jsPHPPython

./payniko.sh GET '/api/account/disputes?status=open&page=1&per_page=20'

import {api} from './payniko.mjs';

const disputes = await api('GET', '/api/account/disputes?status=open&page=1&per_page=20');
console.log(disputes);

<?php
require __DIR__ . '/payniko.php';

$disputes = payniko_api('GET', '/api/account/disputes?status=open&page=1&per_page=20');
print_r($disputes);

from payniko import api

disputes = api("GET", "/api/account/disputes?status=open&page=1&per_page=20")
print(disputes)

Response · Example

{
  "data": [
    {
      "id": "LUVEI-DSPT-100003",
      "service": "api",
      "amount": "100.00",
      "currency": "USD",
      "status": "open",
      "reason": "product_not_delivered",
      "reason_note": null,
      "occurred_on": "2026-11-03",
      "evidence_due_at": "2026-11-10T09:00:00.000Z",
      "evidence_submitted_at": null,
      "merchant_evidence_note": null,
      "merchant_evidence_submitted_at": null,
      "resolved_at": null,
      "created_at": "2026-11-03T09:00:00.000Z",
      "payment_id": "LUVEI-PAYN-123456",
      "environment": "sandbox"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Filter by status. GET /api/account/disputes/{id} returns a single dispute (404 9000015 if it does not exist). The list contains all disputes on your account; payment_id is set when the dispute relates to an API payment.

Dispute object

Field	Type	Description
`id`	`string · LUVEI-ABCD-123456`	Dispute ID.
`service`	`string`	Origin of the payment, for example `api`.
`amount`	`string`	Disputed amount in the payment currency.
`currency`	`string`	Currency of the payment.
`status`	`string`	See the table below. `openunder_reviewwonlost`
`reason`	`string`	Reason provided by the bank. Handle unknown values as well. `fraudunauthorizedproduct_not_deliveredduplicateamount_mismatchother`
`reason_note`	`string \| null`	Note from the bank, if any.
`occurred_on`	`string · date`	Date of the dispute (`YYYY-MM-DD`).
`evidence_due_at`	`string · date-time \| null`	Deadline for your response.
`evidence_submitted_at`	`string · date-time \| null`	Time at which the defence was submitted to the bank.
`merchant_evidence_note`	`string \| null`	Your most recent response.
`merchant_evidence_submitted_at`	`string · date-time \| null`	Time at which you submitted your response.
`resolved_at`	`string · date-time \| null`	Time at which the dispute was decided.
`created_at`	`string · date-time`	Time of creation.
`payment_id`	`string · LUVEI-ABCD-123456 \| null`	The disputed API payment; otherwise `null`.
`environment`	`string`	`sandbox` or `live`.

Status	Meaning
`open`	New dispute. You can respond until `evidence_due_at`.
`under_review`	The defence has been submitted to the bank and a decision is pending. You can still respond until the deadline.
`won`	Decided in your favour. Final status.
`lost`	Decided against you. Final status.

POST/api/account/disputes/{id}/evidenceIdempotency-Key required

Respond to a dispute

Request body

Field	Type	Required	Description
`note`	`string`	Required	Your response, 3–4000 characters: delivery details, communication with the customer and the evidence you hold.

cURLNode.jsPHPPython

KEY="$(openssl rand -hex 16)"  # store with the order before sending; reuse it after network errors
./payniko.sh POST '/api/account/disputes/LUVEI-DSPT-100003/evidence' '{
  "note": "The order was delivered on 2026-10-28; tracking number and signed receipt are available."
}' "$KEY"

import {api, randomUUID} from './payniko.mjs';

const key = randomUUID(); // Store this key with the order before sending; reuse it after network errors.
const dispute = await api('POST', '/api/account/disputes/LUVEI-DSPT-100003/evidence', {
  "note": "The order was delivered on 2026-10-28; tracking number and signed receipt are available."
}, key);
console.log(dispute);

<?php
require __DIR__ . '/payniko.php';

$key = bin2hex(random_bytes(16)); // store with the order; reuse it after network errors
$dispute = payniko_api('POST', '/api/account/disputes/LUVEI-DSPT-100003/evidence', [
    "note" => 'The order was delivered on 2026-10-28; tracking number and signed receipt are available.',
], $key);
print_r($dispute);

from payniko import api
import uuid

key = str(uuid.uuid4())  # store with the order; reuse it after network errors
dispute = api("POST", "/api/account/disputes/LUVEI-DSPT-100003/evidence", {
    "note": "The order was delivered on 2026-10-28; tracking number and signed receipt are available."
}, key)
print(dispute)

Response · Example

{
  "id": "LUVEI-DSPT-100003",
  "service": "api",
  "amount": "100.00",
  "currency": "USD",
  "status": "open",
  "reason": "product_not_delivered",
  "reason_note": null,
  "occurred_on": "2026-11-03",
  "evidence_due_at": "2026-11-10T09:00:00.000Z",
  "evidence_submitted_at": null,
  "merchant_evidence_note": "The order was delivered on 2026-10-28; tracking number and signed receipt are available.",
  "merchant_evidence_submitted_at": "2026-11-04T08:00:00.000Z",
  "resolved_at": null,
  "created_at": "2026-11-03T09:00:00.000Z",
  "payment_id": "LUVEI-PAYN-123456",
  "environment": "sandbox"
}

Response · 200

Returns the dispute including your note.

Accepted only while the dispute is open or under_review and before evidence_due_at; otherwise the request returns 409 9000016.
A new request with a new Idempotency-Key replaces your previous note.
File uploads are not supported through the API. Describe the available evidence in the note.

Possible errors

To test disputes with a sandbox key, create one with POST /api/sandbox/disputes.