Optional - Set up webhooks

📘
Optional
This step is optional and by no means needed to get a functioning Onramper integration up and running. Setting up webhooks is a way for you to always know the status of a transactiom.

Endpoint configuration

Set up an endpoint on your server capable of handling POST requests. This will serve as the webhook listener. Ensure the endpoint can parse and handle JSON payloads, as this is the typical format for webhook data.

Webhook registration with Onramper

To activate webhooks for a specific ApiKey, please reach out to your Customer Success Manager. Provide them with your preferred webhook URL and the associated ApiKey for which you wish to enable webhooks.

Payload structure

The webhook will send a payload containing these specific properties:

{
    "apiKey": "pk_test_01K4MF4ZBPGDCV3GFFNA684NT0",
    "country": "us",
    "inAmount": 100,
    "onramp": "gatefi",
    "onrampTransactionId": "8bf94c80-test-aabb-851-143835984d1d",
    "outAmount": 3.83527521,
    "paymentMethod": "creditcard",
    "partnerContext": "",
    "sourceCurrency": "usd",
    "status": "pending",  	
    "statusDate": "2023-08-09T13:15:18.725Z",
    "targetCurrency": "sol",
    "transactionId": "01H7D547TESTV2RQJ52ZAB7WF7",
    "transactionType": "buy",
    "transactionHash": "",
    "walletAddress": "testG15oy66q7cU6aNige54PxLLEfGZvRsAADjbF7D4",
    "partnerFee": "0.01",
    "alternateRouteData": {
      "finalCurrency": "ccc_solana",
      "finalAmount": 3000.3302,
      "intermediateCurrencyId": "sol",
      "alternateRouteProvider": "moongate",
    }

}

Payload property explanation

Attribute	Type	Required	Description
`country`	string	true	The country from which the transaction was initiated.
`apiKey`	string	true	The public key with which the transaction was initiated.
`inAmount`	number	true	For Onramp transactions, this field indicates the requested fiat amount.
`onramp`	string	true	The ID corresponding to the provider for processing the transaction.
`onrampTransactionId`	string	true	The transaction ID is assigned by the provider
`outAmount`	number	true	For Onramp transactions, it contains the Crypto Currency amount delivered.
`paymentMethod`	string	false	The payment method id was utilized for the transaction.
`partnerContext`	string	false	The `partnerContext` can be provided as a string parameter to the widget, and it will be relayed back in the webhook responses.
`sourceCurrency`	string	true	For Onramp transactions, this field specifies the Fiat Currency id .
`status`	string	true	A string that indicates the transaction status. Possible values are: "`new`", "`pending`", "`paid`", "`completed`", "`canceled`", or "`failed`". The specific statuses might vary among providers, depending on the webhooks they support.
`statusReason`	string	false	Reason for transaction status: Provides context where relevant, included selectively based on applicability.
`statusDate`	string	true	A date/time string formatted in the simplified extended ISO 8601 format.
`targetCurrency`	string	true	For Onramp transactions, this field holds the Crypto Currency Id
`transactionId`	string	true	Onramper transaction ID.
`transactionType`	string	true	The type of transaction, which can be either "`buy`" or "`sell`".
`transactionHash`	string	false	The transaction hash is provided when relevant or applicable.
`walletAddress`	string	false	The wallet address where the crypto was delivered.
`isRecurringPayment`	boolean	false	A boolean attribute that specifies whether the transaction is recurring.
`alternateRouteData`	Object	false	A object compromising of data related to the intermediary transaction. Structure as follows: `{ finalCurrency: string; finalAmount: number; intermediateCurrencyId: string; alternateRouteProvider:string }`
`partnerFee`	number	false	Partner fee as a decimal fraction of the transaction amount. For example, 0.02 = 2.0% fee. Calculate the fee in source currency: `feeAmount = inAmount × partnerFee` Example: For inAmount=100 USD and partnerFee=0.02, the fee is 2 USD.``

Security and payload validation

Upon request for webhook registration, Onramper will provide you with a secret key. This key is used by Onramper to generate a hash signature for each payload. This signature is then included in the headers of every request under the name X-Onramper-Webhook-Signature.

For security, it's essential to compute a hash using the provided secret on your end and verify that it aligns with the hash received from Onramper. Note that Onramper employs an HMAC hex digest method to calculate this hash.

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);
};

Keeping your keys safe

NEVER embed your secret API Key in any web pages or mobile applications.
Don't store the secret API Key in any version control system.
Limit who has access to your secret API Key.

alternateRouteData

This object is only added to the transaction for the fiat-to-any flow.