Retrieve and manage billing transactions

Learn how to retrieve, filter, and sort billing transactions using the Billing Transactions API.

The Billing Transactions API allows you to retrieve billing transaction data using GraphQL queries. You can apply filters, sorting, and pagination to refine results and optimise response times.

---

Understanding the API workflow

To retrieve billing transactions, you will:

1. Obtain an API token for authentication.
2. Construct a GraphQL request with the necessary filters (e.g., date range, transaction ID).
3. Send a POST request to the API endpoint.
4. Receive and process the response, which includes the requested transaction details.

With this API, you can:

✅ Retrieve billing transactions using filters such as transaction ID, billing statement, and date range.
✅ Sort and paginate results for better data management.
✅ Optimise performance by selecting only the fields you need in your response.
✅ Use GraphQL introspection to explore the API schema dynamically.

For the full API details, see the Billing Transactions API documentation.

---

Prerequisites

Before retrieving billing transactions, ensure you have:

• A valid API token issued by tech-support@emerchantpay.com.
• A GraphQL-compatible tool like Postman or Insomnia for testing queries.
• Basic understanding of GraphQL to construct and execute API requests.

---

1. Obtain API authorisation token

Before making API requests, you need an authorisation token.

1. Get your token
• Contact tech-support@emerchantpay.com to request your billing_api_token.
• The token is issued per merchant and should be kept secure.
2. Include the token in your requests

Every request must include an Authorisation header with one of the following formats:

Authorization: Bearer “billing_api_token”
Authorization: Bearer billing_api_token
Authorization: Bearer token=”billing_api_token”
Authorization: Bearer token=billing_api_token
Authorization: Token token=”billing_api_token”
Authorization: Token token=billing_api_token
Authorization: Token “billing_api_token”
Authorization: Token billing_api_token

For the full API details, see the Billing Transactions API documentation.

---

2. Use GraphQL introspection to fetch the schema

The Billing Transactions API supports GraphQL introspection, allowing you to retrieve schema details.

Why use introspection?

• Fetch a list of all available fields, queries, and relationships in the API.
• Enables GraphQL query autocompletion in tools like Postman and Insomnia.

How to fetch the schema?

• Use Postman, Insomnia, or any GraphQL-compatible tool to fetch the schema using introspection.

---

3. Construct Your API request

Before making a request to the Billing Transactions API, ensure you include the required headers. These headers define the request format and authenticate your access.

Header	Required	Value
Content-Type	✅ Yes	application/graphql or application/json
Accept	✅ Yes	application/json
Authorization	✅ Yes	The API requires an authentication token in the request header. Replace billing_api_token with your actual token. See the “Obtain API Authorisation Token” section for details.

Once your request headers are set up, the next step is to retrieve billing transactions. The API allows filtering transactions by date, unique ID, and other criteria to refine your results.

For the full API details, see the Billing Transactions API documentation.

---

4.Filter and retrieve billing transactions

You need to apply at least one filter before retrieving billing transactions. You can filter transactions using date, unique ID, and more. This helps you get better results.

Parameter	Required	Type	Primary/Secondary Filter	Description
startDate	❌ No	yyyy-mm-dd hh:mm:ss or yyyy-mm-dd	Primary	Defines the start of the requested date range. Includes transactions created on or after the specified time (UTC). Must be used with endDate. The maximum allowed date range is 7 days.
endDate	❌ No	yyyy-mm-dd hh:mm:ss or yyyy-mm-dd	Primary	Defines the end of the requested date range. Includes transactions created before the specified time (UTC). Must be used with startDate. The maximum allowed date range is 7 days.
uniqueId	❌ No	list of strings	Primary	Retrieves transactions by unique transaction ID. Up to 10,000 IDs can be included in a single request.
billingStatement	❌ No	list of strings	Primary	Retrieves transactions by billing statement name. A maximum of 10 statements can be specified per request.
merchantTransactionId	❌ No	list of strings	Primary	Retrieves transactions by merchant-assigned transaction IDs. Supports up to 10,000 IDs in a single request.
masterAccountName	❌ No	list of strings	Secondary	Filters transactions by master account name. Supports up to 10 account names per request. Requires a primary filter for accurate results.
transactionType	❌ No	string (255)	Secondary	Filters transactions by billing transaction type (e.g., “Sale Approved”, “Chargeback”, “Refund Approved”). Supports up to 10 transaction types per request. Must be formatted with spaces and capital letters if applicable. See [Transaction Types] for the full list.

