Daily Fees and Gross Funding

Updated
  • Updated on Jun 30, 2025
  • Published on May 13, 2025
  • 9 minute(s) read
Prev Next

The Billing resource allows partners to differ paying Fees and those automatically being deducted from disbursements by having a certain set of defined Fees by creating a statement that can be paid after a defined period of time.

Important!

Billing resource can only be enabled by the API at this time. There is no UI management for Statements. The payment and management of these must be handled by the partner respectively.

Creating a Billing Resource for Daily Funding

  1. Create a /billings resource. This will determine what fees are collected in a statement for a period of time.
    Entity: Entity that will be collecting the fee at the end of the billing period.
    forEntity: Entity that is paying the fee(s) for the billing period. This field is only required if org or division is set to null.

    POST /billings HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

    {
	"login": "t1_log_5e052c20b6f1ef38770a410",
	"entity": "t1_ent_5e052c20b7dcdfe6bda8a3a",
	"forentity": "t1_ent_5e9735c503a9888a85fc8e2",
	"schedule": "days",
	"start": "20200409",
	"currency": "USD",
	"inactive": "0",
	"frozen": "0"
}

    {
    "response": {
        "data": [
        {
            "id": "t1_bil_123abc4d567890efg1h2i34",
            "created": "2020-04-15 19:21:53.0183",
            "modified": "2020-04-15 19:21:53.0183",
            "creator": "t1_log_123abc4d567890efg1h2i34",
            "modifier": "t1_log_123abc4d567890efg1h2i34",
            "login": "t1_log_123abc4d567890efg1h2i34",
            "entity": "t1_ent_123abc4d567890efg1h2i34",
            "org": null,
            "division": null,
            "partition": null,
            "description": null,
            "schedule": "days",
            "scheduleFactor": 1,
            "start": "20250615",
            "finish": null,
            "collection": "entity",
            "collectionFactor": "days",
            "collectionOffset": 1,
            "collectionIncludeCurrent": "0",
            "currency": "USD",
            "inactive": "0",
            "frozen": "0",
            "forentity": "t1_ent_234abc5d678901efg2h3i45"
        }
    ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

    Note

    The entity defined in the /billings resource needs to be the same charging entity that is in the fee in order for that fee to be included in a statement.

  2. Associate a /billingEvents resource to the /billings resource. This defines what will be collected in a statement. A /billingEvents can be setup for fees, chargebacks, returns, and/or profitShares. If the resource is for one specific item then the eventSchedule must be set otherwise the /billingEvents will apply for all items; meaning, all fees opposed to just a specific fee.
    By default, a /billingEvents resource will have deductFromBalance set to 0/False. Meaning entries will not be created for fees meaning the Available Balance on the entity will not be impacted. Fees will not be charged or deducted from a disbursement. Disbursements will be only Sales - Returns.

    Partners can set deductFromBalance to 1/True if they want entries created on the fees so that the merchant always has enough balance in their FBO to cover the fees. Will disburse everything in the FBO minus enough to cover the fees so money will be withheld on the merchant account.

    Note

    A /billingEvents resource can be embedded within the creation of the /billings resource by submitting as an array.

    A /billingModifer is an optional configuration for a /billings resource and changes who owns the /billings resource giving them control to change the total amount of the billing and who will pay.

  3. When a fee defined within the entity /billingEvents occurs a statementEntry is created.
    entity: Is the entity that triggered the statementEntry.

    onEntity: Is the entity that will be charged for the statementEntry

    forEntity: Is the entity that created the billing resource.

    GET /statementEntries HTTP/1.1
Accept: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
SEARCH: billing[in]=t1_bil_5e9797110472c0e9ca747ab

    {
    "response": {
        "data": [
            {
                "id": "t1_ste_123abc4d567890efg1h2i34",
                "created": "2020-04-16 18:49:24.0049",
                "modified": "2020-04-16 18:49:24.0049",
                "creator": "000000000000001",
                "modifier": "000000000000001",
                "onentity": "t1_ent_5e9735c503a9888a85fc8e2",
                "billing": "t1_bil_123abc4d567890efg1h2i34",
                "statement": null,
                "fee": "t1_fee_123abc4d567890efg1h2i34",
                "profitShare": null,
                "event": 6,
                "eventId": "t1_txn_123abc4d567890efg1h2i34",
                "description": "AUTH fee schedule",
                "amount": 806.5,
                "deductedFromBalance": 0,
                "entity": "t1_ent_123abc4d567890efg1h2i34",
                "forentity": "t1_ent_234abc5d678901efg2h3i45"
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

    Note

    Statements are only generated at the end of the billing cycle, statementEntries resources are created immediately when a fee part of a /billingEvents is created.

  4. Depending on the start value of the /billing resource and the schedule the statement is generated.

    {
    "response": {
        "data": [
            {
                "id": "t1_stm_123abc4d567890efg1h2i34",
                "created": "2020-04-16 00:27:02.8583",
                "modified": "2020-04-16 00:27:02.9048",
                "creator": "000000000000001",
                "modifier": "000000000000001",
                "billing": "t1_bil_123abc4d567890efg1h2i34",
                "status": "pending",
                "totalPaid": 0,
                "total": 5419,
                "currency": "USD",
                "forentity": "t1_ent_234abc5d678901efg2h3i45",
                "entity": "t1_ent_123abc4d567890efg1h2i34",
                "start": 20200415,
                "finish": 20200415
             }
        ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

Paying for a Statement

There are two ways that a statement can be paid for once generated in the API.

  • A Txn can be submitted to pay the statement total. This requires the partner to have a merchant account to accept payment for the statement.

  • A Payout schedule can be created on the billing resource. This will automatically debit the entity for the statement total based on the schedule defined in the payout resource.

Get the Statement ID

GET /statements HTTP/1.1
Accept: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}    
search: billing[equals]={billing-ID}

Response: 

{
    "response": {
        "data": [
            {
                "id": "t1_stm_123abc4d567890efg1h2i34",
                "created": "2020-04-16 00:27:02.8583",
                "modified": "2020-04-16 00:27:02.9048",
                "creator": "000000000000001",
                "modifier": "000000000000001",
                "billing": "t1_bil_123abc4d567890efg1h2i34",
                "status": "pending",
                "totalPaid": 0,
                "total": 5419,
                "currency": "USD",
                "forentity": "t1_ent_234abc5d678901efg2h3i45",
                "entity": "t1_ent_123abc4d567890efg1h2i34",
                "start": 20200415,
                "finish": 20200415
            }
        ],
        "details": {
            "requestId": 1,
            "totals": [],
            "page": {
                "current": 1,
                "last": 1,
                "hasMore": false
            }
        },
        "errors": []
    }
}

Submit a Transaction

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
{
    "merchant": "t1_mer_123abc4d567890efg1h2i34",
    "statement": "t1_stm_123abc4d567890efg1h2i34", // Pass the statement ID here
    "type": "7",
    "origin": "2",
    "payment": {
        "method": "8",
        "number": "11112223333",
        "routing": "11112222",
    },
    "first": "firstname",
    "expiration": "1234",
    "total": "5000"
}

Response:

{
  "response": {
    "data": [
      {
        "id": "t1_stm_123abc4d567890efg1h2i34",
        "created": "2020-04-16 00:27:02.8583",
        "modified": "2020-04-16 18:55:57.8464",
        "creator": "000000000000001",
        "modifier": "t1_log_123abc4d567890efg1h2i34",
        "billing": "t1_bil_123abc4d567890efg1h2i34",
        "status": "processing",
        "totalPaid": 0,
        "total": 5419.925,
        "currency": "USD",
        "forentity": "t1_ent_234abc5d678901efg2h3i45",
        "entity": "t1_ent_123abc4d567890efg1h2i34",
        "start": 20200415,
        "finish": 20200415
      }
    ],
    "details": {
      "requestId": 1,
      "totals": [],
      "page": {
        "current": 1,
        "last": 1,
        "hasMore": false
      }
    },
    "errors": []
  }
}

Questions

Question

Answer

What is the behavior if a /billing resource is setup on a merchant entity and on a group the merchant is part of? Will two statements be generated or will one supersede the other?

If multiple billings of the same payer/payee apply for the same event, the order of preference will be:

1. direct to entity (forentity set)
2. via org
3. via division
4. via partition

That said, if there are two separate billings that applied to the same payer/payee by the time statements are generated, there will be two statements generated for whatever applied to each billing.

What is the behavior if a merchant is part of two groups that each have a /billings resource?

The earliest created billingEvent will prevail when creating statementEntries. See above as well.

What are the valid enumerations for collectionFactor and collectionOffset?


"errors": [ { "field": "collectionFactor", "code": 15, "severity": 2, "msg": "This field only accepts values in ()", "errorCode": "invalid_enum_value" }, { "field": "collectionOffset", "code": 15, "severity": 2, "msg": "This field only accepts values in ()", "errorCode": "invalid_enum_value" }

In order to be able to set collectionFactor or collectionOffset, it is required to set collection. Currently, only entity collections are supported, so in reality this feature is not yet fully supported.

When a transaction is submitted for a statement does the status change to processing and then paid once the transaction settles?

A statement status will change from processing to paid when the transaction goes into a captured status or the disbursement goes into a processed status.

If a second payment is submitted for a statement that has been marked processing or paid what is the expected behavior?

It appears that a second txn can be submitted to a statement that is in a processing status.

Need to validate behavior for a Paid statement.

Should a statement have sub-pennies or should this be rounded up or down?

How do I setup a billingEvents resource for a Chargeback and a Chargeback Fee?

When an event is set to chargebacks then the chargeback transaction will be billed daily. To setup the fee then a second event for fees would need to be setup or a specific fee ID can be added in the eventSchedule.

What time do /statements generate?

Statements generate around 1:00 AM ET.

Related articles