Hyfin Logo
API Docs 3.0API Docs 3.1API Docs 4.0 SimpleAPI Docs 4.0

Add/Update Payment

The following endpoint can be used to add or update a payment within the Hyfin application that were already processed.

Endpoint

The following endpoint can be used to add or update a payment. You must replace the {base_url} and {site_id} variable with the site id that was provided when the site was created.

POST
{base_url}/api/v3/site/{site_id}/payment/addUpdate

The same endpoint is used to add or update a payment. If a payment already exists with the {external_id} , the payment will be updated otherwise it will be inserted.
Request
Field
Type
Required
Description
external_id
String
The unique payment id from the source system/database. If we detect a record with the same `external_id`, it will be updated, otherwise it will be added.
gateway_transaction_id
String
The unique id that was assigned to the payment record from the gateway when the payment was processed.
display_name
String
The secure friendly display name of the payment method. Example: `VISA **** 3421`.
amount
Number
The amount that was paid. Format = 0.00
paid_on
Date
The date and time of when the payment was made. Format = YYYY-MM-DDTHH:mm:ssZ
tip
Number
--
The tip amount that was added. Format = 0.00
tax
Number
--
The tax amount that was added. Format = 0.00
fee
Number
--
The fee amount that was added. Format = 0.00
invoice
--
A reference to the invoice record.
payment_type
String
--
The type of payment method used to make the payment.
One of `payment_card`, `ach`, `cash`, `check`
payment_sub_type
String
--
The sub type of the payment method used to make the payment.
One of `checking`, `savings`, `visa`, `mastercard`, `discover`, `amex`, `cash`, `other`
status
String
--
The current status of the payment.
Default = `captured` | One of `declined`, `authorized`, `captured`, `voided`, `settled`, `returned`, `refundFailed`, `refunded`, `refundSettled`
active
Boolean
--
This flag represents whether the payment record is active.
Default = `true`
Sample Request
			
				{
  "external_id": "65432325",
  "gateway_transaction_id": "53912387124235234",
  "payment_type": "payment_card",
  "payment_sub_type": "visa",
  "display_name": "VISA **** 5123",
  "amount": 35.15,
  "paid_on": "2021-01-01T14:32:18Z",
  "status": "captured",
  "invoice": {
    "external_id": "65432661"
  }
}
Response
Field
Type
Description
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if `success` is `true`.
One of `added`, `updated`
_id
String
The auto generated id assigned to the record.
errors
String [ ]
A list of errors. Will only be returned if `success` is `false`.
Sample Response (Successful)
			
				{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0"
}
Sample Response (Failed)
			
				{
  "success": false,
  "errors": [
    "invalid field2",
    "missing field_name"
  ]
}