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/v4/site/{site_id}/payment/addUpdate

Request
Field
Type
Description
_id
String
The id we assign to this payment. Leave it out when creating a payment, and send it when updating one.
externalId
String
Your own id for this payment, from your software. Required when _id is not passed in. Send the same externalId 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.
displayName
String
The secure friendly display name of the payment method. Example: VISA **** 3421.
amount
Number
The amount that was paid. This is an integer number of cents, so 1035 means $10.35.
paidOn
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:ss.SSSZ
gatewayTransactionId
String
The unique id that was assigned to the payment record from the gateway when the payment was processed.
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.
allowMissingInvoice
Boolean
When invoice.externalId 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 externalId 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
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
site
String
The _id of the site
type
String
The type of payment method used to make the payment. credit is a credit applied to an invoice (see credit); it is set by the system and cannot be sent.
One of payment_card, ach, eft, apple_pay, google_pay, oxxo, spei, bnpl, dlocal, cash, check, other, credit
subType
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, creditNote
totals
How the payment amount breaks down.
allocations
The allocations for the payment. This is an array of objects that specify how the payment was allocated to different orders or refunds.
deleted
Boolean
This flag represents whether the record is deleted and no longer available to be used.
Sample Request
			
{
  "externalId": "65432325",
  "gatewayTransactionId": "53912387124235234",
  "type": "payment_card",
  "subType": "visa",
  "displayName": "VISA **** 5123",
  "amount": 3515,
  "paidOn": "2021-01-01T14:32:18.000Z",
  "status": "captured",
  "allocations": [
    {
      "refType": "Invoice",
      "ref": "61f32dc2f62bdc6a48951255",
      "amount": 3515
    }
  ]
}


		
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.
updatedAt
The date the record was last updated. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}


		

Related