invoices

Charge a payment instrument against an invoice

Charges a payment instrument for all or part of the remaining balance. The invoice balance does not move until the processor reports a capture, which this endpoint waits briefly for so the response’s amountPaid and status usually reflect the settled state; if capture hasn’t landed by the time the wait elapses, the allocation is still pending and the response reflects the pre-charge state. Idempotent by idempotency key per invoice — a replay returns the existing allocation without charging again.

POST

invoices

{id}

payments

curl --request POST \
  --url https://api-sandbox.paygood.co/invoices/{id}/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
  "paymentInstrumentId": "pi_01hxy8m1nqk9g3x3y3p0azq2p1"
}
'

{
  "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_...) to charge.

Example:

"inv_01hxy8m1nqk9g3x3y3p0azq2va"

Body

application/json

Charge payload with merchant scope, payment instrument, and optional partial amount. Supply idempotency via the Idempotency-Key header.

merchantId

string

required

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

paymentInstrumentId

string

required

Payment instrument TypeID (pi_...) to charge. Must belong to the invoice's customer and be active.

amount

integer

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

Required range: 0 < x <= 9007199254740991

Response

Charge accepted. Returns the invoice plus the newly created pending allocation.

invoice

object

required

Show child attributes

allocation

object

required

Show child attributes

curl --request POST \
  --url https://api-sandbox.paygood.co/invoices/{id}/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
  "paymentInstrumentId": "pi_01hxy8m1nqk9g3x3y3p0azq2p1"
}
'

{
  "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"
  }
}