Add/Update Payment

The following endpoint can be used to add or update a payment within the Builder Pay Pro 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

The same endpoint is used to add or update a payment. If the {_id} is provided, the payment will be updated otherwise it will be inserted.

Request

Field

Type

Description

_id

String

The id of the payment. This field is auto generated by the system and is not required when creating a new payment, but it is required when updating an existing payment.

externalId

String

The unique payment id from the source system/database. Required when _id is not passed in. If we detect a record with the same externalId, it will be updated, otherwise it will be added.

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

Date

The date and time of when the payment was made. Format = YYYY-MM-DDTHH:mm:ssZ

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.
Default = captured | One of declined, authorized, captured, voided, settled, returned, refundFailed, refunded, refundSettled

site

String

The _id of the site

type

String

The type of payment method used to make the payment.
One of payment_card, ach, cash, check

subType

String

The sub type of the payment method used to make the payment.
One of checking, savings, visa, mastercard, discover, amex, cash, other

totals

The total amounts of the payment.

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:18Z",
  "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 auto generated id assigned to the record.

updatedAt

Date

The date the record was last updated.

errors

String [ ]

A list of errors. Will only be returned if success is false.

Sample Response (Successful)

			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}

Sample Response (Failed)

			
{
  "success": false,
  "errors": [
    "invalid field2",
    "missing field_name"
  ]
}