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.1/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
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
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
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
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
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
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"
]
}