E-Commerce & tokenized transactionsInvoice Management

Record Invoice Payment

API Explorer
https://api.ipospays.tech/invoice-service/v1/invoices/{invoiceNumber}/payment
PUT

Use this API to record a payment against an invoice. You can link one or more approved transactions to close the invoice, or mark it as paid.

OptionBodyWhat it does
Pay with transactionstransactionsLinks the approved transactions to the invoice
Mark as paidmark_as_paid: true + mark_as_paid_reasonRecords the invoice as paid outside iPOSpays, with no transaction

Option 1: pay with transactions

{
  "transactions": [
    { "transaction_id": "73804112475255476321791864572107" },
    { "transaction_id": "44702062475255476321791864583266" }
  ]
}

Option 2: mark as paid

{
  "mark_as_paid": true,
  "mark_as_paid_reason": "Paid by check 1042"
}

Path Parameters

invoiceNumber*string

Invoice number returned by Create Invoice

Match^[A-Za-z0-9]+$
Length5 <= length <= 100

Header Parameters

token*string

Authentication token generated using the API Key and Secret Key. Required for all API requests.

Idempotency-Key?string

A Unique key generated for each operation to prevent duplicate processing when retrying requests. A UUID is recommended. The key must contain 1–255 visible ASCII characters. If the same request is retried with the same key within 24 hours, the API returns the original successful response with the header Idempotent-Replayed: true instead of processing the operation again

Request Body

application/json

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com" \  -H "token: your-access-token-here" \  -H "Idempotency-Key: 8a7c2d91-4e6b-4f03-9c52-1b6d8e5a7f20" \  -H "Content-Type: application/json" \  -d '{    "transactions": [      {        "transaction_id": "32250116290654763220261010155208"      }    ]  }'

{
  "data": {
    "invoice_number": "261012153815CkSl24DHNV",
    "status": "SUCCESS",
    "tpn": "247525547632",
    "payment_link_status": "NONE",
    "transactions": [
      {
        "transaction_id": "32250116290654763220261010155208",
        "amount": 1870
      }
    ]
  },
  "message": "Invoice payment updated successfully",
  "response_code": "SUCCESS",
  "status_code": 200,
  "request_id": "TEST-20261012153830-6BCA8E",
  "timestamp": "2026-10-12T10:08:30.429Z"
}

{
  "data": null,
  "message": "The request contains invalid input parameters.",
  "response_code": "BAD_REQUEST",
  "status_code": 400,
  "request_id": "TEST-20261012153932-ROEMW6",
  "timestamp": "2026-10-12T10:09:32.407Z",
  "errors": [
    {
      "field": "transactions",
      "messages": [
        "transactions are required unless mark_as_paid is true"
      ]
    }
  ]
}

{
  "data": null,
  "message": "Missing authentication token. Please include a valid API token in your request.",
  "response_code": "TOKEN_MISSING",
  "status_code": 401,
  "request_id": "TEST-20261022075139-RYYFRR",
  "timestamp": "2026-10-22T07:51:39.729Z"
}

{
  "data": null,
  "message": "Invoice not found",
  "response_code": "NOT_FOUND",
  "status_code": 404,
  "request_id": "TEST-20261012153959-ZUX5LO",
  "timestamp": "2026-10-12T10:09:59.515Z"
}

{
  "data": null,
  "message": "Maximum of 10 transactions allowed per invoice (already linked: 10)",
  "response_code": "PRECONDITION_FAILED",
  "status_code": 409,
  "request_id": "TEST-20261012153914-Z-NOK9",
  "timestamp": "2026-10-12T10:09:14.567Z",
  "errors": [
    {
      "field": "transactions",
      "messages": [
        "Maximum of 10 transactions allowed per invoice (already linked: 10)"
      ]
    }
  ]
}

{
  "data": null,
  "message": "Unsupported content type",
  "response_code": "BAD_REQUEST",
  "status_code": 415,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>",
  "errors": [
    {
      "field": "body",
      "messages": [
        "Content-Type must be application/json"
      ]
    }
  ]
}
{
  "data": null,
  "message": "This Idempotency-Key was already used with a different request",
  "response_code": "BAD_REQUEST",
  "status_code": 422,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}
{
  "data": null,
  "message": "Too many requests, please try again in a minute",
  "response_code": "RATE_LIMITED",
  "status_code": 429,
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "An error occurred while processing your request. Please try again later.",
  "response_code": "INTERNAL_ERROR",
  "status_code": 500,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "Payment linking is temporarily unavailable, please retry",
  "response_code": "SERVICE_UNAVAILABLE",
  "status_code": 503,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

Update InvoiceCustomer Management