Transaction Update

This endpoint can be implemented by the partner to receive real-time transaction status updates from Payward.

When a Ramp transaction is created or changes state, Payward sends a POST request to the partner’s configured webhook URL with transaction details and status information.

Security

All webhook requests include an X-Signature header containing an HMAC-SHA256 signature of the request body. Partners should verify this signature to ensure integrity of the request.

Contact your Payward integration point of contact to securely exchange the HMAC secret key for signature verification.

Signature Verification

1. Extract the X-Signature header value
2. Compute HMAC-SHA256 of the raw request body using your webhook secret
3. Compare the computed signature with the X-Signature header value (hex-encoded)

import crypto from 'crypto';

// This function will return true/false if the signature matches
const verifySignature = (signature: string, secret: string, body: string) => {
  const hash = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return (signature === hash);
};

Retry Behavior

Payward will automatically retry failed webhook deliveries using exponential backoff. Partners should respond with HTTP 2xx status to acknowledge receipt. Non-2xx responses will trigger retries.

Status Types

The status field provides a simplified transaction state:

• new - Transaction has been initiated
• paid - Payment has been received
• pending - Transaction is being processed
• completed - Transaction successfully completed
• failed - Transaction failed
• canceled - Transaction was canceled

POST /webhooks/payward/transaction-update

Transaction Update

cURL

curl --request POST \
  --url https://your-webhook-endpoint.com/webhooks/payward/transaction-update \
  --header 'Content-Type: <content-type>' \
  --header 'X-Signature: <x-signature>' \
  --data '
{
  "status": "completed",
  "payload": {
    "transaction_id": "<string>",
    "in_amount": "10.00",
    "in_asset": "USD",
    "out_asset": "BTC",
    "out_amount": "0.002813",
    "in_method": "creditCard",
    "out_method": "Bitcoin",
    "timestamp": "2025-11-07T14:35:57.391208753Z",
    "wallet": "<string>",
    "transaction_hash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "external_transaction_id": "<string>",
    "external_user_id": "<string>",
    "external_partner_id": "<string>",
    "external_metadata": "<string>",
    "affiliate_fee": "0.50"
  },
  "raw_status": {},
  "timestamp": "2025-11-07T14:35:57.391209043Z"
}
'

Headers

X-Signature · string · required

HMAC-SHA256 signature of the request body (hex-encoded). Use this to verify the webhook authenticity.

Example:

"35d050c7eb06bf050fd676db4e6c79f5e90abef9b2ae8aa2dac23302998db5cf"

Content-Type · enum<string> · required

Available options: application/json

Body

application/json

Webhook request sent by Payward when a Ramp transaction status changes.

status · enum<string> · required

Transaction status:

• new - Transaction has been initiated
• paid - Payment has been received
• pending - Transaction is being processed
• completed - Transaction successfully completed
• failed - Transaction failed
• canceled - Transaction was canceled

Available options: new, paid, pending, completed, failed, canceled

Example:

"completed"

payload · object · required

Transaction payload containing detailed information about the Ramp transaction.

Show child attributes

raw_status · object · required

Object containing internal status information for more granular transaction tracking.

timestamp · string<date-time> · required

Timestamp when this webhook request was created (ISO-8601 format). Use this for replay attack detection.

Example:

"2025-11-07T14:35:57.391209043Z"

Response

200

Webhook received and processed successfully. Return any 2xx status code to acknowledge receipt.