Skip to main content

FAQ

Questions About Authentication (AccessToken)​

How to obtain an AccessToken?

All endpoints require authorization. To get a token, send the username and password to the POST /auth/token service.

This token must be used in the Header for all requests:

Authorization: Bearer {AccessToken}

How long is the token valid?

The expiresIn field is in seconds (for example 3600 → 1 hour). When the time expires, the system returns 401 Unauthorized. A new token must be obtained.

Is there refresh token support?

If available, a new accessToken can be obtained with the refreshToken. If your system does not support refresh tokens, the user session must be renewed.

I get a “401 Unauthorized” error, why?

  • The token may have expired.
  • The token may belong to the wrong user/tenant.
  • Header is missing or incorrectly formatted (Bearer might be forgotten).

Solution: Renew the token and ensure the format is correct.

Request Format & Submission Rules​

Is Content-Type required in API requests?

Yes. The following header must be present for all POST and PUT requests:

Content-Type: application/json

Otherwise, a 400 Bad Request may occur.

How should empty fields be sent?

For string fields to be left empty:

"address": null

or omit them entirely. Sending an empty string ("") is not recommended.

I received a “Required field missing” error, how to fix it?

The response “details” section indicates which field is missing

{
  "errorCode": "ERR_VALIDATION",
  "details": { "field": "email" }
}

Check the endpoint definition to see if the field is mandatory.

Can boolean fields be sent as strings?

No.

Instead of "isActive": "true", it must be boolean:

"isActive": true

Data Operations (Create, Update, Delete)​

Why does the same “erpCode” or “code” cause an error?

These fields must be unique in the system.

If the same value exists:

{
  "errorCode": "ERR_CONFLICT",
  "message": "The same erpCode conflicts with another record."
}

Check if the code is in use before adding a new record.

Can code be changed in update (PUT) operations?

Yes, updateCode is used to find the existing record; the code field can be updated with a new value.

However, if the new code conflicts with another record, it returns 409 Conflict.

Can deleted records be restored?

No.

DELETE endpoints are permanent.

For example, cards deleted via /vendor/creditcard cannot be restored.

Which fields are optional and which are mandatory?

Each endpoint specifies under the “Mandatory” column.

Some fields are conditionally required (e.g., taxNumber is required only for corporate accounts).

What is the difference between PUT and POST?

  • POST: Creates a new record.
  • PUT: Updates an existing record. Using the wrong method may cause a 400 or 409 error.

What should I do if the server returns “500 Internal Server Error”?

This error occurs due to unexpected system conditions. The traceId in the response should be reported to the technical support team

{
  "traceId": "5c1d7f2a-ec81-4e1b-b72c-11e2f8cb234f"
}

Listing, Paging & Filtering​

Can I get all records at once?

No, the system enforces paging.

A maximum pageSize=100 can be sent per request.

Where can I find the total number of records?

All listing responses include the totalCount field. This indicates the total number of records.

What happens if I don’t provide a filter parameter?

All records are returned.

However, paging is applied for performance (e.g., first 10 records).

Are filters case-sensitive?

Generally case-insensitive (e.g., "tr", "TR" are treated the same).

However, some fields like code require exact match.

Payment, Card, and Account Operations​

Why are card numbers masked?

For security reasons.

Only the first 6 and last 4 digits are shown:

858563******9966

The full number is never returned by any API call.

What does “isVisibleOnPayment” do?

This field determines whether accounts are listed on payment screens.

true → visible on payment screens, false → used only for background processes.

If an account “code” changes, will old payments be affected?

No.

Old transactions are preserved using the updateCode reference, so historical data is not broken.

Why are saved cards not visible?

  • The token may belong to a different tenant.
  • If there are no saved cards for the member, a 404 is returned.
  • Deleted cards are never listed.

Developer Tips & Best Practices

How can I manage errors most effectively?

Check the isSuccess field in each request result. Log errorCode and traceId for failed requests. This makes debugging easier.

How can I work in the test environment?

The base URL for the test environment is:

https://sandbox.catvendorapi.com/

Integration should be completed in the test environment before real operations.

How to track API version changes?

The “Version Notes (Change Log)” section lists recent changes. New versions usually come with the v2, v3 endpoint prefix.

Is there a rate limit?

If present, a 429 Too Many Requests error is returned. Wait briefly and retry or contact support.

Why is there a UTC date difference?

The API returns all dates in UTC (Coordinated Universal Time). They must be converted to local time on the client side.

When is the registration email sent to the user?

For some endpoints (sendRegisterMail: true), the registration email is automatically sent to the user. This is optional.

How to enable mobile usage?

Set canUseMobile to true to grant the user mobile access. Mobile users can only log in to supported mobile applications.

Can I send data in formats other than JSON?

No.

All requests and responses are in application/json format.

XML or form-data is not supported.

In summary

The FAQ section explains the most common developer errors, technical rules, and business rules with examples.

This section is common for all modules in the system (Vendor, Sub-Vendor, User, Account, Card, etc.).