Charge a payment instrument against an invoice

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' \
  --data '
{
  "idempotencyKey": "idem-inv-charge-01",
  "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
  "paymentInstrumentId": "pi_01hxy8m1nqk9g3x3y3p0azq2p1"
}
'

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

Example:

"inv_01hxy8m1nqk9g3x3y3p0azq2va"

Body

application/json

Charge payload with idempotency key, merchant scope, payment instrument, and optional partial amount.

idempotencyKey

string

required

Idempotency key for safe retries of the charge per invoice.

Minimum string length: 1

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' \
  --data '
{
  "idempotencyKey": "idem-inv-charge-01",
  "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
  "paymentInstrumentId": "pi_01hxy8m1nqk9g3x3y3p0azq2p1"
}
'

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