Skip to main content

Retrieve a Transaction

You can retrieve the detailed status and information of a specific transaction by using Modem Pay's H2H Transactions API. This is useful for tracking payment statuses, verifying transfers, or building transaction history in your application.

Endpoint​

Use the following endpoint to fetch a transaction by its unique id or reference (both are accepted):

GET https://api.modempay.com/h2h/v1/transactions/:id_or_reference
  • Replace :id_or_reference with either the transaction id (e.g., 3a703077-d0c2-4d44-a304-adbc37c84879) or your custom reference value (e.g., cos-232hn5spg8v48).

Request Example​

curl -X GET "https://api.modempay.com/h2h/v1/transactions/3a703077-d0c2-4d44-a304-adbc37c84879" \
  -H "Authorization: Bearer YOUR_API_KEY"

Or using a custom reference:

curl -X GET "https://api.modempay.com/h2h/v1/transactions/cos-232hn5spg8v48" \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful Response​

If the transaction is found, you'll receive a JSON response with full details. A typical transaction response looks like:

{
  "id": "3a703077-d0c2-4d44-a304-adbc37c84879",
  "payment_intent_id": "cd33b10e-cb8a-48e5-a5d6-e2c0e659028e",
  "amount": 11,
  "currency": "GMD",
  "source": "online",
  "status": "completed",
  "transaction_reference": "MP-20260217-131523-78C3C7D6",
  "reference": "cos-232hn5spg8v48",
  "payment_method": "wave",
  "risk_score": {},
  "payment_method_id": "d8ec7405-0485-47aa-b58e-ab6d173ba4ef",
  "customer": null,
  "customer_name": null,
  "customer_phone": null,
  "customer_email": null,
  "payment_account": ".... 3716",
  "metadata": {...},
  "payment_metadata": {},
  "type": "payment",
  "custom_fields_values": {},
  "payment_link_id": null,
  "account_id": "34e12f5f-3ecc-4b5e-bfda-07a3c74763ae",
  "business_id": "120c298f-b736-49c1-8220-8a8c84a5d8f3",
  "test_mode": false,
  "failure_reason": null,
  "transaction_fee": 1,
  "transaction_fee_type": "business",
  "coupon": null,
  "discount": null,
  "sub_total": null,
  "requires_auth": false,
  "auth_length": 0,
  "auth_mode": "confirm",
  "_dnc": {},
  "launch_url": "...",
  "openExternal": true,
  "notes": null,
  "edited": false,
  "paid_date": null,
  "terminal_id": null,
  "createdAt": "2026-02-17T13:15:23.636Z",
  "updatedAt": "2026-02-17T13:15:49.151Z",
  "PaymentGateway": {...},
  "Business": {...}
}
  • The fields above are for illustration; your response will include all available data about the transaction.

Error Handling​

If the transaction is not found, you'll receive a standard error response:

{
  "message": "Transaction not found"
}

You may also receive other error messages if the request is invalid or your API key is missing/incorrect.

Notes​

  • You can use either the Modem Pay id or your own reference to search for a transaction.
  • Always keep your API key secure and do not share it publicly.
  • Refer to the Errors documentation for details on error formats and troubleshooting.

If you need to retrieve a list of transactions or filter by criteria (e.g., date range, type), please contact support or refer to future API updates.