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

# Payments

> A detailed overview of payment attempts and how they are handled.

### Overview

A **payment** refers to an individual attempt to process a charge against a specific payment method. Each payment attempt is a distinct operation that may succeed or fail independently. A single transaction can involve multiple payment attempts if retries are required.

For more details on initiating payments, refer to the [Initiate Payment API](/api-reference/collect/payments/payment-initiation/create-checkout-session).

---

### Payment Attempts Explained

* **Single Attempt**: A simple one-time payment with no retries.
* **Multiple Attempts**: If a payment fails, the platform automatically retries using alternative processors or payment methods (if configured).

#### Payment Attempt States:

1. **Initiated**: Payment request is sent to the payment processor.
2. **Pending**: Payment is under review or awaiting customer action (e.g., 3D Secure).
3. **Authorized**: Payment was approved but not yet captured.
4. **Captured**: Funds have been transferred from the customer.
5. **Failed**: Payment attempt failed, and the platform may retry.
6. **Refunded**: Payment was refunded (full or partial).

For more information on payment states, see the [Payments API reference](/api-reference/collect/payments).

---

### Payment Methods

The platform supports various payment methods, including:

* **Credit/Debit Cards**: Securely processed through tokenized transactions.
* **Bank Transfers**: Supports real-time and batch transfers.
* **Mobile Money**
* **Digital Wallets**: PayPal, Apple Pay, and others. See [Digital Wallets](/payment-method-digital-wallets).

The payment methods available to you are configured on your account during onboarding; on hosted checkout the customer automatically sees the methods valid for their location.

---

### Example Payment Payload

```json
{
  "attemptId": "attempt_01",
  "transactionId": "1234567890",
  "processor": "Processor_A",
  "status": "COMPLETED",
  "amount": 10000,
  "currency": "USD",
  "paymentMethod": {
    "type": "card",
    "cardDetails": {
      "brand": "Visa",
      "last4": "4242",
      "expiryMonth": "12",
      "expiryYear": "2026"
    }
  },
  "timestamp": "2024-10-17T12:05:00Z"
}
```

For the full schema, refer to the [Payment Initiate Request Schema](https://api.crisscross.money/v1/components/schemas/PaymentInitiateRequest).

---

### Handling Payment Failures

The platform retries failed payment attempts automatically. Merchants can configure retry rules to maximize success rates. In cases where retries are exhausted, a webhook notification will be sent to the merchant for further action.

For more details on handling failures, see the [Error Response Schema](https://api.crisscross.money/v1/components/schemas/ErrorResponse).

---

### Payment Capture and Refunds

* **Capture**: Payments must be captured to finalize the transfer of funds.
* **Refunds**: Payments can be refunded (partially or fully) based on merchant policies.

To refund a payment, use the [Refund a Payment API](https://api.crisscross.money/v1/payment/\{transactionId}/refund). Refunds are issued against the original payment and accept an optional `refundValue` object (`minorAmount` plus ISO 4217 `currency`) — omit it for a full refund; see [Full and Partial Refunds](full-and-partial-refunds) for details.

---

### Cancelling a Payment

Cancellation is split across two endpoints depending on whether you want to cancel an entire checkout session or a single transaction.

#### Cancel a session

`POST /checkout/session/cancel` takes a `sessionId` and cancels the whole session. The session is locked against any further payment attempts, and every in-flight transaction linked to the session is cancelled in the same call. Transactions already in a terminal state (settled, failed, refunded) are not affected.

If one of those in-flight transactions is being processed by a provider that does not support cancelling an in-progress transaction, the session enters the **`PENDING_CANCELLATION`** state. While in this state:

* No further payment attempts can be initiated against the session.
* The session is **not** considered fully cancelled — it only moves to `CANCELLED` once the outstanding transaction reaches its own terminal state.

The response returns the session's resulting `status` (`CANCELLED` or `PENDING_CANCELLATION`), the transactions that were successfully cancelled in `cancelledTransactionIds`, and any unstoppable in-flight transactions in `pendingTransactionIds`.

**Clean cancel** — every in-flight transaction was cancellable, so the session reaches `CANCELLED` immediately:

```json
{
  "sessionId": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70",
  "status": "CANCELLED",
  "message": "Session cancelled. 1 in-flight transaction was cancelled as part of this call.",
  "cancelledTransactionIds": ["01951c8a-8b4c-7d2a-8f1e-5d6c7b8a9e10"],
  "pendingTransactionIds": []
}
```

**Pending cancellation** — one of the in-flight transactions belongs to a provider that does not support in-process cancellation. The session is locked but not yet terminal; it will move to `CANCELLED` once the listed transaction reaches its own terminal state on the rail:

```json
{
  "sessionId": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70",
  "status": "PENDING_CANCELLATION",
  "message": "Session locked. Awaiting terminal state on 1 in-flight transaction whose provider does not support in-process cancellation.",
  "cancelledTransactionIds": ["01951c8a-8b4c-7d2a-8f1e-5d6c7b8a9e10"],
  "pendingTransactionIds": ["01951c8a-ad6f-7b1c-a2d3-7f8e9d0c1b32"]
}
```

#### Cancel a transaction

`POST /payment/{transactionId}/cancel` cancels a single transaction by its id. No session id is required — the transaction id is sufficient. The transaction's session and any other transactions on it remain active.

A transaction can only be cancelled while it is in a non-terminal state and while its originating provider supports cancelling an in-progress transaction. Otherwise the call returns `409`.

---

### Security and Compliance

* **PCI Compliance**: Merchants must ensure PCI compliance when handling card data directly.
* **3D Secure Authentication**: The platform supports 3D Secure to reduce fraud.

For more information on security, refer to the Security and Compliance Documentation.

---

### External Resources

For a complete list of API operations and schemas, visit the API Documentation.

> Managing individual payment attempts