Skip to main content

​
Introduction to Sell and Pay Webhooks

Ripio provides webhook notifications to keep your application informed about real-time status updates for Sell and Pay transactions. These events cover the process of converting cryptocurrency to fiat currency and completing QR code payments to merchants. Similar to On-Ramp and Off-Ramp events, Sell and Pay 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 Sell and Pay event notification message contains a JSON-formatted payload with the following general structure: 
{
  "eventType": "EVENT_TYPE_HERE",
  "issueDatetime": "YYYY-MM-DDTHH:MM:SS.ffffffZ",
  "transaction": {
    // Fields specific to the transaction and event type
  }
}
  • eventType (String): The specific type of Sell and Pay event that occurred.
  • issueDatetime (String): The Coordinated Universal Time (UTC) timestamp indicating when the event was triggered (e.g., "2024-04-25T18:22:37Z").
  • transaction (Object): An object containing details of the Sell and Pay transaction associated with the event.

​
Sell and Pay Event Types

The following event types are supported for Sell and Pay transactions:

​
SELL_AND_PAY.DEPOSIT_CONFIRMED

  • Description: Sent after Ripio successfully confirms a cryptocurrency deposit to the address associated with the Sell and Pay transaction. This indicates that the crypto deposit has been detected and confirmed on the blockchain.
  • transaction typically includes: Sell and Pay transaction fields (see below), including details of the crypto deposit.

​
SELL_AND_PAY.DEPOSIT_BLOCKED

  • Description: Sent when the cryptocurrency deposit has been blocked. This can occur due to compliance issues, suspicious activity, or other security reasons. The deposit will not be processed and may be subject to review.
  • transaction typically includes: Sell and Pay transaction fields.

​
SELL_AND_PAY.COMPLETED

  • Description: Sent after the QR code payment to the merchant has been successfully completed. This indicates that the cryptocurrency has been converted to fiat currency and the payment has been processed to the merchant.
  • transaction typically includes: Sell and Pay transaction fields, including payment confirmation details.

​
SELL_AND_PAY.REFUNDED

  • Description: Sent after a refund of the cryptocurrency deposit has been completed. This can occur if the transaction was cancelled, failed, or if the deposit was blocked. The cryptocurrency is returned to the customer’s refund address.
  • transaction typically includes: Sell and Pay transaction fields, including refundTxnHash.

​
Transaction Object Fields for Sell and Pay Events

The transaction object for Sell and Pay events includes the following fields (matching the SellAndPayWebhookSerializer structure):
  • id (String): Unique identifier for the Sell and Pay transaction.
  • createdAt (String): Date and time the Sell and Pay transaction was created (UTC format).
  • expiresAt (String): Date and time when the transaction will expire (UTC format).
  • customerId (String): Unique identifier of the customer associated with the transaction.
  • trade (Object, nullable): Trade execution details containing information about the crypto-to-fiat conversion. Will be null if the trade has not been executed yet. See SellAndPayTrade schema for structure.
  • paymentOrder (Object, nullable): Payment order details for the QR code payment to the merchant. Will be null if the payment order has not been created yet. See SellAndPayPaymentOrder schema for structure.
  • amount (String): Payment amount in fiat currency to be paid to the merchant.
  • cryptoAmount (String): The amount of cryptocurrency required/deposited.
  • paymentCurrency (String): The fiat currency used for the QR code payment to the merchant (e.g., “ARS”, “BRL”).
  • depositCurrency (String): The cryptocurrency deposited by the customer (e.g., “USDC”, “BTC”).
  • depositNetwork (String): The blockchain network used for the cryptocurrency deposit (e.g., “ETHEREUM”, “POLYGON”).
  • depositAddress (String): The cryptocurrency address where the deposit was made.
  • status (String): The current status of the Sell and Pay transaction (e.g., “CONFIRMED_DEPOSIT”, “COMPLETED”, “REFUNDED”).
Note: The exact fields and their presence might vary slightly depending on the transaction state. Always inspect the payload of received webhooks.

​
Sell and Pay Event Flows

The following sequences illustrate the expected order of events in common Sell and Pay scenarios. Your system should be prepared to handle webhooks that might arrive out of the typical order due to network conditions or other factors.
  1. Standard Successful Sell and Pay Transaction Flow: SELL_AND_PAY.DEPOSIT_CONFIRMED → SELL_AND_PAY.COMPLETED
    • Description: This is the usual flow for a successful Sell and Pay transaction, starting from the confirmation of a cryptocurrency deposit, followed by the completion of the QR code payment to the merchant.
  2. Deposit Blocked Flow: SELL_AND_PAY.DEPOSIT_BLOCKED → SELL_AND_PAY.REFUNDED
    • Description: In this scenario, the cryptocurrency deposit is blocked due to compliance or security reasons, and subsequently refunded to the customer.
  3. Transaction Cancellation and Refund Flow: SELL_AND_PAY.DEPOSIT_CONFIRMED → SELL_AND_PAY.REFUNDED
    • Description: After a deposit is confirmed, the transaction may be cancelled (e.g., due to payment processing failure, customer request, or timeout), leading to a refund of the cryptocurrency deposit.

​
Important Considerations

  • Idempotency: Your webhook endpoint should be designed to handle duplicate webhook deliveries gracefully. Use the transactionId and eventType to identify and deduplicate events if necessary.
  • Signature Validation: Always validate the webhook signature to ensure the request is genuinely from Ripio. See the Webhooks Introduction for details on signature validation.
  • Asynchronous Processing: Process webhooks asynchronously to avoid blocking your webhook endpoint and to ensure timely responses to Ripio’s servers.
  • Error Handling: Implement robust error handling and logging for your webhook processing logic to debug issues effectively.
  • Event Order: While events generally follow the flows described above, your system should not strictly depend on receiving events in a specific order. Design your logic to handle events arriving out of sequence.

​
Example Webhook Payload

Here’s an example of a SELL_AND_PAY.COMPLETED webhook payload: 
{
  "eventType": "SELL_AND_PAY.COMPLETED",
  "issueDatetime": "2024-10-01T15:30:45.123456Z",
  "transaction": {
    "id": "a3b2c1d0-1234-5678-90ab-cdef12345678",
    "createdAt": "2024-10-01T15:20:00.000000Z",
    "expiresAt": "2024-10-01T16:20:00.000000Z",
    "customerId": "b6cecc1f-c90d-424b-adaa-c82b780696c1",
    "trade": {
      "id": "trade-uuid-here",
      "customerId": "end-user-uuid",
      "baseAsset": "USDC",
      "quoteAsset": "ARS",
      "baseAmount": "10.25",
      "quoteAmount": "10000.50",
      "rate": "976.0975609756098",
      "marketRate": "980.00"
    },
    "paymentOrder": {
      "id": "payment-order-uuid",
      "customerId": "end-user-uuid",
      "merchant": "Merchant Name",
      "qrCode": "00020101021226360014...",
      "amount": "10000.50",
      "currency": "ARS",
      "providerTxnId": "provider-txn-123"
    },
    "amount": "10000.50",
    "cryptoAmount": "10.25",
    "paymentCurrency": "ARS",
    "depositCurrency": "USDC",
    "depositNetwork": "ETHEREUM",
    "depositAddress": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
    "status": "COMPLETED"
  }
}
For more information on configuring webhooks and validating signatures, please refer to the Webhooks Introduction.