List payments
Return a paginated list of the project's payments, newest first. Page and sort the results with the order, limit, and lastId query parameters.
GET
/v1/paymentsAPI keyQuery parameters
| Field | Type | Description |
|---|---|---|
orderoptional | string | Sort order (asc/desc) |
| ||
limitoptional | integer | Limit (default 20, max 100) |
lastIdoptional | string | Last ID for pagination |
Response
200 OK
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
hasMoreoptional | boolean | True when more payments exist beyond this page. To fetch the next page, pass the last item's id as the lastId query parameter. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
itemsoptional | PaymentResponse[] | Page of payments, ordered per the request's order parameter. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Field | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
acceptedAtoptional | integer | Unix-milliseconds timestamp when the payment reached the accepted state (safe confirmations, balance credited). Null before acceptance. | |||||||||||||||
activatedAtoptional | integer | Unix-milliseconds timestamp when the payment was activated and its payment window began counting. Null before activation. | |||||||||||||||
activationFlowSecondsoptional | integer | Resolved activation grace period, in seconds. Null when not configured. | |||||||||||||||
addressoptional | string | On-chain deposit address the customer must send funds to. Null until the payment is activated and an address is assigned. | |||||||||||||||
amountoptional | string | Integer string in the asset's smallest unit. | |||||||||||||||
amountConfirmedoptional | string | Integer string in the asset's smallest unit. | |||||||||||||||
amountReceivedoptional | string | Integer string in the asset's smallest unit. | |||||||||||||||
assetoptional | AssetID | Asset the payment is denominated in, as an asset id-string (see GET /v1/assets). Null until an asset is selected for the payment. | |||||||||||||||
| |||||||||||||||||
confirmedAtoptional | integer | Unix-milliseconds timestamp when the payment reached finalization (confirmed). Null until confirmed; may revert if a chain reorg undoes the confirmation. | |||||||||||||||
createdAtoptional | integer | Unix-milliseconds timestamp when the payment was created. | |||||||||||||||
expiresAtoptional | integer | Unix-milliseconds timestamp when the payment window closes; the payment expires (fails) if it has not been paid by then. | |||||||||||||||
externalIdoptional | string | Merchant's own identifier for this payment, echoed from creation. Null when none was provided. | |||||||||||||||
feeoptional | string | Platform fee: 0.4% of the amount, minimum $1 equivalent. Integer string in the asset's smallest unit. | |||||||||||||||
idoptional | string | Unique Suward identifier of the payment. Use it in the payment endpoints (get, cancel, transactions) and as the checkout page path. | |||||||||||||||
metadataoptional | object | Arbitrary key/value data attached by the merchant at creation, echoed back unchanged. | |||||||||||||||
networkFeeoptional | string | Estimated on-chain (gas) cost, deducted from the received amount. Integer string in the asset's smallest unit. | |||||||||||||||
quotedPriceoptional | string | USD price of the asset locked at creation, decimal string. Fees are computed from this price at settlement, so the merchant's net is deterministic. | |||||||||||||||
networkFeePayeroptional | FeePayer | Who bears the network (gas) fee, echoed from creation. | |||||||||||||||
| |||||||||||||||||
serviceFeePayeroptional | FeePayer | Who bears the platform (service) fee, echoed from creation. | |||||||||||||||
| |||||||||||||||||
paymentWindowSecondsoptional | integer | Resolved length of the payment window, in seconds. | |||||||||||||||
projectIdoptional | string | Identifier of the project that owns this payment. | |||||||||||||||
redirectConfigoptional | RedirectConfigDTO | Return-to-store redirect configuration echoed from creation. Null when none was configured. | |||||||||||||||
| |||||||||||||||||
| Field | Type | Description |
|---|---|---|
dataoptional | string | Opaque string passed through unchanged as the "data" query parameter on the return URL. Use it to carry your own session/order token. |
paramsoptional | string[] | Which payment identifiers to append to the return URL as query parameters. Allowed values: "id" (the Suward payment id) and "externalId" (your identifier). |
| ||
urloptional | string | Base "return to store" URL the customer is sent back to after paying. |
statusoptionalstatus values PaymentStatusEnum
pendingacceptedsuccessfailedsubStatusoptionalsubStatus values PaymentSubStatusEnum
createdactivatedawaitingPaymentconfirmingcompletedoverpaidunderpaidexpiredcancelledpartiallyPaidtransactionsoptionaltransactions fields TransactionList
| Field | Type | Description |
|---|---|---|
hasMoreoptional | boolean | True when more transactions exist beyond this page. To fetch the next page, pass the last item's id as the lastId query parameter. |
itemsoptional | object[] | Page of transactions, ordered per the request's order parameter. |
underpaymentToleranceoptionalupdatedAtoptionalwebhookUrloptionalpaymentPageUrloptionalErrors
400 Bad Request401 Unauthorized500 Internal Server Error— each returns { errorCode, message, args? }. Codes, retries and limits: Errors & limits
Request
curl https://api.suward.com/v1/payments \ -H "X-Api-Key: $SUWARD_API_KEY"const response = await fetch('https://api.suward.com/v1/payments', { method: 'GET', headers: { 'X-Api-Key': process.env.SUWARD_API_KEY, },});const data = await response.json();package main import ( "fmt" "io" "net/http" "os") func main() { req, _ := http.NewRequest("GET", "https://api.suward.com/v1/payments", nil) req.Header.Set("X-Api-Key", os.Getenv("SUWARD_API_KEY")) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() data, _ := io.ReadAll(res.Body) fmt.Println(string(data))}import requests, os response = requests.get( 'https://api.suward.com/v1/payments', headers={'X-Api-Key': os.environ['SUWARD_API_KEY']},)data = response.json()Response · 200 OK
{ "hasMore": false, "items": []}Illustrative values. Every field, type and status on this page is generated from the OpenAPI specification.
Something unclear? payments@suward.com — we treat every integration question as a documentation defect.