Creating a Quick Bill

Using the API, you can create a Quick Bill from within your application. Use the following steps:

  1. Determine where Quick Bill fees will be deposited.
  2. Determine who is receiving the goods or services.
  3. Determine how much will be charged.
  4. Choose an identifier from your own system.
  5. Determine who can see the Quick Bill.
  6. Customize the email.
  7. Choose the date.
  8. Upload attachments.
  9. Create the Quick Bill.

1: Determine where Quick Bill fees will be deposited

Quick Bill fees can be deposited in any of the bank accounts associated with a merchant account. You can retrieve a list of bank accounts for the merchant and then prompt the user to choose one to be the deposit account.

Example request: Retrieving a list of bank accounts for the merchant
curl -X GET -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/bank-accounts
Example response
[
  {
      "id": "bank_eZX3KANx7JyXDCrMQkdLj",
      "name": "Chase",
      "bank_name": "JPMorgan Chase & Co.",
      "trust": false,
      "account_id": "*****1234"
  }
  {
      "id": "bank_XugcE9HWGZNdLFLPvmP82",
      "name": "BoA",
      "bank_name": "Bank of America Corporation",
      "trust": false,
      "account_id": "*****9876"
  }
]

Note the id for the account to be used as the deposit account, which has a prefix of bank_. You’ll provide it as the bank_account_id in the Quick Bill.

2: Determine who is receiving the goods or services

A Quick Bill must have a contact associated with it. This contact is typically the client who is receiving the goods or services associated with the Quick Bill.

Example request: Creating a new contact
curl -X POST -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/contacts -d '
{
  "first_name": "Ellen",
  "last_name": "Ripley",
  "email_addresses": [
    {"address": "eripley@weyland-yutani.com"}
  ],
  "type": "person"
}'
Example response
{
  "id": "p_tup7e7S0e7LIE55qvgXAR",
  "created": {
      "user": "org_Y2eJHCXVqjMlXL9EfmBfc",
      "timestamp": "2018-06-07T16:22:17.445Z",
      "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
      "client_inet_address": "66.90.249.23",
      "client_country_code": "US",
      "client_location": "30.2414,-97.7687",
      "caller_inet_address": "66.90.249.23",
      "caller_country_code": "US",
      "caller_location": "30.2414,-97.7687"
  },
  "modified": {
      "user": "org_Y2eJHCXVqjMlXL9EfmBfc",
      "timestamp": "2018-06-07T16:22:17.445Z",
      "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
      "client_inet_address": "66.90.249.23",
      "client_country_code": "US",
      "client_location": "30.2414,-97.7687",
      "caller_inet_address": "66.90.249.23",
      "caller_country_code": "US",
      "caller_location": "30.2414,-97.7687"
  },
  "test_mode": false,
  "name": "Ellen Ripley",
  "sort_name": "Ripley Ellen",
  "preferred_email": "eripley@weyland-yutani.com",
  "contact_code": "0010",
  "owner_id": "org_Y2eJHCXVqjMlXL9EfmBfc",
  "owner": {
      "id": "org_Y2eJHCXVqjMlXL9EfmBfc",
      "test_mode": false,
      "owner_id": "org_aQ5urhpA1HUBJIxAvDfsM",
      "preferred_email": "myemail@mypartnercompany.com",
      "name": "My Partner Company",
      "sort_name": "My Partner Company",
      "type": "organization",
      "display_name": "My Partner Company"
  },
  "email_addresses": [
      {
          "id": "eml_mh5lADCijYgvLf5pMVvDl",
          "created": {
              "user": "org_Y2eJHCXVqjMlXL9EfmBfc",
              "timestamp": "2018-06-07T16:22:17.446Z",
              "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
              "client_inet_address": "66.90.249.23",
              "client_country_code": "US",
              "client_location": "30.2414,-97.7687",
              "caller_inet_address": "66.90.249.23",
              "caller_country_code": "US",
              "caller_location": "30.2414,-97.7687"
          },
          "modified": {
              "user": "org_Y2eJHCXVqjMlXL9EfmBfc",
              "timestamp": "2018-06-07T16:22:17.446Z",
              "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
              "client_inet_address": "66.90.249.23",
              "client_country_code": "US",
              "client_location": "30.2414,-97.7687",
              "caller_inet_address": "66.90.249.23",
              "caller_country_code": "US",
              "caller_location": "30.2414,-97.7687"
          },
          "address": "eripley@weyland-yutani.com",
          "preferred": false,
          "type": "email_address"
      }
  ],
  "first_name": "Ellen",
  "last_name": "Ripley",
  "display_name": "Ellen Ripley",
  "type": "person"
}

