Payments

Payment creation and management. External ID must be unique per node.

Authentication: Bearer token required (except Get Payment Widget Data).

---

Create Payment

Endpoint: POST /api/v1/payments

Request Body

Field	Type	Required	Description
external_id	string	Yes	Unique per node
node_id	string	Yes	Node UUID
chain_id	string	No	Chain UUID
network_id	string	Yes	Network UUID
wallet_id	string	No	Wallet UUID
member_id	string	No	Member UUID
member	object	No	Inline member data (external_id, name, surname, email, etc.)
currency_id	string	Yes	Currency UUID
price	float64	Yes	Price
paid_price	float64	Yes	Paid price
payment_method	string	Yes	web3, credit_card, or bank_transfer
payment_group	string	Yes	product or listing_or_subscription
payment_address	string	Yes	Payment address (min 10 chars)
items	array	No	Payment items (name, price, external_id)
metadata	string	No	Metadata
expires_at	string	Yes	RFC3339 datetime
retry	bool	No	Retry flag
retry_count	int	No	Retry count
client_ip	string	No	Client IP (IPv4)

Response — 201 Created

Returns PaymentResponse with access_token for the payment widget.

Status	Description
404	Node or currency not found
409	External ID already exists for node

---

List Payments

Endpoint: GET /api/v1/payments

Query Parameters

Parameter	Type	Required	Default	Description
node_id	string	Yes	—	Node UUID
wallet_id	string	No	—	Filter by wallet
network_id	string	No	—	Filter by network
page	int	No	1	Page number
per_page	int	No	10	Items per page (max 100)

Response — 200 OK

Paginated list with items (PaymentResponse), page, per_page, total.

---

Get Payment by ID

Endpoint: GET /api/v1/payments/{id}

Response — 200 OK

Full payment object including access_token, status, transaction_hash, etc.

Status	Description
404	Payment not found

---

Cancel Payment

Endpoint: POST /api/v1/payments/{id}/cancel

Triggers cancelDeal on the diamond contract. Integration's node must have access to the payment's node.

Response — 202 Accepted

{ "status": "accepted" }

Status	Description
403	Insufficient permission to access payment's node
404	Payment not found

---

List Payment Logs

Endpoint: GET /api/v1/payments/{id}/logs

Returns paginated payment logs, ordered by created_at DESC.

Query Parameters

Parameter	Type	Required	Default	Description
page	int	No	1	Page number
per_page	int	No	10	Items per page (max 100)

Response — 200 OK

Paginated list with items (event_type, message, actor_type, created_at, etc.), page, per_page, total.

Status	Description
404	Payment not found

---

Retry Send Payment

Endpoint: POST /api/v1/payments/{id}/retry-send

Re-sends a pending web3 payment to the create-payment consumer.

Response — 200 OK

Returns updated payment object.

Status	Description
400	Payment not eligible for retry
404	Payment not found

---

Get Payment Widget Data

Endpoint: GET /api/v1/widget/payments/{id}

Returns payment data and contract info for the payment widget. Use access_token from payment creation response.

Authentication: Bearer <access_token> (from payment creation, not integration JWT).

Response — 200 OK

{
  "external_id": "...",
  "node_id": "...",
  "network_id": 1,
  "deal_id": 123,
  "price": 100.0,
  "price_decimals": 6,
  "payment_address": "...",
  "diamond_address": "...",
  "currency": "USDT",
  "token_address": "...",
  "contract": {
    "abi": [...],
    "function_name": "deposit",
    "arguments": [...]
  }
}

Status	Description
401	Invalid or expired access token
404	Payment not found