Producer payment instruments

When a producer receives a commission payment or makes an agency bill payment, the payment is made using a producer payment instrument.

Similar to account payment instruments, producers have two types of payment instruments available to use: universal payment instruments and non-universal payment instruments.
  • Universal payment instruments are applicable to all producers. These include Cash, Check, Responsive, and Unapplied fund (Producer Unapplied).
  • Non-universal payment instruments are specific to a producer. Non-universal payment instruments are typically credit cards or bank accounts where the producer is the account holder.

Some producer payment instruments can be used both for payments coming into BillingCenter and payments paid out by BillingCenter. Others have more restricted uses. For example, you cannot use the Responsive payment instrument to make agency bill payments. Cloud API has validations in place to ensure that the correct type of payment instrument is used when making financial transactions.

In Cloud API, you can query for both universal and non-universal payment instruments available to a producer, and you can create non-universal producer payment instruments.

Retrieve all of a producer’s payment instruments

Use the following endpoint to retrieve all of a producer’s payment instruments:
  • GET /billing/v1/producers/{producerId}/payment-instruments

When using this endpoint, both the universal payment instruments and the non-universal payment instruments on that producer are returned.

You can tell a payment instrument is universal if the immutable field is set to true. If the immutable field is set to false, the payment instrument is non-universal.

For example:

Command
GET /billing/v1/producers/bc:367/payment-instruments
Response
{
    "count": 7,
    "data": [
        {
            "attributes": {
                "displayName": "ACH/EFT (bc:SpjgWR2BTUPfzm75pslhv)",
                "id": "bc:SpjgWR2BTUPfzm75pslhv",
                "immutable": false,
                "paymentMethod": {
                    "code": "ach",
                    "name": "ACH/EFT"
                }
            },
            ...
        },
        {
            "attributes": {
                "displayName": "Cash",
                "id": "bc:SmDW7_usFGdFY62eTG1aq",
                "immutable": true,
                "paymentMethod": {
                    "code": "cash",
                    "name": "Cash"
                }
            },
            ...
        },
        ...
    ]
}

Retrieve a single producer payment instrument

When retrieving individual producer payment instruments, different endpoints are used for universal and non-universal payment instruments.

For a universal payment instrument, use the following endpoint:
  • GET /billing/v1/universal-payment-instruments/{universalPaymentInstrumentId}
For a non-universal payment instrument, use the following endpoint:
  • GET billing/v1/producers/{producerId}/payment-instruments/{paymentInstrumentId}

Note that if you have retrieved a producer’s available payment instruments using the collection endpoint, you do not have to figure out the correct universal or non-universal URI. The href field in the self object provides a path to both universal and non-universal payment instruments.

For example, the following retrieves a producer’s credit card payment instrument, which is non-universal.

Command
GET /billing/v1/producers/bc:367/payment-instruments/bc:393
Response
{
    "data": {
        "attributes": {
            "detail": "PmntIns",
            "displayName": "PmntIns",
            "id": "bc:393",
            "immutable": false,
            "paymentMethod": {
                "code": "creditcard",
                "name": "Credit Card"
            },
            "token": "1234567890123456"
        },
        ...
    }
}

Create a producer payment instrument

You can create a non-universal payment on a producer.

Use the following endpoint to create a producer payment instrument:
  • POST /billing/v1/producers/{producerId}/payment-instruments
Only one field is required:
  • paymentMethod - A typekey reference to the PaymentMethod typelist. The valid options in this typelist when creating payment instruments are ach, creditcard, misc, and wire
Other fields are available or required in certain circumstances:
  • If you specify a payment method of creditcard, you must also specify the token field as a string (such as the credit card's number).
  • The detail field, used to provide a credit card’s display name, is only permitted when creating a credit card.

The following call creates a credit card payment instrument:

Command
POST /billing/v1/producers/bc:SbAeLB6FWDdTaHhsPTrBy/payment-instruments
Request body
{
    "data": {
        "attributes": {
            "paymentMethod": {
                "code": "creditcard"
            },
            "token": "5986-7890-5343-7771",
            "detail": "Allrisk Credit Card (7771)"
        }
    }
}