Atlas Documentation
GuidesAPI ReferenceChangelog

Balances & Transactions

Check your business wallet balance and look up transaction history across all Atlas products.

Atlas gives you two ways to monitor your account: a live snapshot of your wallet balance, and a searchable history of every transaction recorded against your business, including payouts, payins, checkout, and fees.

Checking your wallet balance

To retrieve the balance available for settlements and payouts, make a GET request to the Get Wallet Balance endpoint. It takes no parameters.

curl -X GET "https://atlas.tryduplo.com/api/v1/wallet/balance" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Accept: application/json"

On a successful request, you should receive a response similar to the one below:

JSON
{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2026-04-16 23:06:50.663",
  "message": "Fetch Wallet details.",
  "statusCode": 200,
  "data": {
    "availableBalance": {
      "value": 20000,
      "currency": "NGN",
      "formatted": "NGN 200.00"
    }
  }
}

The availableBalance reflects the parent currency of your onboarding country (for example, NGN for businesses onboarded in Nigeria) and is the balance available for settlements and payouts.

Note

This endpoint only returns the balance in your onboarding country's parent currency. If you need balances in other currencies, for example after running FX swaps, use the FX Wallet Balances endpoint instead.

Listing transactions

To retrieve transactions for your business, including payout, payin, checkout, and fee-related records, make a GET request to the List Business Transactions endpoint.

The supported query parameters are:

ParameterDescription
pageUsed for pagination, this specifies which page of results to retrieve.
limitUsed for pagination, this controls how many records are returned per page.
searchIncluding this query parameter allows you to filter for transactions whose reference matches a search term, such as the prefix TRN_.
statusIncluding this query parameter allows you to filter for transactions in a specific status, such as successful.
channelIncluding this query parameter allows you to filter for transactions from a specific product channel, such as swap, bank_transfer, or checkout. It is useful for reconciliation flows that need to isolate activity from a single product.
curl -X GET "https://atlas.tryduplo.com/api/v1/transaction?page=1&limit=15&status=successful" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Accept: application/json"

On a successful request, you should receive a response similar to the one below:

JSON
{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2026-04-16 23:06:50.663",
  "message": "All business transactions fetched successfully.",
  "statusCode": 200,
  "data": [
    {
      "id": "019d4f46-e9cf-705a-93e7-d13b1208ad08",
      "type": "credit",
      "sourceReference": null,
      "parentTransactionReference": null,
      "reference": "TRN_XqLkjzm8ZyjM",
      "status": "successful",
      "amount": {
        "value": 10000,
        "currency": "NGN",
        "formatted": "NGN10000"
      },
      "balanceBefore": {
        "value": 179900,
        "currency": "NGN",
        "formatted": "NGN179900"
      },
      "balanceAfter": {
        "value": 189900,
        "currency": "NGN",
        "formatted": "NGN189900"
      },
      "createdAt": "02/04/2026 06:38pm",
      "customer": null,
      "paymentLink": null
    }
  ]
}

Each item's reference is the Atlas-generated transaction reference, which you can use to fetch the full record with the endpoint below. The type field tells you whether the entry is a credit or debit against your wallet, and balanceBefore/balanceAfter show the wallet balance on either side of the transaction. The customer and paymentLink fields are populated when the transaction originated from a customer or a payment link, and are null otherwise.

Fetching a transaction by reference

If you already have a transaction reference, for example from a webhook payload, use the Get Transaction By Reference endpoint to fetch the full record directly.

curl -X GET "https://atlas.tryduplo.com/api/v1/transaction/find-by-reference/TRN_S004BNTM9TLO" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Accept: application/json"

On a successful request, you should receive a response similar to the one below:

JSON
{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2026-04-16 23:06:50.663",
  "message": "Business transaction fetched successfully.",
  "statusCode": 200,
  "data": {
    "id": "019e87eb-37ee-72d9-8856-8f14b0164616",
    "type": "credit",
    "sourceReference": null,
    "parentTransactionReference": null,
    "reference": "TRN_S004BNTM9TLO",
    "status": "successful",
    "amount": {
      "value": 4500,
      "currency": "NGN",
      "formatted": "NGN4500"
    },
    "balanceBefore": {
      "value": 0,
      "currency": "NGN",
      "formatted": "NGN0"
    },
    "balanceAfter": {
      "value": 0,
      "currency": "NGN",
      "formatted": "NGN0"
    },
    "createdAt": "02/06/2026 11:39am",
    "fee": [
      {
        "id": "019e87eb-9673-73af-ad9b-0c46349bd132",
        "type": "debit",
        "sourceReference": null,
        "parentTransactionReference": "TRN_S004BNTM9TLO",
        "reference": "TRN_F8IHUDBLKVRO",
        "status": "successful",
        "amount": {
          "value": 67.5,
          "currency": "NGN",
          "formatted": "NGN67.5"
        },
        "balanceBefore": { "value": 0, "currency": "NGN", "formatted": "NGN0" },
        "balanceAfter": { "value": 0, "currency": "NGN", "formatted": "NGN0" },
        "createdAt": "02/06/2026 11:40am",
        "customer": null,
        "paymentLink": null
      }
    ],
    "customer": {
      "id": "019e8783-05e4-70ed-8946-e0ab476f4b32",
      "firstName": "Glory",
      "lastName": "Amuah",
      "email": "glory@tryduplo.com",
      "phoneNumber": null,
      "reference": "dp_cust_dr7qtjtzqpsjlis",
      "businessState": "test",
      "isBlacklisted": false,
      "hasWallet": false,
      "hasNrsCustomer": false,
      "wallet": [],
      "status": "ACTIVE",
      "source": "API",
      "createdAt": "2026-06-02 09:46:11"
    },
    "paymentLink": {
      "id": "019e8789-a944-7219-9587-32a73edeae96",
      "createdAt": "2026-06-02 09:53:26",
      "linkName": "Card payment",
      "linkUrl": "https://atlas-app.dev.tryduplo.com/pay/PLK_TELDU9RNNIJU",
      "amount": { "value": 0, "currency": "NGN", "formatted": "NGN0" },
      "status": "Active",
      "narration": "Card payment",
      "businessState": "test",
      "reference": "PLK_TELDU9RNNIJU",
      "sourceReference": null,
      "feeBearer": "MERCHANT"
    }
  }
}

The fee array lists any fee debits charged against the transaction, each with its own reference you can look up independently. The customer and paymentLink objects give you the full context behind the transaction without needing a second API call.

How is this guide?

Last updated on

Swapping between Currency Pairs

Learn how to convert funds between supported currency pairs using the Atlas Swaps API.

E-Invoicing

Validate and digitally sign your invoices to stay compliant with the Nigeria Revenue Service (NRS)

On this page

Checking your wallet balanceListing transactionsFetching a transaction by referenceRelated guides