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.RECEIVED

  • Description: Sent after Ripio successfully received a cryptocurrency deposit to the address associated with the Sell and Pay transaction. This indicates that the crypto deposit has been detected 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.PAYMENT_ORDER.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 order has been processed to the merchant.
  • transaction typically includes: Sell and Pay transaction fields, including payment confirmation details in the paymentOrder object.

​
SELL_AND_PAY.DEPOSIT_WITHOUT_SELL_AND_PAY.REFUND_PROCESSING

  • Description: Sent when a cryptocurrency deposit is received that is not associated with any existing Sell and Pay transaction. This triggers a refund process to return the cryptocurrency to the sender. Note: This event does NOT contain a full Sell and Pay transaction object.
  • transaction structure: This event has a special structure containing only cryptoDeposit (the deposit information) and refundTxnHash (the refund transaction hash). See the special transaction object section below for details.

​
SELL_AND_PAY.DEPOSIT.REFUND_PROCESSING

  • Description: Sent when a refund of the cryptocurrency deposit is being processed for a Sell and Pay transaction. This can occur if the transaction was cancelled, failed, or if the deposit was blocked. The cryptocurrency will be returned to the customer’s refund address.
  • transaction typically includes: Sell and Pay transaction fields with refund processing details.

​
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”).
  • cryptoDeposit (Object, nullable): Information about the cryptocurrency deposit made by the customer. Will be null until a deposit is detected on the blockchain. See SellAndPayCryptoDeposit schema for structure.
  • refundTxnHash (String, nullable): Transaction hash for the refund transaction on the blockchain. Present when a refund has been processed.

​
Special Transaction Object for SELL_AND_PAY.DEPOSIT_WITHOUT_SELL_AND_PAY.REFUND_PROCESSING

This event has a different transaction structure with only the following fields:
  • cryptoDeposit (Object): Information about the cryptocurrency deposit that was received without an associated Sell and Pay transaction. See SellAndPayCryptoDeposit schema for structure.
  • refundTxnHash (String, nullable): Transaction hash for the refund transaction on the blockchain. Will be present once the refund is processed.
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.RECEIVED → SELL_AND_PAY.PAYMENT_ORDER.COMPLETED
    • Description: This is the usual flow for a successful Sell and Pay transaction, starting from the receipt 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.DEPOSIT.REFUND_PROCESSING
    • Description: In this scenario, the cryptocurrency deposit is blocked due to compliance or security reasons, and subsequently a refund is processed to return the cryptocurrency to the customer.
  3. Transaction Cancellation and Refund Flow: SELL_AND_PAY.DEPOSIT.RECEIVED → SELL_AND_PAY.DEPOSIT.REFUND_PROCESSING
    • Description: After a deposit is received, the transaction may be cancelled (e.g., due to payment processing failure, customer request, or timeout), leading to a refund of the cryptocurrency deposit.
  4. Deposit Without Sell and Pay Transaction Flow: SELL_AND_PAY.DEPOSIT_WITHOUT_SELL_AND_PAY.REFUND_PROCESSING
    • Description: This event is triggered when a cryptocurrency deposit is received at a Sell and Pay address but there is no associated transaction. The system automatically processes a refund to return the cryptocurrency to the sender.

​
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 Payloads

​
Example 1: SELL_AND_PAY.PAYMENT_ORDER.COMPLETED

Standard Sell and Pay transaction completed successfully: 
{
  "eventType": "SELL_AND_PAY.PAYMENT_ORDER.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",
    "cryptoDeposit": {
      "id": "deposit-uuid",
      "txnId": "txn-uuid",
      "hash": "0xabc123def456...",
      "currencyCode": "USDC",
      "addressDestination": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
      "confirmationDate": "2024-10-01T15:25:00.000000Z",
      "amount": "10.25",
      "createdAt": "2024-10-01T15:22:00.000000Z",
      "customerId": "end-user-uuid",
      "status": "CONFIRMED",
      "network": "ETHEREUM"
    },
    "refundTxnHash": null
  }
}

​
Example 2: SELL_AND_PAY.DEPOSIT_WITHOUT_SELL_AND_PAY.REFUND_PROCESSING

Deposit received without an associated transaction (special structure): 
{
  "eventType": "SELL_AND_PAY.DEPOSIT_WITHOUT_SELL_AND_PAY.REFUND_PROCESSING",
  "issueDatetime": "2024-10-01T16:45:30.789012Z",
  "transaction": {
    "cryptoDeposit": {
      "id": "orphan-deposit-uuid",
      "txnId": "orphan-txn-uuid",
      "hash": "0x789xyz123abc...",
      "currencyCode": "USDC",
      "addressDestination": "0x9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c",
      "confirmationDate": "2024-10-01T16:40:00.000000Z",
      "amount": "50.00",
      "createdAt": "2024-10-01T16:38:00.000000Z",
      "customerId": "end-user-uuid",
      "status": "CONFIRMED",
      "network": "POLYGON"
    },
    "refundTxnHash": "0xrefund456def789..."
  }
}
For more information on configuring webhooks and validating signatures, please refer to the Webhooks Introduction.