If startDate is used, endDate must also be specified.
If no sorting is specified, results are returned in ascending order by transactionDate by default (earliest transactions first).
Applying certain filters (like masterAccountName or transactionType) may cause older records to appear first unless explicitly sorted by a different field (e.g., transactionDate desc). To ensure you retrieve the latest records efficiently, use sorting and paging, as explained in the “Request paging and sorting” section below.
Primary vs. Secondary Filters: Primary filters define the main criteria for retrieving transactions (e.g., date range, unique ID). Secondary filters refine results further but require a primary filter to be effective. Using only secondary filters may result in unexpected data retrieval.

Retrieving Billing Transactions with Selected Fields

The API allows you to customise your response by selecting only the fields relevant to your needs. Instead of retrieving all available data, you can specify exactly which details to include, optimising response performance.

Below is an example GraphQL query that retrieves billing transactions while selecting key fields such as transaction details, fees, settlement status, and merchant information. You can modify the request to include or exclude fields based on your requirements.

query {
  billingTransactions(
    filter: {
      uniqueId: “abc123”
    }
  ) {
    items {
      id
      billingStatement
      uniqueId
      arn
      transactionDate
      transactionType
      transactionCurrency
      transactionAmount
      exchangeRate
      billingCurrency
      billingAmount
      transactionFeeCurrency
      transactionFeeAmount
      transactionFeeChargedOnBillingStatement
      commissionPercent
      commissionAmount
      interchangeFee
      interchangeCurrency
      isInterchangeplusplus
      interchangeplusplusChargedOnBillingStatement
      schemeFee
      schemeFeeCurrency
      standardDebitCardRate
      gstAmount
      gstRate
      vatAmount
      vatRate
      terminalName
      region
      settlementBillingStatements
      settlementDates
      settlementStatus
      merchantId
      merchantName
      merchantTransactionId
      masterAccountName
      valueDate
      documentId
      referenceId
      authCode
      paymentType
      cardBrand
      cardNumber
      cardHolder
      cardType
      cardSubtype
    }
  }
}

By selecting only the required fields, you reduce response size and improve query efficiency. The next examples demonstrate how to apply different filters for specific use cases.

Example 1: Retrieve transactions by Unique ID

This request retrieves transactions within a date range and filters them by uniqueId.

query {
  billingTransactions(
    filter: {
      uniqueId: “abc123”
    }
  )
  {
    items {
      id
      billingStatement
      arn
      transactionDate
      transactionType
      transactionCurrency
      transactionAmount
      exchangeRate
      billingCurrency
      billingAmount
      transactionFeeCurrency
      transactionFeeAmount
      transactionFeeChargedOnBillingStatement
      commissionPercent
      commissionAmount
      interchangeFee
      interchangeCurrency
      isInterchangeplusplus
      interchangeplusplusChargedOnBillingStatement
      schemeFee
      schemeFeeCurrency
      standardDebitCardRate
      gstAmount
      gstRate
      vatAmount
      vatRate
      terminalName
      region
      settlementBillingStatements
      settlementDates
      settlementStatus
      merchantId
      merchantName
      merchantTransactionId
      masterAccountName
      valueDate
      documentId
      referenceId
      authCode
      paymentType
      cardBrand
      cardNumber
      cardHolder
      cardType
      cardSubtype
    }
  }
}

Example 2: Retrieve transactions by Billing Statement

This request filters transactions by billing statement name (e.g., "Statement123").

query {
  billingTransactions(
    filter: {
      billingStatement: “Statement123”
    }
  )
    {
        items
        {
    id
    uniqueId
    transactionDate
    transactionAmount
  }
    }
}

Example 3: Retrieve transactions by Merchant Transaction ID

This request retrieves transactions based on merchant-assigned transaction IDs.

query {
  billingTransactions(
      filter: { merchantTransactionId: [“TXN-001”, “TXN-002”] })
    {
        items
        {
    id
    uniqueId
    transactionDate
    transactionAmount
  }
    }
}

Example 4: Retrieve transactions by Transaction Type

