> ## Documentation Index > Fetch the complete documentation index at: https://docs.capa.fi/llms.txt > Use this file to discover all available pages before exploring further. # 🏦 Transaction Events > Transaction events are notifications sent to partners when there are updates or changes related to transactions involving their users. These notifications help partners stay informed about the status of various transactions. *** ## Types of Transaction Events 1. **`COMPLETED_ON_RAMP`(Completed On-Ramp):** * **Description:** This event is triggered when an "on-ramp" transaction (converting fiat currency to cryptocurrency) has been successfully completed. **When this event fires, the crypto is already in the user's destination wallet.** * **Use Case:** The partner updates their system to reflect that the user's on-ramp transaction has been finalized. The crypto has been sent and confirmed on-chain. * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "COMPLETED_ON_RAMP", "externalUserId": "customer_1753744084024", "transactionId": "bf08852e-6b1a-444d-bf87-9a9f1837cfc5", "blockchain": "Polygon PoS", "cryptoCurrency": "USDC", "fiatCurrency": "MXN", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "fiatAmount": "10.00", "cryptoAmount": "0.578031", "exchangeRate": "17.300119008048114" } ``` 2. **`FIAT_RECEIVED_ON_RAMP`(Fiat Received On-Ramp):** * **Description:** This event is triggered when fiat currency has been received for an on-ramp transaction and the conversion process is starting. **The crypto has not been sent yet at this point.** * **Use Case:** The partner is informed that the user's fiat payment has been received and the process to convert it to cryptocurrency has begun. Do not treat this as a completed transaction. * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "FIAT_RECEIVED_ON_RAMP", "externalUserId": "customer_1753744084024", "transactionId": "bf08852e-6b1a-444d-bf87-9a9f1837cfc5", "firstName": "SATOSHI", "lastName": "NAKAMOTO" } ``` 3. **`COMPLETED_OFF_RAMP`(Completed Off-Ramp):** * **Description:** This event is triggered when an "off-ramp" transaction (converting cryptocurrency to fiat currency) has been successfully completed. * **Use Case:** The partner updates their system to reflect that the user's off-ramp transaction has been finalized, indicating the user has received their fiat currency. * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "COMPLETED_OFF_RAMP", "externalUserId": "customer_1765265674454", "transactionId": "3e6e0936-f714-4337-92d0-303dd9da5df5", "blockchain": "Polygon PoS", "cryptoCurrency": "USDC", "fiatCurrency": "MXN", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "cryptoAmount": "1.000000", "fiatAmount": "17.0799", "exchangeRate": "17.085723916631654" } ``` 4. **`CREATED_ON_RAMP`(Created On-Ramp):** * **Description:** This event is triggered when a new on-ramp transaction (fiat to cryptocurrency) has been initiated. * **Use Case:** The partner can record the initiation of a new on-ramp transaction and begin tracking its status. * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "CREATED_ON_RAMP", "externalUserId": "customer_1753744084024", "transactionId": "bf08852e-6b1a-444d-bf87-9a9f1837cfc5", "firstName": "SATOSHI", "lastName": "NAKAMOTO" } ``` 5. **`CRYPTO_RECEIVED_OFF_RAMP`(Crypto Received Off-Ramp):** * **Description:** This event is triggered when a partner's user has sent cryptocurrency to Capa's wallet, and Capa is starting the process of sending the equivalent fiat currency to the user's account with the partner. * **Use Case:** The partner is informed that the user has transferred cryptocurrency to Capa, and the process to exchange it for fiat currency and deposit it into the user’s account has begun. The partner can update their system to reflect this ongoing transaction status. * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "CRYPTO_RECEIVED_OFF_RAMP", "externalUserId": "customer_1765265674454", "transactionId": "3e6e0936-f714-4337-92d0-303dd9da5df5", "firstName": "SATOSHI", "lastName": "NAKAMOTO" } ``` 6. **`CREATED_OFF_RAMP`(Created Off-Ramp):** * **Description:** This event is triggered when a new off-ramp transaction (cryptocurrency to fiat) has been initiated. * **Use Case:** The partner can record the initiation of a new off-ramp transaction and begin tracking its status. * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "CREATED_OFF_RAMP", "externalUserId": "customer_1765265674454", "transactionId": "3e6e0936-f714-4337-92d0-303dd9da5df5", "firstName": "SATOSHI", "lastName": "NAKAMOTO" } ``` 7. **`CANCELLED_ON_RAMP`(Cancelled On-Ramp):** * **Description:** This event is triggered when an on-ramp transaction (fiat to cryptocurrency) has been cancelled. * **Use Case:** The partner can update their system to reflect that the user's on-ramp transaction has been cancelled. * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "CANCELLED_ON_RAMP", "externalUserId": "customer_1768865246072", "transactionId": "e4c0854f-d448-4e1c-bcaf-d6269e6736b3", "blockchain": "Polygon PoS", "cryptoCurrency": "USDC", "fiatCurrency": "MXN", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "fiatAmount": "10.0000", "cancellationReason": "USER_CANCELLED" } ``` 8. **`CANCELLED_OFF_RAMP`(Cancelled Off-Ramp):** * **Description:** This event is triggered when an off-ramp transaction (cryptocurrency to fiat) has been cancelled. * **Use Case:** The partner can update their system to reflect that the user's off-ramp transaction has been cancelled. * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "CANCELLED_OFF_RAMP", "externalUserId": "customer_1753744084024", "transactionId": "ce96ebb3-ace0-4ff6-8d26-baf9d77b44ba", "blockchain": "Polygon PoS", "cryptoCurrency": "USDC", "fiatCurrency": "MXN", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "cryptoAmount": "1.000000", "cancellationReason": "USER_CANCELLED" } ``` *** ## Cross Ramp Events Cross-ramp transactions convert between different fiat currencies. The following events are emitted in order during a cross-ramp transaction lifecycle: 9. **`CREATED_CROSS_RAMP`(created-cross-ramp):** * **Description:** This event is emitted when a cross-ramp transaction is created. * **Transaction Status:** `PENDING_FUNDS` * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "CREATED_CROSS_RAMP", "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015" } ``` 10. **`FUNDS_RECEIVED_CROSS_RAMP`(funds-received-cross-ramp):** * **Description:** This event is emitted when funds are received for the transaction. * **Status Transition:** `PENDING_FUNDS` β†’ `FUNDS_RECEIVED` * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "FUNDS_RECEIVED_CROSS_RAMP", "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015" } ``` 11. **`STARTED_PROCESSING_CROSS_RAMP`(started-processing-cross-ramp):** * **Description:** This event is emitted when processing starts. * **Status Transition:** `FUNDS_RECEIVED` β†’ `IN_PROGRESS` * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "STARTED_PROCESSING_CROSS_RAMP", "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015" } ``` 12. **`AWAITING_FUND_TRANSFER_CROSS_RAMP`(awaiting-fund-transfer-cross-ramp):** * **Description:** This event is emitted when the transaction is awaiting fund transfer. * **Status Transition:** `IN_PROGRESS` β†’ `AWAITING_FUND_TRANSFER` * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "AWAITING_FUND_TRANSFER_CROSS_RAMP", "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015" } ``` 13. **`COMPLETED_CROSS_RAMP`(completed-cross-ramp):** * **Description:** This event is emitted when the transaction completes. * **Status Transition:** `AWAITING_FUND_TRANSFER` β†’ `COMPLETED` * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "COMPLETED_CROSS_RAMP", "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015", "sourceCurrency": "USD", "targetCurrency": "EUR", "sourceAmount": "1000", "targetAmount": "920", "exchangeRate": "0.92" } ``` 14. **`CANCELLED_CROSS_RAMP`(cancelled-cross-ramp):** * **Description:** This event is emitted when the transaction is cancelled. This can occur at any stage of the transaction. * **Transaction Status:** `CANCELLED` * **Example Payload:** ```json JSON theme={null} { "type": "TRANSACTION", "event": "CANCELLED_CROSS_RAMP", "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab", "firstName": "SATOSHI", "lastName": "NAKAMOTO", "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015", "sourceCurrency": "USD", "targetCurrency": "EUR", "sourceAmount": "1000", "targetAmount": "920", "exchangeRate": "0.92", "cancellationReason": "User requested cancellation" } ``` *** ## Bank Account Events Bank account events are sent when the verification status of a user's bank account changes. These use `type: "USER"` instead of `type: "TRANSACTION"`. 15. **`VERIFIED_BANK_ACCOUNT`(Verified Bank Account):** * **Description:** This event is triggered when a user's bank account has been successfully verified (e.g., after a penny test for MX accounts). * **Example Payload:** ```json JSON theme={null} { "type": "USER", "event": "VERIFIED_BANK_ACCOUNT", "externalUserId": "customer_1753744084024", "userBankInfoId": "a1b2c3d4-5678-4abc-8def-1234567890ab" } ``` 16. **`REJECTED_BANK_ACCOUNT`(Rejected Bank Account):** * **Description:** This event is triggered when a user's bank account verification has been rejected. * **Example Payload:** ```json JSON theme={null} { "type": "USER", "event": "REJECTED_BANK_ACCOUNT", "externalUserId": "customer_1753744084024", "userBankInfoId": "a1b2c3d4-5678-4abc-8def-1234567890ab" } ``` *** ### Summary of Transaction Events These transaction events help partners automate their response to changes in transaction statuses: * **`COMPLETED_ON_RAMP`** and **`COMPLETED_OFF_RAMP`**: Confirm that a user's transaction has been successfully completed. * **`FIAT_RECEIVED_ON_RAMP`**: Indicates that fiat currency has been received and the conversion to cryptocurrency has begun. * **`CREATED_ON_RAMP`** and **`CREATED_OFF_RAMP`**: Notify the partner when a new transaction is initiated. * **`CANCELLED_ON_RAMP`** and **`CANCELLED_OFF_RAMP`**: Alert the partner that a user's transaction has been cancelled. * **`CRYPTO_RECEIVED_OFF_RAMP`**: Indicates that Capa has received cryptocurrency from a partner's user and the process of sending fiat currency to the user has started. **Cross Ramp Events:** * **`CREATED_CROSS_RAMP`**: Notifies when a cross-ramp transaction is created. * **`FUNDS_RECEIVED_CROSS_RAMP`**: Indicates funds have been received for the cross-ramp transaction. * **`STARTED_PROCESSING_CROSS_RAMP`**: Signals that processing has begun. * **`AWAITING_FUND_TRANSFER_CROSS_RAMP`**: Indicates the transaction is awaiting fund transfer. * **`COMPLETED_CROSS_RAMP`**: Confirms the cross-ramp transaction has been successfully completed. * **`CANCELLED_CROSS_RAMP`**: Alerts that the cross-ramp transaction has been cancelled. **Bank Account Events:** * **`VERIFIED_BANK_ACCOUNT`**: Confirms a user's bank account has been verified. * **`REJECTED_BANK_ACCOUNT`**: Alerts that a user's bank account verification was rejected. By processing these events, partners can ensure their systems are up-to-date with the latest transaction statuses and take appropriate actions to manage user interactions and maintain accurate records.