Creating an invoice

Using the API, you can create an invoice from within your application. After you create the invoice, users pay it in our payment portal.

This type of integration requires a partner OAuth application. If you do not have a partner OAuth application (for example, if you are a merchant), contact AffiniPay Support.

Use the following steps to create the invoice and send the email with the link to our portal:

Determine where invoice fees will be deposited.
Determine who is receiving the goods or services.
Determine how much will be charged.
Set unique identifiers.
Choose the date.
Upload attachments.
Choose how to send the link to the payment portal.
Create the invoice.

1: Determine where invoice fees will be deposited

Invoice 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",
      "currency": "USD",
      "processing_accounts": [
      {
        "id": "O4dotqecQnuNVM3o9ukr1A",
        "name": "My Operating",
        "required_payment_fields": "cvv,postal_code",
        "accepted_card_types": "VISA,MASTERCARD,AMERICAN_EXPRESS,DISCOVER",
        "cvv_policy": "OPTIONAL",
        "avs_policy": "SUBMIT_IGNORE_RESULT",
        "swipe_cvv_policy": "OPTIONAL",
        "swipe_avs_policy": "SUBMIT_IGNORE_RESULT",
        "swipe_required_payment_fields": "cvv",
        "type": "card"
      }
    ]
  },
  {
      "id": "bank_XugcE9HWGZNdLFLPvmP82",
      "name": "BoA",
      "bank_name": "Bank of America Corporation",
      "trust": true,
      "account_id": "*****9876",
      "currency": "USD",
      "processing_accounts": [
      {
        "id": "QRoxK56MTgmlQrmSbRJnkA",
        "name": "My Trust",
        "required_payment_fields": "cvv,postal_code",
        "accepted_card_types": "VISA,MASTERCARD,AMERICAN_EXPRESS,DISCOVER",
        "cvv_policy": "OPTIONAL",
        "avs_policy": "SUBMIT_IGNORE_RESULT",
        "swipe_cvv_policy": "OPTIONAL",
        "swipe_avs_policy": "SUBMIT_IGNORE_RESULT",
        "swipe_required_payment_fields": "cvv",
        "type": "card"
      }
    ]
  }
]

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 invoice.

2: Determine who is receiving the goods or services

An invoice must have a contact associated with it. This contact is typically the client who is receiving the goods or services associated with the invoice.

If the client is new to the system, create a contact for them.
If the client already has a contact, search your contacts to find the correct one.

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@example.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@example.com",
  "contact_code": "0010",
  "owner_id": "org_Y2eJHCXVqjMlXL9EfmBfc",
  "owner": {
      "id": "org_Y2eJHCXVqjMlXL9EfmBfc",
      "test_mode": false,
      "owner_id": "org_aQ5urhpA1HUBJIxAvDfsM",
      "preferred_email": "myemail@example.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@example.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 invoice.

3: Determine how much will be charged

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

description. For an invoice, this field is for your reference.
rate_per_quantity. The amount charged per unit. For an invoice, set this to the total amount to be charged, in cents.
quantity. The number of units to be charged. For an invoice, set this property to 1.
rate_type. The units used to measure the rate to be charged for the item. Set this property to units.

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

For example, if you provide this information:

description: Consulting fee
rate_per_quantity: 10000
quantity: 1
rate_type: units

The invoice will show a balance due of $100.

4: Set unique identifiers

You should set a source ID to prevent duplicate invoices in our system and to uniquely identify the invoice in your environment. The source ID must be a URI that uniquely identifies the invoice in your environment. It’s recommended that you use the format:

partnername:unique_identifier

For example, mypartnercompany:12345

You’ll add this unique identifier as the source_id parameter of the invoice.

In addition, you can set a reference that includes a unique identifier from your system, such as the invoice number. This reference information will be displayed in the payment portal and will help users identify the invoice. You’ll add this as the reference parameter of the invoice.

5: Choose the date

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

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

6: Upload attachments

You can send supplemental files with your invoice. They’ll be available in the portal where users pay their invoice.

Before you create the invoice, upload your files using the merchant’s contact ID. After you’ve confirmed that processing is completed, include the id for each file in the attachments section of the invoice.

7: Choose how to send the link to the payment portal

You must send a link to the payment portal to the individual who will pay the invoice. You can also send it to any other interested parties, such as the merchant. You must choose whether to send this link yourself or to have AffiniPay send it for you.

Send the link to the payment portal yourself

To send the link yourself:

Create a contact hash for the contact who is receiving the goods and services to obtain a link to the payment portal.
Send the url from the contact hash to the user who will pay the invoice. Do not send this link until after you have created the invoice.

Have AffiniPay send the link to the payment portal

You can have AffiniPay send an email with a link to the payment portal after the invoice is created.

To have AffiniPay send the link in an email:

Obtain the email addresses for the individuals who will receive the email. If you don’t know what these email addresses are, you can search your contacts and retrieve the email addresses associated with them or prompt the user for email addresses.
Include the email addresses in the invoice_messages parameter of the invoice.

Customize the email from AffiniPay

When you send an invoice, the system sends an email to everyone you include in the invoice_messages parameter.

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:

Submit the same subject for all merchants and all emails, such as:
Request for Payment
Allow the merchant to provide you with the subject that will be used for all its emails, which you’ll submit in the request when you create the invoice.

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 invoice.

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:

Submit the same email text for all merchants and all emails, such as:
For your convenience, our firm accepts payments online. To make a payment, please click the link below.
Allow the merchant to provide you with the email text that will be used for all its emails, which you’ll submit in the request when you create the invoice.

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

8: Create the invoice

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

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

The bank_account_id for a bank account associated with a merchant account that is in test mode.
To confirm that a merchant account is in test mode, log into the AffiniPay/LawPay/CPACharge web application using the credentials for the merchant account you want to use for test. If it’s in test mode, you’ll see a red “TEST MODE” bar at the top of the page. If it’s not in test mode, click your name in the top right corner of the page and click Switch to Test Mode.
A contact_id for a contact that has its test_mode parameter set to true.
The test_mode parameter set to true for the invoice itself.

Example request: Creating a new invoice

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": "Invoice 3",
  "source_id": "mypartnercompany:12345",
  "line_items": [
    {
      "description": "Consulting fee",
      "rate_per_quantity": "10000",
      "quantity": "1",
      "rate_type": "units"
    }],
  "invoice_messages": [
    {
      "email_addresses": ["eripley@example.com", "billing@example.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@example.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@example.com",
                "billing@example.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": "Invoice 3",
    "source_id": "mypartnercompany:12345",
    "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 invoice.