API Reference
Complete API documentation for integrating Pulse2Pay into your application.
Base URL
All API endpoints are relative to:
https://api.pulse2pay.com/api/merchant/v1Authentication
All API requests must include the following headers:
| Header | Description |
|---|---|
X-Pulse2Pay-Key | Your public API key |
X-Pulse2Pay-Signature | HMAC-SHA256 signature |
X-Pulse2Pay-Timestamp | Unix timestamp in milliseconds |
Signature calculation:
signature = HMAC-SHA256(apiSecret, timestamp + "." + method + "." + path + "." + body)
Endpoints
POST
/paymentsCreate a new payment request
Request Body
{
"amount": "100.50",
"currency": "USDT",
"network": "TRON",
"tokenStandard": "TRC20",
"addressMode": "PER_PAYMENT",
"description": "Order #1001",
"metadata": {
"orderId": "1001",
"customerId": "cust_abc"
},
"callbackUrl": "https://yoursite.com/webhooks/pulse2pay",
"successRedirectUrl": "https://yoursite.com/success",
"cancelRedirectUrl": "https://yoursite.com/cancel",
"expiresInMinutes": 30,
"idempotencyKey": "order-1001-v1"
}Response
{
"paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"network": "TRON",
"currency": "USDT",
"tokenStandard": "TRC20",
"amount": "100.50",
"expectedAmount": "100.50",
"receivedAmount": null,
"generatedAddress": "TXyz...abc123",
"generatedTokenAccount": null,
"addressMode": "PER_PAYMENT",
"merchantUserId": null,
"txHash": null,
"confirmations": 0,
"createdAt": "2025-01-12T15:00:00.000Z",
"confirmedAt": null,
"expiresAt": "2025-01-12T15:30:00.000Z",
"metadata": { "orderId": "1001", "customerId": "cust_abc" },
"callbackUrl": "https://yoursite.com/webhooks/pulse2pay",
"successRedirectUrl": "https://yoursite.com/success",
"cancelRedirectUrl": "https://yoursite.com/cancel",
"feeAmount": "1.005",
"netAmount": "99.495"
}GET
/payments/:paymentIdGet payment status and details
Response
{
"paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "confirmed",
"network": "TRON",
"currency": "USDT",
"tokenStandard": "TRC20",
"amount": "100.50",
"expectedAmount": "100.50",
"receivedAmount": "100.50",
"generatedAddress": "TXyz...abc123",
"generatedTokenAccount": null,
"addressMode": "PER_PAYMENT",
"merchantUserId": null,
"txHash": "abc123def456...",
"confirmations": 19,
"createdAt": "2025-01-12T15:00:00.000Z",
"confirmedAt": "2025-01-12T15:05:00.000Z",
"expiresAt": "2025-01-12T15:30:00.000Z",
"metadata": { "orderId": "1001" },
"feeAmount": "1.005",
"netAmount": "99.495"
}POST
/payments/:paymentId/cancelCancel a pending payment
Response
{
"paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "canceled",
"network": "TRON",
"currency": "USDT",
"tokenStandard": "TRC20",
"amount": "100.50",
"expectedAmount": "100.50",
"receivedAmount": null,
"generatedAddress": "TXyz...abc123",
"generatedTokenAccount": null,
"addressMode": "PER_PAYMENT",
"merchantUserId": null,
"txHash": null,
"confirmations": 0,
"createdAt": "2025-01-12T15:00:00.000Z",
"confirmedAt": null,
"expiresAt": "2025-01-12T15:30:00.000Z",
"metadata": { "orderId": "1001" },
"feeAmount": "1.005",
"netAmount": "99.495"
}Payment Statuses
| Status | Description |
|---|---|
pending | Waiting for customer to send payment |
confirmed | Payment confirmed on blockchain |
underpaid | Received amount was less than expected |
overpaid | Received amount was more than expected |
expired | Payment expired (30 minute timeout) |
canceled | Payment canceled by merchant |
failed | Payment processing failed |
Error Handling
Error responses include a JSON body with error details:
{
"error": {
"code": "INVALID_SIGNATURE",
"message": "Request signature verification failed"
}
}