Payment requests

Some accounts want to pay for invoices automatically. These accounts prefer to designate a nonresponsive payment instrument (such as an ACH/EFT account or a credit card) from which BillingCenter can withdraw payment whenever an invoice is billed.

Automatic payments are managed by payment requests. A payment request is an object that BillingCenter uses to manage the process of automatically withdrawing money from a nonresponsive payment instrument to pay for an invoice.

Payment requests can be created automatically or manually:

  • When a payment request is created automatically, its amount is set to the amount due on the corresponding invoice.
  • When a payment request is created manually, its amount is set by the user who is creating it.

Payment requests can also be viewed and created through Cloud API.

Note that, as of this release, there are no endpoints for editing or stopping a payment request.

Querying for payment requests

Use the following endpoints to query for an account's payment requests:

  • GET /billing/v1/account/{accountId}/payment-requests
  • GET /billing/v1/account/{accountId}/payment-requests/{paymentRequestId}

For example, the following request retrieves the payment requests for account bc:55.

Command

GET /billing/v1/account/bc:55/payment-requests

Response body

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "amount": {
                    "amount": "120.00",
                    "currency": "usd"
                },
                "draftDate": "2023-04-25",
                "dueDate": "2023-04-25",
                "id": "bc:SKTGjcsKl8xIWXZb8uycZ",
                "paymentInstrument": {
                    "displayName": "Credit card (1200-3679-3343-0094)",
                    "id": "bc:SGP54lChROHT4Q-HsAqh3"
                },
                "requestDate": "2023-04-25",
                "status": {
                    "code": "requested",
                    "name": "Requested"
                },
                "statusDate": "2023-04-25"
            },
            ...

Creating payment requests

Use the following endpoints to create a payment request for an account:

  • POST /billing/v1/account/{accountId}/payment-requests

The following fields are required:

  • amount, which must be a JSON object specifying both amount and currency
  • draftDate
  • paymentInstrument, which must be set to the ID of a nonresponsive payment instrument associated with the account.

For example, the following request creates a payment instrument for account bc:55 for $120 using a credit card payment instrument whose ID is bc:7777.

Command

POST /billing/v1/account/bc:55/payment-requests

Request body

{
  "data": {
    "attributes": {
      "amount": {
        "amount": "120.00",
        "currency": "usd"
      },
      "draftDate": "2023-05-25",
      "paymentInstrument": {
        "id": "bc:7777"
      }
    }
  }
}