Get order

[GET] /api/v2/order

Gets an order by its ID or merchant order params.

Request query params type:

type QueryParams = {
    orderId?: string,// optional
    orderParams?: string,// optional
}

Request URL example:

GET /api/v2/order?orderId=69281d944a1db009177f0198

Response type:

type Response = {
  _id: string,
  countryIsoCode: string;
  userId: string;
  userEmail: string;
  merchantOrderParams?: string;
  status: OrderStatus;
  deposit: {
    paymentChannel: PaymentChannel;
    currencyType: CurrencyType;
    currencyCode: string;
    currencyDetails: OrderCurrencyDetails;
    cashout: Cashout;
    providedFieldsToCreateOrder: Record<string, string>;
    transferInstructions: TransferInstructions;
  },
  payout: {
    paymentChannel: PaymentChannel;
    currencyType: CurrencyType;
    currencyCode: string;
    currencyDetails: OrderCurrencyDetails;
    cashout: Cashout;
    providedFieldsToCreateOrder: Record<string, string>;
    transaction?: {
      meta?: {
        transactionHash?: string;
      }
    }
  },
  createdAt: Date;
  updatedAt: Date;
  expiresAt: Date;
  statusChangeLogs: { oldStatus: OrderStatus; newStatus: OrderStatus; date: Date; }[]
}

Response example:

{
    "_id": "69283d079061f4031ad1ba03",
    "countryIsoCode": "KE",
    "userId": "69283c0518613bc9de730cb4",
    "userEmail": "[email protected]",
    "status": "payout_successful",
    "deposit": {
        "paymentChannel": "mobile_money",
        "currencyType": "fiat",
        "currencyCode": "KES",
        "currencyDetails": {
            "countryIsoCode": "KE",
            "carrier": {
                "code": "ke_safaricom",
                "name": "Safaricom Kenya",
                "_id": "618e43914f57e07d255ff353"
            }
        },
        "cashout": {
            "amountBeforeFees": 135,
            "amountAfterFees": 130,
            "amountBeforeFeesUsd": 1.037823,
            "amountAfterFeesUsd": 0.999385,
            "chargedFees": [
                {
                    "id": "service_fee",
                    "type": "percentage",
                    "recipient": "platform",
                    "amount": 3.38
                },
                {
                    "id": "merchant_fee",
                    "type": "percentage",
                    "recipient": "merchant",
                    "amount": 1.35
                }
            ],
            "chargedFeesUsd": [
                {
                    "id": "service_fee",
                    "type": "percentage",
                    "recipient": "platform",
                    "amount": 0.025984
                },
                {
                    "id": "merchant_fee",
                    "type": "percentage",
                    "recipient": "merchant",
                    "amount": 0.010378
                }
            ],
            "totalChargedFees": 4.73,
            "totalChargedFeesUsd": 0.036362,
            "exchangeRate": 130.08,
            "exchangeRateAfterFees": 135.0831,
            "chargedFeesPerRecipient": {
                "platform": 3.38,
                "merchant": 1.35
            },
            "chargedFeesPerRecipientUsd": {
                "platform": 0.025984,
                "merchant": 0.010378
            },
            "feeSettings": [
                {
                    "id": "service_fee",
                    "recipient": "platform",
                    "type": "percentage",
                    "value": 2.5,
                    "min": 0,
                    "max": "Infinity"
                },
                {
                    "id": "merchant_fee",
                    "recipient": "merchant",
                    "type": "percentage",
                    "value": 1,
                    "min": 0,
                    "max": "Infinity"
                }
            ]
        },
        "providedFieldsToCreateOrder": {
            "phoneNumber": "2348012345678",
            "carrierCode": "ke_safaricom"
        },
        "providedFieldsToConfirmOrder": {},
        "transferInstructions": {
            "type": "otp_stk_push",
            "intermediateActionAttempts": 2,
            "intermediateActionMaxAttempts": 3,
            "intermediateActionButtonText": "Verify OTP code",
            "intermediateActionNextAttemptAvailableAt": "2025-11-27T12:00:14.390Z",
            "intermediateActionTimeoutMs": 30000,
            "isIntermediateActionAvailable": true,
            "forcePhoneNumberVerification": true,
            "fieldsForIntermediateAction": [
                {
                    "key": "otpCode",
                    "label": "OTP code",
                    "type": "number",
                    "required": true
                }
            ],
            "instructionsText": "It is a sandbox offer. Use 123456 as OTP code and confirm the transfer from your side and system will automatically confirm the transfer within 1 minute.",
            "warningText": "Non-confirmed orders will be automatically canceled after 5 minutes.",
            "transferDetails": [
                {
                    "id": "amountToSend",
                    "label": "Amount to send",
                    "value": "135"
                }
            ],
            "fieldsToConfirmOrder": [],
            "intermediateActionRequired": true,
            "intermediateActionExecuted": true,
            "otpChannel": "sms"
        }
    },
    "payout": {
        "paymentChannel": "crypto",
        "currencyType": "crypto",
        "currencyCode": "POLYGON_USDT",
        "currencyDetails": {
            "network": "POLYGON",
            "asset": "USDT",
            "contractAddress": "0x3b3a06b48119c035a2e86afdb69d9ad930643b3d"
        },
        "cashout": {
            "amountBeforeFees": 1.000645,
            "amountAfterFees": 1,
            "amountBeforeFeesUsd": 1.000645,
            "amountAfterFeesUsd": 1,
            "chargedFees": [
                {
                    "id": "gas",
                    "type": "flat_amount",
                    "recipient": "blockchain",
                    "amount": 0.000645
                }
            ],
            "chargedFeesUsd": [
                {
                    "id": "gas",
                    "type": "flat_amount",
                    "recipient": "blockchain",
                    "amount": 0.000645
                }
            ],
            "totalChargedFees": 0.000645,
            "totalChargedFeesUsd": 0.000645,
            "exchangeRate": 1,
            "exchangeRateAfterFees": 1.0006,
            "chargedFeesPerRecipient": {
                "blockchain": 0.000645
            },
            "chargedFeesPerRecipientUsd": {
                "blockchain": 0.000645,
                "platform": 0.025984,
                "merchant": 0.010378
            },
            "feeSettings": [
                {
                    "id": "gas",
                    "recipient": "blockchain",
                    "type": "flat_amount",
                    "value": 0.000645,
                    "min": 0,
                    "max": "Infinity"
                }
            ]
        },
        "providedFieldsToCreateOrder": {
            "blockchainWalletAddress": "0x5b7ae3c6c87f4a3f94b35c77233b13191ebfad20"
        },
        "transaction": {
            "meta": {
                "transactionHash": "0xe168c39bf7165c0eaa88e4df1e21e987666e44f11f2bea6f9be1c145f382dade"
            }
        }
    },
    "statusChangeLogs": [
        {
            "oldStatus": "deposit_awaiting",
            "newStatus": "deposit_validating",
            "date": "2025-11-27T12:01:43.660Z"
        },
        {
            "oldStatus": "deposit_validating",
            "newStatus": "deposit_successful",
            "date": "2025-11-27T12:02:00.770Z"
        },
        {
            "oldStatus": "deposit_successful",
            "newStatus": "payout_pending",
            "date": "2025-11-27T12:02:01.306Z"
        },
        {
            "oldStatus": "payout_pending",
            "newStatus": "payout_successful",
            "date": "2025-11-27T12:02:19.053Z"
        }
    ],
    "createdAt": "2025-11-27T11:59:03.754Z",
    "updatedAt": "2025-11-27T12:02:19.124Z",
    "expiresAt": "2025-11-27T12:04:03.673Z"
}