First Integration BlueHill Payments API

This guide will get you all set up and ready to use the BlueHill Payments API. We'll cover how to get started and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Before you make requests to the BlueHill Payments API, you will need to grab your API key from your dashboard. You find it under Settings » API.

Check out our list of payment and workflow integrations

POST/customers/v2/create

Create Customer

All transactions and billing information are associated with a customer. You can create a customer by making a POST request to the customers/v2/create endpoint. The following attributes are required:

This endpoint allows you to create a new customer. All fields except notes are Required

Optional attributes

Name
None
Type
None
Description
There are no additional attributes for this operation

Models Used

Customers

Request

POST

customers/v2/create

  curl --location --request POST 'https://api.bluehillpayments.io/customers/v2/create' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "organizationId": "{{organizationId}}",
      "firstName": "Himanshu",
      "lastName": "Minocha",
      "street": "123 Alphabet St.",
      "town": "Chicago", 
      "zipCode": 60654, 
      "state": "MA", 
      "email": "himanshu@example.com", 
      "phoneNumber": "555-555-5555", 
      "company": "BlueHill Payments"
  }

Response

  {
      "data": {
          "company": "BlueHill Payments",
          "createdAt": "2023-01-11 02:03:44",
          "customerIds": null,
          "email": "himanshu@example.com",
          "fee": null,
          "firstName": "Himanshu1",
          "id": "39E330B8EAAA4244A01C56E13D0612BF",
          "lastName": "Minocha",
          "notes": null,
          "organizationId": "{{organizationId}}",
          "phoneNumber": "555-555-5555",
          "state": "MA",
          "street": "123 Alphabet St.",
          "town": "Chicago",
          "uniqueHash": "C0C72F7F99A94ED1A510194C499C852B",
          "updateAt": "2023-01-11 02:03:44",
          "zipCode": "60654"
      },
      "status": "success"
  }

POST/payment-method/create

Create PaymentMethod

This endpoint allows you to add a new conversation between you and a contact or group. A contact or group id is required to create a conversation.

Sandbox Cards:

Name	Value
`cardNumber`	4111 1111 1111 1111
`expirationMonth`	12
`expirationYear`	2027
`cvv`	123

Required attributes

Name
customerId
Type
string
Description
Unique identifier for the customer.
Name
cardNumber
Type
string
Description
The card number
Name
expirationMonth
Type
string
Description
The expiration month of the card.
Name
expirationYear
Type
string
Description
The expiration year of the card.
Name
cvv
Type
string
Description
The cvv of the card.

IMPORTANT: This will not be stored past the first authorization
Name
isLive
Type
boolean
Description
Whether or not this is a live card.

IMPORTANT: This will determine if a charge is sandbox or production

Request

POST

/payment-method/create

curl --location --request POST 'https://api.bluehillpayments.io/payment-method/create' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId" : "EC8CD046740E43298BB1636DB0923A91", 
    "cardNumber" : "4111 1111 1111 1111", 
    "expirationMonth": "08",
    "expirationYear": "2026", 
    "cvv": "264",
    "type": "card",
    "isLive": false
}'

Response

{
    "achToken": null,
    "cardNetwork": "Visa",
    "customerId": "EC8CD046740E43298BB1636DB0923A91",
    "expirationMonth": "08",
    "expirationYear": "2026",
    "id": "7E1F9B4988BE4A5A91FE9CB1B3F0056D",
    "isDefault": true,
    "lastFour": "1111",
    "paymentMethodType": "credit_card"
}

POST/transactions/v2/create

Create a Transaction

Create a transaction and make a charge

Required attributes

Name
customerId
Type
string
Description
Unique identifier for the customer.
Name
paymentMethodId
Type
string
Description
Unique identifier for the payment method.
Name
organizationId
Type
string
Description
Unique identifier for the organization.
Name
amount
Type
float
Description
The amount of the transaction.
Name
isLive
Type
boolean
Description
Whether or not this is a live charge.

IMPORTANT: This will determine if a charge is sandbox or production

Request

POST

/payment-method/create

  curl --location --request POST 'https://api.bluehillpayments.io/transactions/v2/create' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "amount": 12.12,
      "customerId" : "EC8CD046740E43298BB1636DB0923A91",
      "paymentMethodId" : "",
      "organizationId": "{{organizationId}}",
      "isLive": true
  }'

Response

  {
      "IPv4": "IP Not found",
      "alpha2": "US",
      "amount": 12.12,
      "bankCity": null,
      "bankCountryCode": "USA",
      "bankName": "JPMORGAN CHASE BANK, N.A.",
      "bankPhone": "1-800-432-3117",
      "bankUrl": "www.chase.com",
      "billingFrequency": null,
      "brand": "VISA",
      "cardType": "Visa",
      "city": "Not found",
      "countryName": "United States",
      "country_code": "Not found",
      "country_name": "Not found",
      "createdAt": "2023-01-17 16:08:39",
      "currency": "USD",
      "customerCompany": "Example Company",
      "customerId": "BFED9A828CC8400089380D7084EEE355",
      "customerName": "Himanshu Smith",
      "cycles": null,
      "feeAmount": 0.65,
      "fullResponse": null,
      "id": "9A572C31137248EA9089C3E98E4AE007",
      "isLive": false,
      "isPrepaid": 0,
      "isRecurring": false,
      "last4": "1111",
      "latitude": "Not found",
      "longitude": "Not found",
      "notes": null,
      "organizationId": "{{organizationId}}",
      "outcome": "unknown",
      "paymentMethodId": "DEC7CDE96D1D461B899276AF66AE0F8E",
      "planName": null,
      "postal": "Not found",
      "processedGateway": 2,
      "processedGatewayName": "Stripe",
      "processorChargeId": "ch_3MRNKlF3W5fmwRAr0DZqJxh2",
      "state": "Not found",
      "type": "CREDIT",
      "updateAt": "2023-01-17 16:08:39"
  }

Read the docs for the Conversations endpoint

What's next?

Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the BlueHill Payments API: