Record Invoice Payment

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.

Option	Body	What it does
Pay with transactions	`transactions`	Links the approved transactions to the invoice
Mark as paid	`mark_as_paid: true` + `mark_as_paid_reason`	Records 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

transactions?

Required unless mark_as_paid is true. Not allowed with mark_as_paid. At most 10 per request (and per invoice in total).

Items1 <= items <= 10

mark_as_paid?boolean

Close without a transaction (needs mark_as_paid_reason)

mark_as_paid_reason?|

Required when mark_as_paid is true. Letters, numbers, spaces and . , ! ? ( ) ' _ - only; max 255 characters.

Response Body

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

Record Invoice Payment

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

404application/json

409application/json

415application/json

422application/json

429application/json

500application/json

503application/json

Link one transaction: invoice becomes SUCCESS

Link several transactions in one call

Add another transaction to an invoice already paid through this API

mark_as_paid: close without a transaction

mark_as_paid "true" as text is accepted

Neither transactions nor mark_as_paid

mark_as_paid false without transactions

transactions is an empty array

transaction_id missing

transaction_id with invalid characters

Same transaction_id twice in one request

Transaction not found

Transaction already voided

Transaction reversed

Transaction refunded

Transaction not approved

Transaction TPN differs from the invoice TPN

mark_as_paid without mark_as_paid_reason

mark_as_paid together with transactions

mark_as_paid_reason with invalid characters

Unknown field

transactions is not an array

transactions item is a string

transaction_id empty

transaction_id blank

transaction_id not a string

transaction_id longer than 64

Unknown key inside a transaction

mark_as_paid not a boolean

mark_as_paid "yes" is read as false (only true, "true" or "1" mean true)

mark_as_paid_reason blank

mark_as_paid_reason longer than 500 (reported as invalid characters)

mark_as_paid_reason not a string

11 transaction_ids: each ID is checked first, so an unknown ID fails before the 10-transaction limit

Body is a JSON array

Nested __proto__ key

REFUND transaction

PREAUTH transaction

invoiceNumber wrong format

invoiceNumber shorter than 5

invoiceNumber longer than 100

Idempotency-Key empty, too long or with non-ASCII / space characters

Malformed JSON body

token header missing

Transaction of another merchant

Transaction from a TPN that is not registered to the merchant

Invalid token

Expired token

Token could not be verified

Token revoked or inactive

Token is not a MERCHANT or STORE token

Account is inactive (message starts with MERCHANT or STORE)

Invoice does not exist

Invoice of another merchant

Internal child row of a multi-transaction payment

11th transaction on one invoice

Transaction already linked to this invoice

Invoice with an active payment link

Add a transaction after mark_as_paid

Add a transaction to an invoice paid in the portal

mark_as_paid on an invoice already paid through this API

Same transaction being linked by a parallel request

Invoice is being collected in the portal

Same Idempotency-Key while the first request is still running

Unexpected server error

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`