> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/transactions/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Transactions

> A detailed overview of how transactions are managed and processed through the CrissCross platform.

### Overview

A **transaction** in CrissCross represents the complete lifecycle of a payment event. It encompasses all payment attempts and refunds associated with a specific payment flow. Understanding how CrissCross handles transactions helps merchants track payments, retries, and outcomes.

### Transaction Lifecycle

A transaction in CrissCross can include multiple states as part of its journey. The following flow outlines the typical stages of a transaction when it makes use of the Hosted Checkout:

1. **Initiation**:

   * The transaction starts when you create a checkout session, then initiate a payment (transaction) against that session.
   * Use `POST /v1/checkout/session` to create a session, then `POST /v1/payment` to initiate the transaction.

   **Example Request:**

   ```json
   {
     "merchantId": "YOUR_MERCHANT_ID",
     "merchantReference": "ORDER12345",
     "amount": 15000,
     "currency": "NGN",
     "integrationType": "hosted",
     "redirectUrl": "https://merchant.com/redirect",
     "payerDetails": {
       "emailAddress": "chinwe.okafor@example.com",
       "location": "NGA",
       "fullName": "Chinwe Okafor",
       "phoneNumber": "08012345678"
     }
   }
   ```

   **Example Response:**

   ```json
   {
     "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
     "paymentLink": "https://checkout.payos.money/session/0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a?signature=kRe8vQZ2mXpL7nT4wYbHs1JdA0uCgFiO6ExNq3ZrPyM"
   }
   ```

2. **Payment Attempt**:
   * After creating the checkout session, the merchant renders the hosted checkout to the payer.
   * The payer interacts with the hosted checkout, selecting one of the available payment methods. These methods are displayed based on configurable rules in the Rules Engine.
   * This stage involves the payer engaging with the checkout interface, selecting their preferred payment method, and entering any necessary details specific to that method.
   * In cases where the merchant is choosing to make use of direct integration, they will initiate a transaction using `POST /v1/payment` and provide `paymentMethodId` plus method-specific `paymentDetails`.

3. **Authorization**:

   * The payment is authorized, and funds are reserved on the customer's payment method. In some cases additional interaction may be required from the payer, and in these cases the Hosted Checkout will handle all interactions. In cases where a merchant is making use of direct integration, they might need to surface the userInteractionRequired URL to the payer.
   * Use the `GET /v1/payment/{transactionId}` endpoint to check the status of a transaction.

   **Example Request:**

   ```bash
   curl --request GET 'https://api.crisscross.money/v1/payment/9f3e4b2c-1a6d-4e88-9d3a-ff1234567890' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
   ```

   **Example Response:**

   ```json
   {
     "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
     "status": "AUTHORIZED",
     "message": "Authorized"
   }
   ```

4. **Settlement**:

   * Once authorized, the payment may move into a settled state, and funds are transferred to the merchant's account.
   * The status can be checked using the same endpoint as for authorization.

   **Example Response:**

   ```json
   {
     "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
     "status": "SETTLED",
     "message": "Settled"
   }
   ```

5. **Refunds**:

   * Refunds are issued against the original payment using the `POST /v1/payment/{transactionId}/refund` endpoint. Pass an optional `refundValue` object (`minorAmount` in minor units, ISO 4217 `currency`) — omit it for a full refund — and an optional `reason`.
   * A refund is itself a transaction, so the response is the standard transaction record (`transactionId`, `status`, `message`, plus `merchantReference` and `identifiers` copied from the original payment). There is no separate refund object.
   * Refunds are processed asynchronously: the refund transaction is created in a non-terminal (pending) state. Poll `GET /v1/payment/{transactionId}` with the refund's `transactionId`, or subscribe to the `refund.*` webhooks (`refund.completed`, `refund.failed`, `refund.errored`, `refund.cancelled`) to observe completion.

   **Example Refund Request:**

   ```json
   {
     "refundValue": {
       "minorAmount": 3500,
       "currency": "NGN"
     },
     "reason": "Customer returned the item"
   }
   ```

   **Example Refund Response:**

   ```json
   {
     "status": "PENDING",
     "transactionId": "01951c8a-9d5e-7f3b-bc4f-6e7d8c9b0a21",
     "message": "Refund accepted and queued for processing.",
     "merchantReference": "order-4021",
     "identifiers": {
       "sessionId": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70"
     }
   }
   ```

6. **Completion**:
   * The transaction is completed once all payment attempts are successful or the payment is cancelled, and any necessary refunds are processed.

### Example Transaction Response

Here's an example transaction object as returned by the **List Payments (Transactions)** endpoint:

```json
{
  "currentState": "COMPLETED",
  "previousStates": ["PENDING", "PROCESSING"],
  "processor": "Processor_A",
  "merchantName": "Acme Inc",
  "transactionId": "txn_1048576",
  "amount": 20000,
  "transactionType": "payment",
  "paymentMethodId": "card",
  "currency": "USD",
  "merchantReference": "ORDER_001",
  "transactionStates": [
    {
      "state": "PENDING",
      "timestamp": "2024-10-17T12:00:00Z"
    },
    {
      "state": "PROCESSING",
      "timestamp": "2024-10-17T12:02:00Z"
    },
    {
      "state": "COMPLETED",
      "timestamp": "2024-10-17T12:05:00Z"
    }
  ],
  "paymentAttributes": {
    "channel": "web"
  },
  "identifiers": {
    "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a"
  },
  "paymentInstrument": {
    "brand": "Visa",
    "last4": "4242",
    "expiryMonth": "12",
    "expiryYear": "2026"
  },
  "processorReference": "PROC-123456",
  "financialTransactionReference": "FIN-789012",
  "currentAttemptId": "att_002"
}
```

### Monitoring and Reporting

CrissCross provides detailed logs and dashboards to monitor transaction statuses and identify any issues in the payment flow. Merchants can use these tools to track retries, cancellations, and refunds within a transaction.

### Authentication and Security

All transaction-related API calls require OAuth 2.0 authentication. Ensure that your access token is valid and included in the `Authorization` header of your requests. Refer to the [Authentication Guide](#) for more details on setting up and managing your OAuth 2.0 credentials.

> Understanding the lifecycle of a transaction