Manage merchants

CreateCopy Anchor Link

Create from the top down: the enterprise if there is one, then the company, then its tradings.

Creating an enterprise, or a company with no enterprise, needs a key for your whole organisation. Set external_ref to your own identifier, and send an Idempotency-Key so a retry cannot create a duplicate.

POST /integration/v1/companies
Idempotency-Key: 0192f6c4-8a20-7d31-b4c5-d6e7f8a9b0c1

{"name": "Kedai Ali Sdn Bhd", "external_ref": "HQ-C-1001"}

POST /integration/v1/tradings
Idempotency-Key: 0192f6c4-8a21-7a02-9b3c-4d5e6f7a8b9c

{"name": "Kedai Ali Shah Alam", "external_ref": "HQ-T-2001", "company_external_ref": "HQ-C-1001"}

An external_ref already in use returns 409, with already_taken in invalid_params.

FindCopy Anchor Link

Find a record by your reference with the list filter:

GET /integration/v1/tradings?external_ref=HQ-T-2001

Search tradings by name with q, or list a company's tradings with company_id or company_external_ref.

UpdateCopy Anchor Link

Send only the fields that change. PATCH takes a JSON merge patch, so null clears a field. See Requests and responses.

PATCH /integration/v1/tradings/{id}

{"name": "Kedai Ali (Shah Alam)"}

An enterprise's, company's or trading's external_ref can be set once. Changing it returns 409, with immutable in invalid_params, and null returns 400. An acquirer's external_ref is different: you can change it, or send null to clear it.

Enroll a trading in a productCopy Anchor Link

A trading takes payments for a product through an acquirer once it is enrolled:

POST /integration/v1/trading-enrollments

{"trading_external_ref": "HQ-T-2001", "product_code": "…", "acquirer_external_ref": "BANK-01"}

If the product has more than one vendor, also send vendor_id. Repeating the same enrollment returns the existing one with 200. Setting up a device at the trading also enrolls it if needed. See Set up a device.

RetireCopy Anchor Link

To stop using a merchant, PATCH it to "status": "inactive". It keeps its history and stays in lists.

A delete is refused with 409 while live records depend on it, such as a company that still has tradings.

Keep your system in stepCopy Anchor Link

If your reports need merchant names and statuses, keep a copy and refresh what changed instead of reading merchants one by one. See Syncing data.