🏦 Transaction Events

Types of Transaction Events

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
  { "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" }
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
  { "type": "TRANSACTION", "event": "FIAT_RECEIVED_ON_RAMP", "externalUserId": "customer_1753744084024", "transactionId": "bf08852e-6b1a-444d-bf87-9a9f1837cfc5", "firstName": "SATOSHI", "lastName": "NAKAMOTO" }

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

{
  "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"
}

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
  { "type": "TRANSACTION", "event": "CREATED_ON_RAMP", "externalUserId": "customer_1753744084024", "transactionId": "bf08852e-6b1a-444d-bf87-9a9f1837cfc5", "firstName": "SATOSHI", "lastName": "NAKAMOTO" }
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
  { "type": "TRANSACTION", "event": "CRYPTO_RECEIVED_OFF_RAMP", "externalUserId": "customer_1765265674454", "transactionId": "3e6e0936-f714-4337-92d0-303dd9da5df5", "firstName": "SATOSHI", "lastName": "NAKAMOTO" }
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
  { "type": "TRANSACTION", "event": "CREATED_OFF_RAMP", "externalUserId": "customer_1765265674454", "transactionId": "3e6e0936-f714-4337-92d0-303dd9da5df5", "firstName": "SATOSHI", "lastName": "NAKAMOTO" }

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

{
  "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"
}

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

{
  "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:

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

{
  "type": "TRANSACTION",
  "event": "CREATED_CROSS_RAMP",
  "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab",
  "userId": "user-12345",
  "partnerId": "partner-67890",
  "firstName": "SATOSHI",
  "lastName": "NAKAMOTO",
  "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015"
}

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

{
  "type": "TRANSACTION",
  "event": "FUNDS_RECEIVED_CROSS_RAMP",
  "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab",
  "userId": "user-12345",
  "partnerId": "partner-67890",
  "firstName": "SATOSHI",
  "lastName": "NAKAMOTO",
  "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015"
}

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

{
  "type": "TRANSACTION",
  "event": "STARTED_PROCESSING_CROSS_RAMP",
  "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab",
  "userId": "user-12345",
  "partnerId": "partner-67890",
  "firstName": "SATOSHI",
  "lastName": "NAKAMOTO",
  "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015"
}

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

{
  "type": "TRANSACTION",
  "event": "AWAITING_FUND_TRANSFER_CROSS_RAMP",
  "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab",
  "userId": "user-12345",
  "partnerId": "partner-67890",
  "firstName": "SATOSHI",
  "lastName": "NAKAMOTO",
  "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015"
}

COMPLETED_CROSS_RAMP(completed-cross-ramp):

Description: This event is emitted when the transaction completes.
Status Transition: AWAITING_FUND_TRANSFER → COMPLETED

Example Payload:

JSON

{
  "type": "TRANSACTION",
  "event": "COMPLETED_CROSS_RAMP",
  "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab",
  "userId": "user-12345",
  "partnerId": "partner-67890",
  "firstName": "SATOSHI",
  "lastName": "NAKAMOTO",
  "externalUserId": "4e6c9c80-6c4a-4bfe-8f70-3a0e4db6d015",
  "sourceCurrency": "USD",
  "targetCurrency": "EUR",
  "sourceAmount": "1000",
  "targetAmount": "920",
  "exchangeRate": "0.92"
}

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

{
  "type": "TRANSACTION",
  "event": "CANCELLED_CROSS_RAMP",
  "transactionId": "a1b2c3d4-5678-4abc-8def-1234567890ab",
  "userId": "user-12345",
  "partnerId": "partner-67890",
  "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".

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
  { "type": "USER", "event": "VERIFIED_BANK_ACCOUNT", "externalUserId": "customer_1753744084024", "userBankInfoId": "a1b2c3d4-5678-4abc-8def-1234567890ab" }

REJECTED_BANK_ACCOUNT(Rejected Bank Account):

Description: This event is triggered when a user’s bank account verification has been rejected.

Example Payload:

JSON

{
  "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.

Documentation

​Types of Transaction Events

​Cross Ramp Events

​Bank Account Events

​Summary of Transaction Events

Types of Transaction Events

Cross Ramp Events

Bank Account Events

Summary of Transaction Events