Get Payment

Use this when you need the full details of one payment, for example after a payment webhook.


The following endpoint can be used to retrieve the details of a payment within the Hyfin application.


Endpoint

The following endpoint can be used to retrieve a payment. You must replace the {base_url} , {external_id} and {site_id} variables with the appropriate values.

GET
{base_url}/api/v3.1/site/{site_id}/payment/{external_id}
Request
No body is required for this API call
Response
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.
_id
String
The id of the payment, assigned by the system.
display_name
String
The secure friendly display name of the payment method. Example: VISA **** 3421.
last_4
String
The last 4 digits of the payment method. Only returned for payments taken through a stored payment method; a payment recorded through this API has none, so it is omitted.
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.
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
created_at
Timestamp
The date the payment was created. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
updated_at
Timestamp
The date the payment was last updated. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
manual_status_change
The latest status change a user made by hand in the app, such as marking a payment declined. Use it to tell a manual change apart from one the payment gateway reported. Omitted when no one has changed the payment's status by hand.
reference_number
String
The unique reference number assigned to the payment by the system, displayed to the merchant.
early_pay_discounts_and_late_fees
Number
The net of any early payment discount and late fee applied to the payment. Format = 0.00
is_refund
Boolean
Whether the payment is a refund of another payment.
orig_payment
String
On a refund, the _id of the payment it refunded. Omitted on payments that are not refunds.
custom_fields
Object
The custom fields recorded on the payment, as name/value pairs. {} when there are none.
allocations
How the payment was applied. A payment split across several invoices has one entry per invoice.
			
{
  "_id": "61f32dc2f62bdc6a48945067",
  "external_id": "65432325",
  "reference_number": "N7E6N7T75WM9-PGEM",
  "gateway_transaction_id": "53912387124235234",
  "payment_type": "payment_card",
  "payment_sub_type": "amex",
  "display_name": "AMEX ****** 3422",
  "amount": 30,
  "tip": 0,
  "tax": 0,
  "fee": 0,
  "early_pay_discounts_and_late_fees": 0,
  "paid_on": "2021-03-15T16:32:11Z",
  "status": "captured",
  "is_refund": false,
  "custom_fields": {},
  "allocations": [
    {
      "ref_type": "Invoice",
      "ref": {
        "_id": "61f32dc2f62bdc6a48951255",
        "external_id": "65432661",
        "reference_number": "N7E6NICAC2FE"
      },
      "amount": 30
    }
  ],
  "created_at": "2025-05-30T19:19:44.143Z",
  "updated_at": "2025-05-30T19:19:44.143Z"
}


		

Related