Invoice Payments

Hiveage allows you to enter payments for invoices.

The Payment Object

EXAMPLE OBJECT

{
  "payment": {
    "id": 2234,
    "date": "2015-01-20",
    "amount": "10.0",
    "formatted_amount": "$10.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Attribute	Description
id	integer Payment ID
date	string Date the payment was received.
amount	string Payment amount
formatted_balance	string
balance	string
formatted_balance	string
payment_method	string The following payment methods are supported: `cash`, `check`, `other`, `bank_transfer`, `google_wallet`, `wepay`, `twocheckout`, `paypal`, `paypal_pro`, `braintree`, `authorizenet` and `stripe`.
details	string Payment details
combined_payment_details	string `payment_method` and `details` values combined
currency_iso_code	string
currency_symbol	string
payment_receipt_no	string Payment receipt number
payment_receipt_hash_key	string Payment hash key.
state	string For offline payments (e.g. bank transfers), whether the payment is realized or unrealized.
created_at	string

Create a New Payment

DEFINITION
POST https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d payment[amount]="10" \
  -d payment[payment_method]="paypal" \
  -d payment[date]="2015-01-25" \
  -d payment[details]="Payment description" \


EXAMPLE RESPONSE
{
  "payment": {
    "id": 2235,
    "date": "2015-01-20",
    "amount": "10.0",
    "formatted_amount": "$10.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter	Description
date	string Date the payment was received.
amount	string Payment amount
payment_method	string The following payment methods are supported: `cash`, `check`, `other`, `bank_transfer`, `google_wallet`, `wepay`, `twocheckout`, `paypal`, `paypal_pro`, `braintree`, `authorizenet` and `stripe`.
details	string Payment details

Return

Returns the invoice payment object.

Retrieve a Payment

Retrieve a payment with a specified ID.

DEFINITION
GET https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{
  "payment": {
    "id": 10,
    "date": "2015-01-20",
    "amount": "10.0",
    "formatted_amount": "$10.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Returns

Returns a payment JSON object if a valid payment id was provided. Returns an error otherwise.

Update a Payment

DEFINITION
PUT https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10 \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d payment[amount]="5" \

EXAMPLE RESPONSE
{
  "payment": {
    "id": 10,
    "date": "2015-01-20",
    "amount": "5.0",
    "formatted_amount": "$5.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter	Description
date	string Date the payment was received.
amount	string Payment amount
payment_method	string The following payment methods are supported: `cash`, `check`, `other`, `bank_transfer`, `google_wallet`, `wepay`, `twocheckout`, `paypal`, `paypal_pro`, `braintree`, `authorizenet` and `stripe`.
details	string Payment details

Delete a Payment

Deletes a payments object permanently.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "deleted": true,
  "id": "10"
}

Returns an object with a deleted parameter on success.

List All Payments

Returns a list of payments. The payments are returned sorted by date.

DEFINITION
GET https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "payments": [{
    "id": 10,
    "date": "2015-01-20",
    "amount": "5.0",
    "formatted_amount": "$5.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  },
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter	Description
per_page	optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page	optional Page in results set

NOTE: The list has been ordered by created_at.

Mark as Realized

DEFINITION
POST https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/[id]/mark_as_realized

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/[id]/mark_as_realized \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "payment": {
    "id": 10,
    "date": "2015-01-20",
    "amount": "5.0",
    "formatted_amount": "$5.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

NOTE: Offline payments are saved as unrealized payments. To mark them as realized, the user has to log into Hiveage and do so manually.