This request filters transactions by transaction type, such as "Sale Approved" or "Chargeback".

query {
               billingTransactions(filter: { startDate: “2025-03-01”, endDate: “2025-03-08”, transactionType: “SettlementApproved” })
      {
        items
        {
    id
    uniqueId
    transactionDate
    transactionAmount
        }
      }
}

Example 5: Combining multiple filters

This request retrieves transactions within a date range, filtered by billing statement and transaction type.

query {
               billingTransactions(filter: { billingStatement: “StatementABC”, transactionType: “Settlement Approved” })
      {
        items
        {
    id
    uniqueId
    transactionDate
    transactionAmount
        }
      }
}

After making a request with filters applied, the API returns a structured response containing transaction details.

---

5. Understand the API response

The API response provides details for each transaction. This includes the transaction ID, amount, currency, and status.

Field	Type	Description
id	integer	Transaction identifier.
uniqueId	string	Transaction unique identifier.
billingStatement	string	Name of the billing statement associated with the transaction.
arn	string*	Acquirer reference number assigned by the card network.
transactionType	string	Indicates the type of billing transaction (e.g., Sale Approved, Chargeback, Refund Declined). See the API documentation for the full list of transaction types.
transactionDate	yyyy-mm-dd hh:mm:ss*	Timestamp when the transaction was processed (UTC).
transactionCurrency	string (3)	Three-letter ISO 4217 code representing the processing currency.
transactionAmount	float	Amount processed in the transaction currency.
exchangeRate	float	Conversion rate used to calculate the billing amount.
billingCurrency	string (3)	Three-letter ISO 4217 code for the billing currency.
billingAmount	float*	Final transaction amount converted into the billing currency.
transactionFeeCurrency	string (3)	ISO 4217 currency code for the applied transaction fee.
transactionFeeAmount	float*	Fee amount deducted for processing the transaction.
transactionFeeChargedOnBillingStatement	string*	Billing statement where the transaction fee was deducted.
commissionPercent	float*	Commission percentage applied to the transaction.
commissionAmount	float*	Commission amount deducted in billing currency.
interchangeFee	float*	Fee charged by the card network for processing the transaction.
interchangeCurrency	string (3)*	Interchange currency code in ISO 4217.
isInterchangeplusplus	boolean	Indicates if the transaction follows the Interchange++ pricing model.
interchangeplusplusChargedOnBillingStatement	string*	Billing statement where the Interchange++ fees were charged.
schemeFee	float*	Scheme fee amount charged by the payment network.
schemeFeeCurrency	string (3)*	Scheme fee currency in ISO 4217.
standardDebitCardRate	float*	Standard debit card rate applied to the transaction.
gstAmount	float	The Goods and Services Tax (GST) amount applied to the transaction. Calculated based on the transaction fee and commission, expressed in the billing currency.
gstRate	float	The percentage rate of GST applied to the transaction. Calculated based on the transaction fee and commission.
vatAmount	float	The Value Added Tax (VAT) amount applied to the transaction. Calculated based on the transaction fee and commission, expressed in the billing currency.
vatRate	float	The percentage rate of VAT applied to the transaction. Calculated based on the transaction fee and commission.
terminalName	string*	The name of the terminal where the transaction was processed. This field may not always be available.
region	string*	The geographical region where the transaction took place. This field may not always be available.
settlementBillingStatements	string*	Thename(s) of billing statements that partially or fully settled the transaction. If multiple billing statements apply, they are separated by a comma.
settlementDates	yyyy-mm-dd*	The date(s) when the transaction was settled. If multiple settlements occurred, dates are separated by a comma.
settlementStatus	string (enum)*	The status of the transaction settlement. Possible values: – Delayed – The transaction is not yet fully settled. – Balanced – The transaction is fully settled. – Not Defined – The settlement status is unknown or unavailable.
merchantId	integer	Your unique account identifier in the system.
merchantName	string	Your account name as registered in the system.
merchantTransactionId	string*	Transaction ID that you assigned to the transaction.
masterAccountName	string	The primary account name associated with your profile.
valueDate	yyyy-mm-dd*	The date when the associated billing statement was marked as Paid. Remains empty for billing statements with Pending status.
documentId	string*	A consumer identification document reference. This may be required for compliance or regulatory purposes. See Document ID parameter for details.
referenceId	string*	Reference to the original transaction ID you provided.
authCode	string*	A 6-character alphanumeric code generated by the card network upon transaction authorisation. Used to track and verify authorisation requests.
paymentType	string*	Identifies the original transaction type that led to this billing transaction. For example, a refund or chargeback might originate from an initial Sale or Authorize.
cardBrand	string*	Brand of the card used (e.g., Visa, Mastercard).
cardType	string*	Type of card used (e.g., Debit, Credit, Charge Card).
cardNumber	string*	Masked card number (e.g., 420000…0000).
cardHolder	string*	Cardholder’s name as printed on the card.
cardType	string*	Indicates the type of card used for the transaction. Possible values: Debit, Credit, Charge Card.
cardSubtype	string*	Specifies the subtype of the card, based on its features and usage. Examples: Standard, Gold, Gift.


