invoices

Record a payment received outside PayGood

Records money the merchant collected directly — cash, check, Zelle, and similar. There is no processor to wait on, so the allocation is applied and the invoice balance moves in the same request: a partial amount leaves the invoice partially_paid, and the full remaining balance marks it paid. Note that effectiveAt drives the invoice paidAt, so back-dating a cash payment back-dates the paid date. The recording actor is taken from the authenticated principal and is never accepted in the body. Idempotent by idempotency key per invoice.

POST

invoices

{id}

out-of-band-payments

curl --request POST \
  --url https://api-sandbox.paygood.co/invoices/{id}/out-of-band-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "idem-inv-oob-01",
  "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
  "method": "cash"
}
'

{
  "invoice": {
    "invoiceId": "<string>",
    "invoiceNumber": "<string>",
    "invoiceUrlSlug": "<string>",
    "idempotencyKey": "<string>",
    "merchantId": "<string>",
    "customerId": "<string>",
    "currentRevisionNumber": 4503599627370495,
    "currency": "<string>",
    "lineItems": [
      {
        "kind": "product_charge",
        "productId": "<string>",
        "description": "<string>",
        "quantity": 4503599627370495,
        "unitAmount": 4503599627370495,
        "lineTotal": 0,
        "priceId": "<string>"
      }
    ],
    "productTotal": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "total": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "amountPaid": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "amountRemaining": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "dueDate": "2023-11-07T05:31:56Z",
    "paidAt": "2023-11-07T05:31:56Z",
    "notes": "<string>",
    "metadata": {}
  },
  "allocation": {
    "allocationId": "<string>",
    "invoiceId": "<string>",
    "amount": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "paymentId": "<string>",
    "reference": "<string>",
    "recordedBy": {
      "display": "<string>"
    },
    "effectiveAt": "2023-11-07T05:31:56Z",
    "appliedAt": "2023-11-07T05:31:56Z",
    "canceledAt": "2023-11-07T05:31:56Z",
    "reversedAt": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization

string

header

required

Merchant API key bearer token. Legacy wire prefixes api_key_ and api_ are also accepted.

Path Parameters

string

required

Invoice TypeID (inv_...) the payment applies to.

Example:

"inv_01hxy8m1nqk9g3x3y3p0azq2va"

Body

application/json

Out-of-band payload with idempotency key, merchant scope, method, and optional amount, effective date, and reference.

idempotencyKey

string

required

Idempotency key for safe retries of the recording per invoice.

Minimum string length: 1

merchantId

string

required

Merchant TypeID (mer_...) used for authorization scope.

method

enum<string>

required

How the money was received outside PayGood.

Available options:

cash,

check,

bank_transfer,

wire,

zelle,

venmo,

cash_app,

paypal,

other

amount

integer

Minor-unit amount received. Defaults to the full remaining balance. Must not exceed it.

Required range: 0 < x <= 9007199254740991

effectiveAt

string<date-time>

When the money actually arrived. Defaults to now, cannot be in the future, and drives the invoice paidAt — so back-dating a cash payment back-dates the paid date.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

reference

string

Check number, Zelle confirmation, or free-form note. Required when method is other.

Required string length: 1 - 500

Response

Payment recorded. Returns the invoice with its balance already updated, plus the applied allocation.

invoice

object

required

Show child attributes

allocation

object

required

Show child attributes

curl --request POST \
  --url https://api-sandbox.paygood.co/invoices/{id}/out-of-band-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "idem-inv-oob-01",
  "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
  "method": "cash"
}
'

{
  "invoice": {
    "invoiceId": "<string>",
    "invoiceNumber": "<string>",
    "invoiceUrlSlug": "<string>",
    "idempotencyKey": "<string>",
    "merchantId": "<string>",
    "customerId": "<string>",
    "currentRevisionNumber": 4503599627370495,
    "currency": "<string>",
    "lineItems": [
      {
        "kind": "product_charge",
        "productId": "<string>",
        "description": "<string>",
        "quantity": 4503599627370495,
        "unitAmount": 4503599627370495,
        "lineTotal": 0,
        "priceId": "<string>"
      }
    ],
    "productTotal": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "total": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "amountPaid": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "amountRemaining": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "dueDate": "2023-11-07T05:31:56Z",
    "paidAt": "2023-11-07T05:31:56Z",
    "notes": "<string>",
    "metadata": {}
  },
  "allocation": {
    "allocationId": "<string>",
    "invoiceId": "<string>",
    "amount": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "paymentId": "<string>",
    "reference": "<string>",
    "recordedBy": {
      "display": "<string>"
    },
    "effectiveAt": "2023-11-07T05:31:56Z",
    "appliedAt": "2023-11-07T05:31:56Z",
    "canceledAt": "2023-11-07T05:31:56Z",
    "reversedAt": "2023-11-07T05:31:56Z"
  }
}