Payment instruments

A payment instrument is a designation for how a payment was or will be made. For example, a payment instrument can be set to Cash, Check, or a specific Credit Card (such as Credit Card 4400-0012-4523-0352). Payment instruments are associated with accounts, invoice streams, and payments.

Universal and non-universal payment instruments

Some payment instruments are applicable to all accounts (or producers). These payment instruments are referred to as universal payment instruments. The universal payment instruments that are applicable to accounts include: Cash, Check, Responsive, and Unapplied Fund (Account).

(The universal payment instruments that are applicable to producers include: Cash, Check, and Unapplied Fund (Producer).)

A non-universal payment instrument is a payment instrument that applies to a single account (or producer). Non-universal payment instruments are typically credit cards or bank accounts that belong to the account holder. For example, suppose the Ray Newton account has a payment instrument that is a bank account with the account number 07025 93211. This is a non-universal payment instrument.

All payment instruments have an immutable field.

  • For universal payment instruments, this field is set to true.
  • For non-universal payment instruments, this field is set to false.

What each type of payment instrument is used for?

Some payment instruments are used for payments that have been made. They identify how the payment was made.

  • The universal Cash payment instrument is used for payments to indicate the payment was made with physical currency.
  • The universal Check payment instrument is used for payments to indicate the payment was made with a check tied to some sort of bank account.
  • The account-specific payment instruments, such as Credit Card, are used for payments to indicate the payment was made with the associated payment instrument (such as a given credit card associated with the account).

Some universal payment instruments are used for account to identify where payments will come from.

  • The universal Responsive payment instrument is used for accounts to indicate an invoice will be sent and the payer will respond with a payment (such as a cash payment, a check payment, or a credit card payment).
  • The account-specific payment instruments (such as Credit Card), which can be used for payments, can also be used for accounts. When the account's payment instrument is set to an account-specific payment instrument (such as a specific credit card), BillingCenter automatically deducts payment from the payment instrument when the invoice is billed.

Some universal payment instruments are used for internal BillingCenter transactions.

  • The universal Unapplied Fund (Account) payment instrument is used for zero-dollar money distributions, which occur when BillingCenter uses money in an unapplied fund to execute a credit distribution.

Querying for universal payment instruments

Universal payment instruments are provided in the base configuration and are unlikely to change. Thus, there is rarely a need to query for universal payment instrument information. However, if there is such a requirement, you can use the following endpoints to query for them:

  • GET /billing/v1/universal-payment-instruments
  • GET /billing/v1/universal-payment-instruments/{universalPaymentInstrumentId}

For example, the following request retrieves information for the Cash universal payment instrument (whose id is S7JRZxdMxp3TQnHCVLN7q).

Command
GET /billing/v1/universal-payment-instruments/bc:S7JRZxdMxp3TQnHCVLN7q
Response body
{
    "data": {
        "attributes": {
            "displayName": "Cash",
            "id": "bc:S7JRZxdMxp3TQnHCVLN7q",
            "immutable": true,
            "paymentMethod": {
                "code": "cash",
                "name": "Cash"
            }
        },
        ...

Querying for account payment instruments

Whenever an account is created, it is automatically associated with the following universal payment instruments: Cash, Check, Responsive, Unapplied Fund (Account).You can also create account-specific payment instruments (such as a specific credit card).

To query for account-level payment instrument information, use the following endpoints:

  • GET /billing/v1/accounts/{accoundId}/payment-instruments
  • GET /billing/v1/accounts/{accoundId}/payment-instruments/{paymentInstrumentId}

For example, the following retrieves the payment instruments for account bc:73. Note that this includes both universal payment instruments (where immutable is true) and account-specific payment instruments (where immutable is false).

Command
GET /billing/v1/accounts/{accoundId}/payment-instruments/bc:73
Response body
{
    "count": 5,
    "data": [
        {
            "attributes": {
                "displayName": "Cash",
                "id": "bc:S7JRZxdMxp3TQnHCVLN7q",
                "immutable": true,
                "paymentMethod": {
                    "code": "cash",
                    "name": "Cash"
                }
            },
            ...
        },
        {
            "attributes": {
                "displayName": "Check",
                "id": "bc:S3tSVt5YFd7_pnRtIk4OV",
                "immutable": true,
                "paymentMethod": {
                    "code": "check",
                    "name": "Check"
                }
            },
            ...
        },
        {
            "attributes": {
                "displayName": "Credit Card (4400-0012-4523-0352)",
                "id": "bc:SZbE2YgL2nTsSIoIDgGLH",
                "immutable": false,
                "paymentMethod": {
                    "code": "creditcard",
                    "name": "Credit Card"
                },
                "token": "4400-0012-4523-0352"
            },
            ...
        },
        ...

Creating account-level payment instruments

Use the following endpoint to create an account-level payment instrument:

  • POST /billing/v1/accounts/{accoundId}/payment-instruments

The request must specify a paymentMethod. This is a typekey that must be set to a value from the PaymentMethod typelist. However, for account-level payment instruments, the only valid values are: ach, creditcard, misc, and wire.

If you specify a payment method of creditcard, you must also specify a token field set to a String value (such as the credit card's number).

If you specify a payment method of ach, misc, or wire, no other fields are required.

For example, the following request creates a new account-level credit card payment instrument for account bc:73.

Command
POST /billing/v1/accounts/bc:73/payment-instruments
Request body
{
  "data": {
    "attributes": {
        "paymentMethod": {
            "code": "creditcard"
        },
        "token": "0000-1111-2222-3333"
    }
  }
}