​
Introduction to Off-Ramp Webhooks

Ripio provides webhook notifications to keep your application informed about real-time status updates for Off-Ramp transactions. These events cover the process of converting cryptocurrency back into fiat currency and its subsequent withdrawal. Similar to On-Ramp events, Off-Ramp webhooks are sent as POST requests with a JSON payload to your configured endpoint. It is crucial to validate the signature of every incoming webhook request as detailed in the Webhooks Introduction.

​
Event Payload Structure

Each Off-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 Off-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 Off-Ramp transaction associated with the event.

​
Off-Ramp Event Types

The following event types are supported for Off-Ramp transactions:

​
OFF-RAMP.DEPOSIT.RECEIVED

  • Description: Sent after Ripio successfully confirms a cryptocurrency deposit to the address associated with the user’s active Off-Ramp session.
  • transactionObject typically includes: Off-Ramp transaction fields (see below), including details of the crypto deposit.

​
OFF-RAMP.TRADE.COMPLETED

  • Description: Sent after Ripio successfully completes the trade operation, converting the deposited cryptocurrency into fiat currency.
  • transactionObject typically includes: Off-Ramp transaction fields.

​
OFF-RAMP.WITHDRAWAL.PROCESSING

  • Description: Sent after Ripio initiates the fiat withdrawal process to the customer’s designated fiat account linked to the active Off-Ramp session.
  • transactionObject typically includes: Off-Ramp transaction fields.

​
OFF-RAMP.WITHDRAWAL.COMPLETED

  • Description: Sent upon successful completion and confirmation that the fiat withdrawal to the customer’s account has been finalized.
  • transactionObject typically includes: Off-Ramp transaction fields.

​
OFF-RAMP.ORDER.CANCELLED

  • Description: Sent if Ripio cancels the Off-Ramp order. This might occur if a customer breaches predefined transactional or periodic limits. In some specific cases, a manual refund of the cryptocurrency deposit might be considered.
  • transactionObject typically includes: Off-Ramp transaction fields.

​
Transaction Object Fields for Off-Ramp Events

The transactionObject for Off-Ramp events generally includes the following fields:
  • transactionId (String): Unique identifier for the Off-Ramp transaction (often corresponds to the session ID).
  • createdAt (String): Date and time the Off-Ramp session/transaction was created (UTC format).
  • fiatAccountId (String): Unique identifier for the customer’s fiat account associated with the session.
  • fromCurrency (String): The source cryptocurrency being off-ramped (e.g., “USDC”).
  • toCurrency (String): The target fiat currency to be received (e.g., “ARS”).
  • amount (String): The amount of the source cryptocurrency deposited by the customer.
  • chain (String): The blockchain network used for the cryptocurrency deposit (e.g., “ETHEREUM”).
  • address (String): The cryptocurrency deposit address used by the customer for this Off-Ramp transaction.
  • status (String): The current status of the Off-Ramp transaction.
  • txnHash (String, optional): The transaction hash for the on-chain cryptocurrency deposit. This is typically present in OFF-RAMP.DEPOSIT.RECEIVED and subsequent events.
  • customerId (String, optional): Unique identifier of the customer associated with the transaction.
Note: The exact fields and their presence might vary slightly. Always inspect the payload of received webhooks.

​
Off-Ramp Event Flows

The following sequences illustrate the expected order of events in common Off-Ramp scenarios. As with On-Ramp events, your system should be prepared to handle webhooks that might arrive out of the typical order.
  1. Standard Successful Off-Ramp Transaction Flow: OFF-RAMP.DEPOSIT.RECEIVED → OFF-RAMP.TRADE.COMPLETED → OFF-RAMP.WITHDRAWAL.PROCESSING → OFF-RAMP.WITHDRAWAL.COMPLETED
    • Description: This is the usual flow for a successful Off-Ramp transaction, starting from the confirmation of a cryptocurrency deposit, followed by its conversion to fiat, initiation of the fiat withdrawal, and finally, the completion of the withdrawal.
  2. Order Cancellation Flow (e.g., Due to Limit Breach): OFF-RAMP.DEPOSIT.RECEIVED → OFF-RAMP.ORDER.CANCELLED
    • Description: This flow occurs when a cryptocurrency deposit is received, but the transaction is subsequently cancelled, for instance, if the customer exceeds transactional limits. A manual review might be needed for potential refunds in specific cases.

​
Important Considerations

  • Webhook Delivery Order: While these flows outline the logical progression, network latency or server processing can cause webhooks to arrive out of sequence. Design your webhook handlers to accommodate this.
  • Idempotency: Ensure that processing the same webhook event multiple times does not lead to unintended side effects or data inconsistencies.
  • Error Management: Implement robust error handling and logging in your webhook consumer.
  • Configuration: For details on setting up your webhook endpoints within the Ripio partner system, please consult with the Ripio technical team.