Transactions

Overview

A transaction in CrissCross represents the complete lifecycle of a payment event. It encompasses all payment attempts, refunds, and adjustments 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:

   1
   {
   2
     "merchantId": "YOUR_MERCHANT_ID",
   3
     "merchantReference": "ORDER12345",
   4
     "amount": 15000,
   5
     "currency": "NGN",
   6
     "integrationType": "hosted",
   7
     "redirectUrl": "https://merchant.com/redirect",
   8
     "payerDetails": {
   9
       "emailAddress": "[email protected]",
   10
       "location": "NGA",
   11
       "fullName": "Chinwe Okafor",
   12
       "phoneNumber": "08012345678"
   13
     }
   14
   }

   Example Response:

   1
   {
   2
     "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
   3
     "paymentLink": "https://crisscross.money/checkout/0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a"
   4
   }

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:

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

   Example Response:

   1
   {
   2
     "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
   3
     "status": "AUTHORIZED",
   4
     "message": "Authorized"
   5
   }

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:

   1
   {
   2
     "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
   3
     "status": "SETTLED",
   4
     "message": "Settled"
   5
   }

5. Refunds and Adjustments:

   • If necessary, refunds or adjustments can be processed using the /payment/payments/{paymentId}/refund endpoint (where paymentId corresponds to the transactionId in the transaction-based model).
   • Adjustments to the authorized amount can be made using the /payments/{id}/adjust-authorization endpoint.

   Example Refund Request:

   1
   {
   2
     "amount": 3500,
   3
     "orderId": "ORDER_987654321",
   4
     "reason": "Customer returned the item"
   5
   }

   Example Refund Response:

   1
   {
   2
     "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
   3
     "status": "PARTIALLY_SETTLED",
   4
     "message": "Refund processed"
   5
   }

6. Completion:

   • The transaction is completed once all payment attempts are successful or the payment is cancelled, and any necessary refunds or adjustments are processed.

Example Transaction Response

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

1
{
2
  "currentState": "COMPLETED",
3
  "previousStates": ["PENDING", "PROCESSING"],
4
  "processor": "Processor_A",
5
  "merchantName": "Acme Inc",
6
  "transactionId": "txn_1048576",
7
  "amount": 20000,
8
  "transactionType": "payment",
9
  "paymentMethodId": "card",
10
  "currency": "USD",
11
  "merchantReference": "ORDER_001",
12
  "transactionStates": [
13
    {
14
      "state": "PENDING",
15
      "timestamp": "2024-10-17T12:00:00Z"
16
    },
17
    {
18
      "state": "PROCESSING",
19
      "timestamp": "2024-10-17T12:02:00Z"
20
    },
21
    {
22
      "state": "COMPLETED",
23
      "timestamp": "2024-10-17T12:05:00Z"
24
    }
25
  ],
26
  "paymentAttributes": {
27
    "channel": "web"
28
  },
29
  "identifiers": {
30
    "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a"
31
  },
32
  "paymentInstrument": {
33
    "brand": "Visa",
34
    "last4": "4242",
35
    "expiryMonth": "12",
36
    "expiryYear": "2026"
37
  },
38
  "processorReference": "PROC-123456",
39
  "financialTransactionReference": "FIN-789012",
40
  "currentAttemptId": "att_002"
41
}

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.