​
Introduction to On-Ramp Webhooks

Ripio utilizes webhooks to provide real-time updates on the status of On-Ramp transactions. By subscribing to these events, your application can stay informed about the progress of fiat-to-crypto conversions and react accordingly. All On-Ramp webhook events share a common payload structure and are sent as POST requests to your configured webhook endpoint. Remember to validate the signature of each incoming webhook as described in the Webhooks Introduction.

​
Event Payload Structure

Each On-Ramp event notification message contains a JSON-formatted payload with the following general structure: 
{
  "eventType": "EVENT_TYPE_HERE",
  "issueDatetime": "YYYY-MM-DDTHH:MM:SS.ffffffZ",
  "transactionObject": {
    // Fields specific to the transaction and event type
  }
}
  • eventType (String): The specific type of On-Ramp event that occurred.
  • issueDatetime (String): The Coordinated Universal Time (UTC) timestamp indicating when the event was triggered (e.g., "2024-04-25T18:22:37Z").
  • transactionObject (Object): An object containing details of the On-Ramp transaction associated with the event. The structure of this object can vary slightly based on the eventType.

​
On-Ramp Event Types

The following event types are available for On-Ramp transactions:

​
ON-RAMP.DEPOSIT.RECEIVED

  • Description: Sent after Ripio successfully confirms a fiat deposit associated with the user’s payment instructions for an On-Ramp order.
  • transactionObject typically includes: Standard On-Ramp transaction fields (see below).

​
ON-RAMP.TRADE.COMPLETED

  • Description: Sent after Ripio successfully completes the trade operation (converting fiat to cryptocurrency) for the On-Ramp transaction.
  • transactionObject typically includes: Standard On-Ramp transaction fields.

​
ON-RAMP.WITHDRAWAL.PROCESSING

  • Description: Sent after Ripio successfully initiates the cryptocurrency withdrawal operation to the customer’s designated deposit address.
  • transactionObject typically includes: Standard On-Ramp transaction fields, often including txnHash.

​
ON-RAMP.WITHDRAWAL.COMPLETED

  • Description: Sent after Ripio successfully confirms that the cryptocurrency withdrawal for the On-Ramp transaction has been completed on the blockchain.
  • transactionObject typically includes: Standard On-Ramp transaction fields, including txnHash.

​
ON-RAMP.ORDER.CANCELLED

  • Description: Sent if Ripio cancels the On-Ramp order. This can occur, for example, due to significant market price deviations exceeding a pre-defined threshold compared to the original quote. In such cases, the trade is cancelled to protect the user, and a refund will typically be initiated.
  • transactionObject typically includes: Standard On-Ramp transaction fields.

​
ON-RAMP.ORDER.REFUNDED

  • Description: Sent after Ripio successfully completes a refund for the On-Ramp transaction, often following an order cancellation (ON-RAMP.ORDER.CANCELLED) or if an order expires.
  • transactionObject typically includes: Standard On-Ramp transaction fields.

​
ON-RAMP.DEPOSIT.REFUNDED

  • Description: Sent after Ripio completes a refund of a fiat deposit that is not linked to an existing or processable On-Ramp order. This is distinct from ON-RAMP.ORDER.REFUNDED.
  • transactionObject structure for this event:
    • transactionId (String): Unique identifier for the deposit being refunded.
    • originAccountIdentifier (String): Identifier of the account from which the deposit originated.
    • amount (String): The amount of the deposit that was received and is being refunded.
    • customerId (String): Unique identifier of the customer associated with the deposit, if known.
    • paymentMethodType (String): The payment method used for the original fiat deposit.
    • createdAt (String): Date and time the original deposit was created.

​
Standard Transaction Object Fields

For most On-Ramp events (excluding ON-RAMP.DEPOSIT.REFUNDED), the transactionObject will contain the following standard fields:
  • transactionId (String): Unique identifier for the On-Ramp transaction.
  • createdAt (String): Date and time the On-Ramp transaction was created.
  • customerId (String): Unique identifier of the customer associated with the On-Ramp transaction.
  • quoteId (String): Reference to the original quote used for this transaction.
  • fromCurrency (String): The source currency (fiat) used in the On-Ramp transaction (e.g., “ARS”).
  • toCurrency (String): The target cryptocurrency to be received (e.g., “USDC”).
  • amount (String): The amount of the target cryptocurrency to be received (based on the original quote).
  • chain (String): The target blockchain network for the cryptocurrency deposit (e.g., “ETHEREUM_SEPOLIA”).
  • paymentMethodType (String): The payment method used for the fiat deposit (as specified in the original quote).
  • depositAddress (String): The customer’s deposit address on the chosen blockchain network.
  • status (String): The current status of the transaction (e.g., “ON_RAMP_DEPOSIT_RECEIVED”, “ON_RAMP_TRADE_COMPLETED”).
  • txnHash (String, optional): The transaction hash for the on-chain cryptocurrency withdrawal. This is typically present in ON-RAMP.WITHDRAWAL.PROCESSING and ON-RAMP.WITHDRAWAL.COMPLETED events.
  • externalRef (String, optional): The unique identifier for the order provided during creation.
Note: The exact fields and their presence might vary slightly. Always inspect the payload of received webhooks.

​
On-Ramp Event Flows

The following sequences represent the expected order of events in common On-Ramp scenarios. However, it’s important to design your system to handle webhooks that might arrive out of order due to network conditions or other factors.
  1. Standard Successful On-Ramp Transaction Flow: ON-RAMP.DEPOSIT.RECEIVED → ON-RAMP.TRADE.COMPLETED → ON-RAMP.WITHDRAWAL.PROCESSING → ON-RAMP.WITHDRAWAL.COMPLETED
    • Description: This is the typical flow for a successful transaction, from fiat deposit confirmation to cryptocurrency withdrawal completion.
  2. Order Cancellation and Refund Flow: ON-RAMP.DEPOSIT.RECEIVED → ON-RAMP.ORDER.CANCELLED → ON-RAMP.ORDER.REFUNDED
    • Description: In this scenario, after a fiat deposit is received, the order is cancelled (e.g., due to price volatility), and then a refund for the fiat deposit is processed.
  3. Standalone Deposit Refund Flow (Unlinked Deposit): ON-RAMP.DEPOSIT.REFUNDED
    • Description: This event occurs if a fiat deposit is received but cannot be matched to an active On-Ramp order, leading to a direct refund of the deposit.

​
Important Considerations

  • Webhook Delivery Order: While the flows above describe the logical sequence of operations, webhook notifications might arrive out of order due to network latency, retries, or server processing times. Your integration should be robust enough to handle such discrepancies, for example, by checking timestamps or transaction statuses.
  • Idempotency: Ensure your webhook processing logic is idempotent. This means that if your endpoint receives the same event notification multiple times, it does not result in duplicated actions or errors.
  • Error Handling: Implement comprehensive error handling in your webhook consumer.
  • Configuration: For instructions on configuring webhook endpoints in your Ripio partner account, please contact the Ripio technical team.