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' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
  "method": "cash"
}
'

{
  "invoice": {
    "invoiceId": "<string>",
    "invoiceNumber": "<string>",
    "invoiceUrlSlug": "<string>",
    "idempotencyKey": "<string>",
    "merchantId": "<string>",
    "customerId": "<string>",
    "currentRevisionNumber": 4503599627370495,
    "status": "draft",
    "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>"
    },
    "acceptedPaymentMethods": [
      "card"
    ],
    "additionalNotificationEmails": [
      "jsmith@example.com"
    ],
    "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>",
    "kind": "payment",
    "status": "pending",
    "amount": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "paymentId": "<string>",
    "method": "cash",
    "reference": "<string>",
    "recordedBy": {
      "principalType": "member",
      "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.

Headers

Idempotency-Key

string

required

Client-supplied unique key for safe retries of this mutating request. Scoped per merchant or resource as documented on each endpoint.

Example:

"idem-01"

Path Parameters

string

required

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

Example:

"inv_01hxy8m1nqk9g3x3y3p0azq2va"

Body

application/json

Out-of-band payload with merchant scope, method, and optional amount, effective date, and reference. Supply idempotency via the Idempotency-Key header.

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' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
  "method": "cash"
}
'

{
  "invoice": {
    "invoiceId": "<string>",
    "invoiceNumber": "<string>",
    "invoiceUrlSlug": "<string>",
    "idempotencyKey": "<string>",
    "merchantId": "<string>",
    "customerId": "<string>",
    "currentRevisionNumber": 4503599627370495,
    "status": "draft",
    "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>"
    },
    "acceptedPaymentMethods": [
      "card"
    ],
    "additionalNotificationEmails": [
      "jsmith@example.com"
    ],
    "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>",
    "kind": "payment",
    "status": "pending",
    "amount": {
      "amount": 4503599627370495,
      "currency": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "paymentId": "<string>",
    "method": "cash",
    "reference": "<string>",
    "recordedBy": {
      "principalType": "member",
      "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"
  }
}