> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.crisscross.money/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.