Add/Update Payment

Use this to record a payment taken outside Hyfin, such as a check or cash, so the invoice shows it.


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

Request
Field
Type
Description
external_id
String
Your own id for this payment, from your software. Send the same external_id again to update this payment instead of adding a new one. We match on this value but do not stop duplicates, so keep it unique within the site.
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
Timestamp
The date and time of when the payment was made. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ssZ
gateway_transaction_id
String
The unique id that was assigned to the payment record from the gateway when the payment was processed.
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. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller allocations list.
allow_missing_invoice
Boolean
When invoice.external_id names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An Add/Update Invoice call with that external_id within 30 days applies the payment to it. Without this, the payment is rejected with Invoice was not found and nothing is saved.
Default = false
payment_type
String
The type of payment method used to make the payment.
One of payment_card, ach, eft, apple_pay, google_pay, oxxo, spei, bnpl, dlocal, cash, check, other
payment_sub_type
String
The sub type of the payment method used to make the payment.
One of visa, mastercard, amex, discover, diners, jcb, checking, savings, oxxo, spei, bnpl, google_pay, dlocal, cash, check, other
status
String
The current status of the payment. created: recorded but not yet sent to the processor. failed: the attempt errored before the processor answered. declined: the processor declined it. expired: it was not completed in time. cancelled: it was cancelled before it was processed. authorized: the card was approved and the funds are held, but not yet charged. captured: the payment was charged and has not settled yet. settled: the processor has settled the funds. voided: cancelled before it settled, so no money moved. refundRequested: a refund is waiting for the payment to settle. returned: the bank sent the payment back. chargebacked: the cardholder disputed the payment. A refund is its own payment, with refunded, refundSettled or refundFailed.
Default = captured | One of failed, declined, created, expired, cancelled, authorized, captured, voided, settled, returned, refundFailed, refunded, refundSettled, chargebacked, refundRequested
transaction_type
String
The type of transaction. Recorded on the payment but not returned by any read endpoint.
One of sale, capture, refund, void
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 id we assign to the record.
id
String
The same id as _id, kept for backwards compatibility. Not returned on 4.0 and later.
errors
String [ ]
A list of errors. Will only be returned if success is false.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0"
}


		

Related