Transaction Update

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": "credit_card",
    "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"
}
'

Ramp

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

Extract the X-Signature header value
Compute HMAC-SHA256 of the raw request body using your webhook secret
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 --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": "credit_card",
    "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

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

Get Ramp Checkout URL List Settlement Reports

⌘I