Regardless of which method you choose, note the contact’s id, which has a prefix of p_. You’ll provide this value as the contact_id in the Quick Bill.

3: Determine how much will be charged

When you specify the charge in the Quick Bill, you’ll need to provide:

You’ll provide these details in the line_items section of the Quick Bill.

For example, if you provide this information:

The Quick Bill will show a balance due of $100.

4: Choose an identifier from your own system

You should associate the Quick Bill with an invoice number or other unique identifier from your system.

You’ll add this unique identifier as the reference parameter of the Quick Bill.

5: Determine who can see the Quick Bill

When you create the Quick Bill, you’ll include the email address of the individual who will pay the Quick Bill, as well as other interested parties, such as the merchant. You choose how to gather these email addresses. For example, you can:

Regardless of how you obtain the email addresses, you’ll include them in the invoice_messages parameter of the Quick Bill.

6: Customize the email

When you send a Quick Bill, the system sends an email to everyone you include in the Quick Bill request.

Default email content

By default the email subject is:

Your <AffiniPay_Brand> Invoice [<AffiniPay_Brand_Invoice_Number]

For example:

Your LawPay Invoice [0000029]

The default email content is the following text, plus a payment link:

<Merchant_Name> has sent you a payment request

For example:

My Company, Inc. has sent you a payment request

Customize the email subject

If you don’t like the default email subject, you can define your own. For example, you can:

If you want to use a custom email subject, you’ll include it in the invoice_messages section’s subject parameter parameter when you create the Quick Bill.

Customize the text within the email

If you don’t like the default text within the email, you can define your own. For example, you can:

If you want to use custom email text, you’ll include it in the invoice_messages section’s message parameter when you create the Quick Bill.

7: Choose the date

You must set the date set for the Quick Bill. This date will show in the payment portal next to the reference number and amount for the Quick Bill. Typically, this is the date when the goods and services are received.

You’ll include this as the invoice_date when you create the Quick Bill.

8: Upload attachments

You can send invoices, supplemental documents, or other files with your Quick Bill. They’ll be available in the portal where users pay their Quick Bill.

Before you create the Quick Bill, you must upload your files. After you’ve confirmed that processing is completed, you’ll include the id for each file in the attachments section of the Quick Bill.

9: Create the Quick Bill

To create the Quick Bill, you’ll POST the information you gathered to the /invoices endpoint.

If you’re creating a test Quick Bill, your request body must include:

