API conventions

​

IDs in the path

​

companyCode

• If you do not send it, the API responds 400 BAD_REQUEST asking for it.
• If you send a code that is not a company of your client, the API responds 422 RESOLUTION_ERROR.
• In the PATCH endpoints (contacts, products, payment links, subscriptions, and debts), companyCode in the body is taken as context: it is not treated as a field to modify, nor rejected as a non-editable field.

​

Malformed JSON

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Malformed JSON in request body",
    "details": [
      { "field": "body", "issue": "Invalid JSON syntax" }
    ]
  },
  "requestId": "req_3f8a1c9e2b"
}

​

Pagination

{
  "data": [],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 0,
    "hasMore": false
  },
  "requestId": "req_a1b2c3d4e5f6"
}

​

Dates

• date-time fields in responses (createdAt, updatedAt, expiresAt, etc.) always come in UTC with milliseconds and Z: 2026-09-24T17:38:21.107Z.
• Date fields (dueDate, startDate, endDate) use YYYY-MM-DD and must be valid calendar dates (2026-02-30 returns 400).
• The date-times you send (for example the expiresAt of a payment link) must be RFC 3339, with Z or an offset (2026-12-31T23:59:59-06:00). They are converted and stored in UTC, and returned in UTC even if you sent them with an offset.
• The createdAtFrom and createdAtTo filters of list endpoints accept a date (YYYY-MM-DD) or an RFC 3339 date-time. A date alone covers the full UTC day, included at both ends. The details of each list are in Debts and Payment links.

​

Strict types

• Booleans: only accept the literal true or false. "true", 1, "yes", etc. return 400 INVALID_REQUEST with one entry in details[] per field. This applies to allowOverduePayment and allowPartialPayments in POST /v2/debts, to autopay, allowOverduePayment, allowPartialPayments, and enforcePaymentOrder in POST /subscriptions, and to the editable booleans of PATCH /subscriptions/{id}. The active query param of GET /products also accepts only true or false.
• description: must be a string. Any other type returns 400.
• Amounts: numbers in pesos with up to 2 decimals.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Validation failed: allowPartialPayments must be a boolean.",
    "details": [
      { "field": "allowPartialPayments", "issue": "allowPartialPayments must be a boolean." }
    ]
  },
  "requestId": "req_3f8a1c9e2b"
}

​

additionalData

• It must be a flat object. A scalar (string, number, or boolean) returns 400 INVALID_REQUEST.
• It cannot use reserved keys, which TapiPay writes internally: description, paymentMethods, productName, externalProductId, debtExpirationDate, overduePayment, allowPartialPayments, recurringDebt, and debtReference. If any of them appears, the API responds 400 INVALID_REQUEST with details[].field = "additionalData".

{
  "additionalData": {
    "source": "crm",
    "folio": "F-2026-0042"
  }
}

​

Undeclared fields

• In POST /v2/debts and in every PATCH, a field that is not in the contract returns 400 INVALID_REQUEST. In POST /v2/debts the field comes in details[].field.
• In POST /contacts, POST /products, POST /payment-links, and POST /subscriptions, undeclared fields are ignored.

​

Validation errors