GET

List Payins

A referência da API está em inglês. Os guias, a autenticação, os webhooks e os códigos de erro estão em português.

Lists deposits created through the API (not those created in the panel), newest first (created_at descending), with filters and pagination.

Answers 200 OK. summary counts pending, completed, failed and reversed deposits matching the same filters. minimum_payment is the percentage of crypto_amount that marks the payin completed; received_amount is what actually arrived, and payment_status says partial, exact or overpaid (null before any payment). A reversed deposit carries reversal with reversed_at, partial (true when part of the payin is still credited) and amounts (balance key and amount removed); reversal is null otherwise. meta.filters echoes the filters applied, with status in its public value. Fields that need explanation are described below.

GEThttps://bridge.bifrostcrypto.com/v1/list-payin

Escopo exigido:payin:read(chave nova sem lista é somente leitura)

Headers

Key	Value	Description
`X-Bifrost-Invoke`	`{{api_key}}`	Private API key

Query Parameters

Parameter	Example	Description
`page`	`1`	Page number (default: 1). 0 or a non-numeric value falls back to 1; a negative value returns invalid_page_number.
`per_page`	`50`	Items per page, 1-100 (default: 50). 0 or a non-numeric value falls back to 50; above 100 or negative returns invalid_per_page_limit.
`status`	`completed`	Filter by status: pending, completed, failed or reversed (any case). completed excludes reversed deposits. Anything else returns invalid_status_filter.
`crypto_currency`	`USDT`	Filter by crypto currency symbol (exact match)
`network`	`BinanceSmartChain`	Filter by a network name from the catalog, exact and case-sensitive (BinanceSmartChain, not binancesmartchain). An unknown name returns invalid_network_filter.
`date_from`	`2026-01-01`	Start date (YYYY-MM-DD), inclusive from 00:00:00. An unparseable date returns invalid_date_from. No maximum range. Read in UTC−03:00.
`date_to`	`2026-01-31`	End date (YYYY-MM-DD), inclusive until 23:59:59. An unparseable date returns invalid_date_to. Read in UTC−03:00.
`reference_id`	`invoice_67890`	Filter by reference_id (exact match)

cURL Example

bash

curl -X GET "https://bridge.bifrostcrypto.com/v1/list-payin?page=1&per_page=50&status=completed" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY"

Response Example

json

{
  "message": "deposits_retrieved_success",
  "deposits": [
    {
      "internal_reference": "f531c319-6957-45c6-a154-d4944ca3eee3",
      "reference_id": "invoice_67890",
      "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "crypto_currency": "USDT",
      "invoice_currency": "USDT",
      "invoice_amount": "50.00",
      "fiat_currency": "USD",
      "crypto_amount": "50.00",
      "received_amount": "0.00000000",
      "fiat_amount": "50.00",
      "process_by": "crypto_amount",
      "percent_rate": "2.50",
      "network_fee": "0.00000000",
      "minimum_payment": "10.00",
      "network": "BinanceSmartChain",
      "status": "pending",
      "payment_status": null,
      "txid": null,
      "payments": [],
      "webhook_url": "https://your-site.com/webhook-deposit",
      "is_wallet_fixed": false,
      "reversal": null,
      "created_at": "2026-01-16 10:00:00",
      "updated_at": "2026-01-16 10:00:00",
      "expires_at": "2026-01-16 14:00:00"
    }
  ],
  "summary": {
    "total_pending": 1,
    "total_completed": 0,
    "total_failed": 0,
    "total_reversed": 0
  },
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 1,
    "total_pages": 1,
    "filters": {
      "status": "pending",
      "crypto_currency": "USDT"
    }
  }
}

Deposit fields

Fields of each entry in deposits that are not obvious from their name.

Field	Meaning
`invoice_currency · invoice_amount`	Token and amount of the payin as created (the same as crypto_currency and crypto_amount).
`received_amount`	Amount actually received, converted to crypto_currency when the customer paid with another token.
`minimum_payment`	Percentage of crypto_amount that marks the payin completed.
`payment_status`	partial, exact or overpaid, comparing received_amount with crypto_amount; null before any payment.
`payments[]`	One entry per transfer received: token, amount, network, txid and timestamp. converted_to (token and amount) appears when the transfer was in a token other than the invoice token.
`txid`	Text holding a JSON list of transaction hashes, e.g. "[\"0xabc...\"]". Decode it as JSON; null before any payment.
`is_wallet_fixed`	true when the payin came from a fixed address.
`reversal`	null, or reversed_at, partial and amounts when the network undid a credited payment.

Errors

Every error has the shape error.code, error.message and, when useful, error.details. Authentication, scope and rate-limit errors (401, 403, 429) apply to every endpoint and are described under Authentication.

Status	Code	When	What to do
400	`invalid_page_number`	page is negative.	Fix the request before sending it again.
400	`invalid_per_page_limit`	per_page is negative or above 100.	Fix the request before sending it again.
400	`invalid_status_filter`	status is not one of the accepted values.	Fix the request before sending it again.
400	`invalid_network_filter`	network is not a known network name (case-sensitive).	Fix the request before sending it again.
400	`invalid_date_from · invalid_date_to`	A date could not be read.	Send YYYY-MM-DD.
500	`internal_error`	Unexpected failure.	Nothing was changed. Retry later.

Outras respostas

Respostas que não são o caminho feliz e ainda assim precisam de tratamento na sua integração.

400

Invalid filter

json

{
  "error": {
    "code": "invalid_network_filter",
    "message": "Invalid network filter"
  }
}