Get payment

Returns full payment details when called with an API key (merchant view). Returns limited payment details when called without an API key (customer view).

GET/v1/payments/{paymentId}API key

Path parameters

Field	Type	Description
`paymentId`required	string	Payment ID

Response

200 OK

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.

asset values AssetID

USDT_ETHEREUMUSDT_ARBITRUMUSDT_OPTIMISMUSDT_BASEUSDT_BSCUSDT_PLASMAUSDT_POLYGONUSDC_ETHEREUMUSDC_ARBITRUMUSDCE_ARBITRUMUSDC_OPTIMISMUSDC_BASEUSDC_BSCUSDC_PLASMAUSDC_POLYGONETH_ETHEREUMETH_ARBITRUMETH_OPTIMISMETH_BASEXPL_PLASMABNB_BSCPOL_POLYGONTESTCOIN_ETHEREUMTESTCOIN_OPTIMISMTESTCOIN_PLASMATESTSTABLECOIN_ETHEREUMTESTSTABLECOIN_OPTIMISMTESTSTABLECOIN_PLASMA

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.

networkFeePayer values FeePayer

merchantcustomer

serviceFeePayeroptional FeePayer Who bears the platform (service) fee, echoed from creation.

serviceFeePayer values FeePayer

merchantcustomer

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.

redirectConfig fields RedirectConfigDTO

Field	Type	Description
`data`optional	string	Opaque string passed through unchanged as the "data" query parameter on the return URL. Use it to carry your own session/order token.
`params`optional	string[]	Which payment identifiers to append to the return URL as query parameters. Allowed values: "id" (the Suward payment id) and "externalId" (your identifier).
`params` values string[] `idexternalId`
`url`optional	string	Base "return to store" URL the customer is sent back to after paying.

statusoptional PaymentStatusEnum Main payment lifecycle status. See the status enum for the full meaning of each value.

status values PaymentStatusEnum

pendingacceptedsuccessfailed

subStatusoptional PaymentSubStatusEnum Fine-grained payment sub-status describing the current step or amount condition. See the sub-status enum for the full meaning of each value.

subStatus values PaymentSubStatusEnum

createdactivatedawaitingPaymentconfirmingcompletedoverpaidunderpaidexpiredcancelledpartiallyPaid

transactionsoptional TransactionList Preview page of the on-chain transactions detected for this payment (newest first). Use GET /v1/payments/{paymentId}/transactions for the full paginated list.

transactions 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 TransactionResponse[] Page of transactions, ordered per the request's order parameter.

items fields TransactionResponse

Field	Type	Description
`acceptedAt`optional	integer	Unix-milliseconds timestamp when the transfer reached the accepted (safe) confirmation tier. Null before acceptance.
`amount`optional	string	On-chain transfer amount, an integer string in the asset's smallest unit (see CreatePaymentRequest.amount).
`detectedAt`optional	integer	Unix-milliseconds timestamp when the transfer was first seen on-chain.
`txHash`optional	string	On-chain transaction hash of the transfer.

underpaymentToleranceoptional string Integer string in the asset's smallest unit.

updatedAtoptional integer Unix-milliseconds timestamp when the payment was last updated.

webhookUrloptional string Webhook URL that receives this payment's events, echoed from creation. Null when the project default webhook is used.

paymentPageUrloptional string Absolute URL of the Suward-hosted checkout page where the customer pays this payment.

Errors

500 Internal Server Error— each returns { errorCode, message, args? }. Codes, retries and limits: Errors & limits

All Payments endpoints

Request

terminal

curl https://api.suward.com/v1/payments/<payment_id> \
  -H "X-Api-Key: $SUWARD_API_KEY"

request.js

const response = await fetch('https://api.suward.com/v1/payments/<payment_id>', {
  method: 'GET',
  headers: {
    'X-Api-Key': process.env.SUWARD_API_KEY,
  },
});
const data = await response.json();

main.go

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
)
 
func main() {
	req, _ := http.NewRequest("GET", "https://api.suward.com/v1/payments/<payment_id>", 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))
}

Response · 200 OK

response.json

{
  "acceptedAt": 0,
  "activatedAt": 0,
  "activationFlowSeconds": 3600,
  "address": "0xabc…def",
  "amount": "100000000",
  "amountConfirmed": "100000000",
  "amountReceived": "100000000",
  "asset": "USDT_ETHEREUM",
  "confirmedAt": 0,
  "createdAt": 0,
  "expiresAt": 0,
  "externalId": "order_abc123",
  "fee": "1000000",
  "id": "obj_abc123",
  "metadata": {},
  "networkFee": "150000",
  "quotedPrice": "string",
  "networkFeePayer": "merchant",
  "serviceFeePayer": "merchant",
  "paymentWindowSeconds": 3600,
  "projectId": "obj_abc123",
  "redirectConfig": {},
  "status": "pending",
  "subStatus": "created",
  "transactions": {},
  "underpaymentTolerance": "0",
  "updatedAt": 0,
  "webhookUrl": "https://example.com/webhook",
  "paymentPageUrl": "string"
}

Illustrative values. Every field, type and status on this page is generated from the OpenAPI specification.

PreviousCreate payment NextActivate payment

Something unclear? payments@suward.com — we treat every integration question as a documentation defect.