Get Payment

Retrieve details of a specific payment by its ID.

HTTP Method: GET
Endpoint URL: /v2/payment/{id}
Authentication: Requires API-KEY header.

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Unique payment identifier

Example Request

curl -X GET https://api.alppay.io/v2/payment/3d6b7f2a-1c4e-4a8b-9f3d-2e5c1a7b0d9e \
  -H "API-KEY: your_api_key_here"

Response

HTTP Status: 200 OK

{
  "data": {
    "id": "3d6b7f2a-1c4e-4a8b-9f3d-2e5c1a7b0d9e",
    "status": "COMPLETED",
    "displayStatus": "OVERPAID",
    "amount": "100.00",
    "totalReceivedAmount": "115.00",
    "addressTo": "TXyz...abc",
    "destTag": null,
    "confirmsNeeded": 20,
    "timeout": 3600,
    "checkoutUrl": "https://pay.alppay.io/checkout/3d6b7f2a-...",
    "paymentRedirectUrl": "https://yoursite.com/order/123",
    "invoice": "ORDER-123",
    "asset": {
      "short": "USDT",
      "name": "Tether USD",
      "logoUrl": "https://cdn.alppay.io/assets/usdt.png",
      "network": "TRC20"
    },
    "customer": {
      "id": 42,
      "name": "John Doe",
      "email": "[email protected]"
    },
    "merchant": {
      "id": 7,
      "name": "My Store",
      "siteUrl": "https://mystore.com",
      "logoUrl": "https://mystore.com/logo.png",
      "email": "[email protected]"
    },
    "transactions": [
      {
        "paymentId": "3d6b7f2a-1c4e-4a8b-9f3d-2e5c1a7b0d9e",
        "txnId": "a1b2c3d4e5f6...",
        "receivedAmount": "115.00",
        "addressFrom": "TAbc...xyz",
        "addressTo": "TXyz...abc",
        "destTag": null,
        "asset": {
          "short": "USDT",
          "name": "Tether USD",
          "logoUrl": "https://cdn.alppay.io/assets/usdt.png",
          "network": "TRC20"
        },
        "fixedFee": "1.00",
        "percentFee": "2.30",
        "riskScore": 5,
        "isDanger": false,
        "createdAt": "2024-10-15T12:34:56Z"
      }
    ],
    "fixedFee": "1.00",
    "createdAt": "2024-10-15T12:30:00Z",
    "updatedAt": "2024-10-15T12:35:00Z"
  }
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Unique payment identifier
`status`	string	Internal lifecycle state: `OPEN`, `EXPIRED`, `COMPLETED`
`displayStatus`	string	Business-facing payment status
`amount`	string (decimal)	Requested payment amount
`totalReceivedAmount`	string (decimal)	Total amount received
`addressTo`	string	Destination wallet address
`destTag`	string \| null	Destination tag (for XRP, XLM, etc.)
`confirmsNeeded`	integer	Required blockchain confirmations
`timeout`	integer	Payment expiry timeout in seconds
`checkoutUrl`	string	URL of hosted payment page
`paymentRedirectUrl`	string	Redirect URL after payment
`invoice`	string \| null	Merchant order or invoice reference
`asset`	object	Cryptocurrency asset details
`customer`	object	Customer information
`merchant`	object	Merchant information
`transactions`	array	On-chain transactions linked to the payment
`fixedFee`	string (decimal)	Fixed fee applied
`createdAt`	string (ISO 8601)	Payment creation timestamp
`updatedAt`	string (ISO 8601)	Last update timestamp

Display Status Values

Value	Description
`NEW`	Payment created, awaiting deposit
`OPEN`	Awaiting payment from the customer
`COMPLETED`	Payment received in full
`EXPIRED`	Payment window expired without full payment
`UNDERPAID`	Amount received is less than required
`OVERPAID`	Amount received exceeds the invoice amount
`AML_CHECK_DANGER`	Payment flagged by AML check, manual review required

Error Responses

401 Unauthorized

Missing or invalid API key.

{
  "error": "unauthorized"
}

403 Forbidden

Payment belongs to a different merchant.

{
  "error": "forbidden"
}

400 Bad Request

Payment not found or invalid UUID.

{
  "error": "payment not found"
}