Example request: Creating a new Quick Bill
curl -X POST -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/invoices -d '
{
  "contact_id": "p_tup7e7S0e7LIE55qvgXAR",
  "bank_account_id": "bank_ngoOybNXKY52w7Jr32kHO",
  "invoice_date": "2018-09-27T00:00:00.000Z",
  "currency": "USD",
  "reference": "1357",
  "line_items": [
    {
      "description": "Consulting fee",
      "rate_per_quantity": "10000",
      "quantity": "1",
      "rate_type": "units"
    }],
  "invoice_messages": [
    {
      "email_addresses": ["eripley@weyland-yutani.com", "billing@mycompany.com"],
      "subject": "Request for Payment",
      "message": "For your convenience, our firm accepts payments online. To make a payment, please click the link below."
    }],
  "attachments": [
    {
      "id": "fref_vmaFw5ARaXFOFgEH7gtCa"
    }],
  "test_mode": "true"
}'
Example response
{
    "id": "i_WMxCGPfFSeHKgdoLsPMus",
    "created": {
        "user": "org_Y2eJHCXVqjMlXL9EfmBfc",
        "timestamp": "2018-09-27T20:21:15.440Z",
        "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
        "client_inet_address": "66.90.249.23",
        "client_country_code": "US",
        "client_location": "30.2955,-97.8133",
        "caller_inet_address": "66.90.249.23",
        "caller_country_code": "US",
        "caller_location": "30.2955,-97.8133"
    },
    "modified": {
        "user": "org_Y2eJHCXVqjMlXL9EfmBfc",
        "timestamp": "2018-09-27T20:21:15.440Z",
        "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
        "client_inet_address": "66.90.249.23",
        "client_country_code": "US",
        "client_location": "30.2955,-97.8133",
        "caller_inet_address": "66.90.249.23",
        "caller_country_code": "US",
        "caller_location": "30.2955,-97.8133"
    },
    "status": "pending",
    "invoice_number": "000028",
    "invoice_date": "2018-09-27T00:00:00.000Z",
    "total_amount": 10000,
    "total_amount_due": 10000,
    "amount_paid": 0,
    "test_mode": true,
    "currency": "USD",
    "bank_account_id": "bank_ngoOybNXKY52w7Jr32kHO",
    "owner_id": "org_Y2eJHCXVqjMlXL9EfmBfc",
    "contact_id": "p_tup7e7S0e7LIE55qvgXAR",
    "contact": {
        "id": "p_tup7e7S0e7LIE55qvgXAR",
        "test_mode": false,
        "owner_id": "org_Y2eJHCXVqjMlXL9EfmBfc",
        "preferred_email": "eripley@weyland-yutani.com",
        "first_name": "Ellen",
        "last_name": "Ripley",
        "name": "Ellen Ripley",
        "type": "person",
        "sort_name": "Ripley Ellen",
        "display_name": "Ellen Ripley"
    },
    "invoice_payments": [],
    "items": [
        {
            "id": "li_mXwlgmkwdBpr5e6wtTtA8",
            "description": "Consulting fee",
            "rate_per_quantity": "10000",
            "quantity": "1",
            "rate_type": "units",
            "total": 10000
        }
    ],
    "line_items": [
        {
            "id": "li_mXwlgmkwdBpr5e6wtTtA8",
            "description": "Consulting fee",
            "rate_per_quantity": "10000",
            "quantity": "1",
            "rate_type": "units",
            "total": 10000
        }
    ],
    "invoice_messages": [
        {
            "id": "imsg_Rub9yEhVt5oo37On70y0H",
            "created": {
                "user": "org_Y2eJHCXVqjMlXL9EfmBfc",
                "timestamp": "2018-09-27T20:21:15.440Z",
                "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
                "client_inet_address": "66.90.249.23",
                "client_country_code": "US",
                "client_location": "30.2955,-97.8133",
                "caller_inet_address": "66.90.249.23",
                "caller_country_code": "US",
                "caller_location": "30.2955,-97.8133"
            },
            "modified": {
                "user": "org_Y2eJHCXVqjMlXL9EfmBfc",
                "timestamp": "2018-09-27T20:21:15.440Z",
                "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
                "client_inet_address": "66.90.249.23",
                "client_country_code": "US",
                "client_location": "30.2955,-97.8133",
                "caller_inet_address": "66.90.249.23",
                "caller_country_code": "US",
                "caller_location": "30.2955,-97.8133"
            },
            "email_addresses": [
                "eripley@weyland-yutani.com",
                "billing@mycompany.com"
            ],
            "subject": "Request for Payment",
            "body": "\n    <!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">\n<html xmlns=\"http://www.w3.org/1999/xhtml\">\n\n<link href=\"https://fonts.googleapis.com/css?family=Lato|Source+Sans+Pro\" rel=\"stylesheet\"> \n<meta http-equiv=\"Content-Type\" content=\"text/html charset=UTF-8\" />\n\n<body bgcolor=\"#143F6C\" color=\"#333333\" style=\"background: #143F6C; font-family: 'Source Sans Pro', sans-serif; color: #333; padding-top: 15px;\">\n    <table align=\"center\" bgcolor=\"#FFFFFF\" style=\"width: 75%; background-color: #FFF; margin: auto; padding: 24px;\">\n        \n            \n                \n                    

\n <font family=\"Helvetica, Arial,sans-serif\">Heather Law LLC said:</font>\n

\n

\n <font family=\"Helvetica, Arial,sans-serif\">For your convenience, our firm accepts payments online. To make a payment, please click the link below. Contact our office directly if you have any questions.</font>\n

\n \n\n

\n \n

\n \n \n \n <p align=\"center\" style=\"text-align: center; margin-top: 24px; margin-bottom: 24px;\">\n \n \n \n <a style=\"padding: 8px 15px; color: #FFF; background: #046FDC; text-decoration: none;\" class=\"btnPayNow\" href=\"https://qa.portal.affinipay.com/?c=pn0q3moptqusjs2ajer8gis2itu3un77q3keh4q8efde2d8rskh3\">\n <font family=\"Helvetica, Arial,sans-serif\">Pay Now</font>\n </a>\n \n </p>\n \n <table bgcolor=\"#FFFFFF\" width=\"100%\" border=\"0\" cellpadding=\"6\">\n \n <td style=\"font-size: 20px; border-bottom: 1px solid #EEE; color: #666\">\n <font family=\"Helvetica, Arial,sans-serif\" color=\"#666666\">Balance Due</font>\n </td>\n <td style=\"font-size: 20px; text-align:right; color: #000; font-family: 'Lato', sans-serif; border-bottom: 1px solid #EEE;\">\n <font family=\"Helvetica, Arial,sans-serif\" color=\"#000000\">$200.00</font>\n </td>\n \n </table>\n \n\n <p style=\"margin-top: 24px; border-top: 1px solid #EEE; padding-top: 8px;\">\n <img border=\"0\" width=\"200\" height=\"50\" src=\"cid:poweredBy\" alt=\"Powered By AffiniPay\">\n </p>\n \n \n \n\n </table>\n\n <p style=\"padding: 36px 0px; text-align: center; font-size: 14px; color: #FFF;\">\n <font color=\"#FFFFFF\">\n Heather Law LLC
\n \n 98723 Main Street, Austin, TX 78730\n \n </font>\n </p>\n\n</body>\n</html>\n", "status": "sent", "type": "invoice_message" } ], "scheduled_payment_requests": [], "reference": "1357", "presentment_status": "sent", "attachments": [ { "id": "fref_vmaFw5ARaXFOFgEH7gtCa", "created": { "user": "org_Y2eJHCXVqjMlXL9EfmBfc", "timestamp": "2018-09-27T20:21:15.440Z", "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910", "client_inet_address": "66.90.249.23", "client_country_code": "US", "client_location": "30.2961,-97.7369", "caller_inet_address": "66.90.249.23", "caller_country_code": "US", "caller_location": "30.2961,-97.7369" }, "modified": { "user": "SERVER", "timestamp": "2018-09-27T20:21:15.949Z", "client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910", "client_inet_address": "0.0.0.0", "client_country_code": "US", "client_location": "30.2961,-97.7369", "caller_inet_address": "0.0.0.0", "caller_country_code": "US", "caller_location": "30.2961,-97.7369" }, "file_name": "invoice123456789.pdf", "processing_state": "completed", "type": "invoice_file_reference" } ], "type": "invoice" }

An email will be sent the email addresses specified in the request. The email contains a link to the payment portal where the recipient can pay the Quick Bill.

Next step

Next, you’ll check payments.