Fields marked with * may not always be present in the response.

Example Successful Response

Below is an example of a successful API response, showing a list of billing transactions that match the applied filters.

{
  “data”: {
    “billingTransactions”: [
      {
        “id”: 123456,
        “uniqueId”: “ABC123XYZ”,
        “transactionDate”: “2024-02-02 14:30:00”,
        “transactionAmount”: 100.50,
        “transactionCurrency”: “USD”,
        “billingAmount”: 95.75,
        “billingCurrency”: “EUR”,
        “transactionType”: “Sale Approved”
      }
    ]
  }
}

If your request returns a large number of transactions, you can use pagination to manage the response efficiently. The API allows you to retrieve transactions in smaller chunks and sort them based on specific fields.

For the full API details, see the Billing Transactions API documentation.

---

6. Request paging and sorting

To improve performance and manage large datasets, the Billing Transactions API supports pagination. You can specify the number of results per page and retrieve transactions in a structured manner. Additionally, sorting options allow you to order transactions by date, amount, and other criteria.

Parameter	Required	Type	Description
page	❌ No	integer	Page number (starts from 1). Default: 1.
perPage	❌ No	integer	Number of entries per page (1 – 100). Default: 100.
orderByField	❌ No	string	Field to sort results by. Default: transactionDate. See available fields below.
orderByDirection	❌ No	string (enum)	Sort direction: asc (default) or desc.

Example: Retrieve transactions with pagination

The following request retrieves transactions **on page 2** with **5 results per page** sorted by transactionDate in descending order.

query {
  billingTransactions(
    filter: { startDate: “2024-02-01”, endDate: “2024-02-07” },
    paging: { page: 2, perPage: 5 },
    sort: { byField: “transactionDate”, byDirection: “desc” }
  ) {
    id
    uniqueId
    transactionDate
    transactionAmount
  }
}

Example Successful Response

The API response returns a paginated list of transactions that match the specified filters. Since this request retrieves **page 2** with **5 results per page**, the response includes the second batch of transactions.

{
  “data”: {
    “billingTransactions”: [
      {
        “id”: 987654,
        “uniqueId”: “DEF456”,
        “transactionDate”: “2024-02-06 18:45:00”,
        “transactionAmount”: 50.25
      },
      {
        “id”: 123456,
        “uniqueId”: “ABC123”,
        “transactionDate”: “2024-02-06 16:30:00”,
        “transactionAmount”: 75.00
      }
    ]
  }
}

---

7. Troubleshooting & FAQ

If you encounter issues while using the Billing Transactions API, refer to the common error codes and their descriptions below. If the issue persists, contact support for further assistance.

Common API Errors

Status Code	Description
401 Unauthorized	Missing or invalid API token. Ensure the correct token format is used.
403 Access Denied	The token is valid, but you do not have the necessary permissions to access the API.
500 Internal Service Error	An unknown system error has occurred. Please contact support for assistance.

Example Error Response

Below is an example of an error response when required parameters are missing or incorrectly formatted.

{
  “data”: null,
  “errors”: [
    {
      “message”: “invalid request parameters”,
      “extensions”: {
        “code”: “INVALID_REQUEST_PARAMETERS”,
        “debug”: “startDate and endDate fields should be defined together”
      }
    }
  ]
}

For additional troubleshooting, verify that all required parameters are included in your request. If you continue to experience issues, contact support at tech-support@emerchantpay.com.