Authentication
Use the same access token as for payments (Obtain/Refresh Access Token), issued for a service account of exactly one merchant. A missing or expired token answers 401. A token that doesn't select exactly one active merchant, or lacks the customer tag API permission, is refused with 403 before the tag API runs; these platform answers carry no code.
POST requests need Content-Type: application/json; any other content type answers 415.
How a request is checked
Every request is checked in this order; the first check that fails decides the answer, and nothing is changed:
- The access token and its merchant (see Authentication).
- The rate limit: 120 requests per 60 seconds per merchant, counted over all four endpoints, in a fixed window. Over that the API answers
429rate_limitedwith aRetry-Afterheader (seconds until the window ends, at least1). If Finrelay can't count your requests, it answers503temporarily_unavailablewithRetry-After: 5. - The tag: it must exist, be active, belong to your business account and be opened to your merchant. Otherwise
404tag_not_opened. - For adding and removing: the write switch for your merchant. If it is off,
403tag_api_writes_disabled. - The body: a JSON object with a non-empty
entriesarray, else400invalid_request; more than 1,000 entries,400batch_too_large. For the entry list,pageandsizeare checked here instead. - Each entry, which gets its own result code.
- For adding: your business account's entry limit, counted over all its tags. If the new entries would exceed it,
422limit_exceededand nothing is added.
Errors
A refused request answers with one object:
{"code":"limit_exceeded","message":"The business account's entry limit would be exceeded; nothing was added",
"status":422,"method":"POST","details":{"limit":20000000,"would_add":250,"remaining":120}}
details is present only for limit_exceeded. Codes are stable; messages may change.
Entry types
| Type | Send | Notes |
|---|---|---|
email |
{"type":"email","value":"jane@example.com"} |
Trimmed and stored in lower case; at most 254 characters and shaped like name@domain.tld. Matches the payment's customer.email, ignoring case. |
customer_reference |
{"type":"customer_reference","value":"P-104729384756"} |
Your own customer ID, the same value you send as customer_reference on payments. Trimmed, case-sensitive, 1 to 255 characters; a value that looks like a card number is refused. It matches only payments of your merchant. |
card |
{"type":"card","transaction_id":"…"} or {"type":"card","payment_method_id":"…"} |
Exactly one of the two, and no value. transaction_id is the gateway transaction id, never your order reference; payment_method_id is the ID of a saved card. Both must belong to your merchant. The card number is never sent or returned; you get the masked card back. |
How tags apply to payments
Tags are applied on a best-effort basis. If Finrelay can't check a transaction's tags in time, the transaction is processed as if the customer were in no tag: routing, whitelist and other rules that need a tag don't apply, and rules on "has none of" do. Block rules (blacklist and fraud blocks) with a tag condition still apply: while the check is unavailable, they treat their tag condition as met for every payment. Don't use a tag as your only control for players you must never accept, such as self-excluded or banned players. Keep blocking them in your own system before you send the payment. An entry you add applies from the next transaction.
Tags are checked on payments and payouts alike (authorize, purchase, payment, payout, OCT and card verification). A capture, refund or void uses the tags of the payment it acts on.
Send your customer reference
customer_reference is your own customer ID (for example your player ID), sent as a top-level string next to reference, never inside customer. It is accepted on:
/api/transactions/authorize,/api/transactions/execute,/api/transactions/paymentand/api/transactions/payout;/api/hosted-payment-pageand/api/sessions, where it is stored on the session's payment;/api/payment-links, where it is copied to the payment the link opens.
On /api/transactions/retry it is ignored: the retry keeps the reference of the payment it retries. The client-side calls of the Hosted Payment Page, Embedded Fields and the mobile SDKs never read it; set it when you create the session.
- Trimmed; an absent,
null, empty or blank value means no reference. -
At most 255 characters after trimming. A longer value is refused with
422and nothing is created. This is checked on every endpoint above,/api/transactions/retryincluded:{"errors":[{"property":"customer_reference","message":"customer_reference_too_long","params":["255"]}],"status":422,"method":"POST"} -
A value that looks like a card number (12 to 19 digits once spaces and dashes are removed, passing the card checksum) is dropped silently: the payment goes ahead without a reference, and the dashboards flag the payment as having had its reference dropped.
- It is not returned in payment API responses or webhooks; it is shown in the dashboards and the merchant-admin transaction API.
If your player IDs are numbers of 12 or more digits, about one in ten of them looks like a card number and is dropped. Send them with a non-numeric prefix, for example P-104729384756, and use the same prefix in your tag entries.
Keeping your list in sync
- Keep your own record of what you have pushed, and diff against it: send the additions and the removals since your last sync. List paging is for spot checks, not for reconciliation.
- Adding an entry that is already in the tag answers
addedand changes nothing, so a repeated add is safe. - Removing an entry that is already gone answers
entry_not_found; treat that as done. - An entry another source added (the dashboard or another merchant) looks absent to you: it isn't listed, removing it answers
entry_not_found, and adding it answersaddedwithout making it yours. To take such a player out of a tag, ask your business account admin.
List the tags opened to you
GET /api/customer-tags
The active tags opened to your merchant, oldest opening first, without paging. opened_at is when the tag was opened to you.
{"items":[{"id":"t0000000000000000001","name":"VIP","opened_at":"2026-10-19T08:00:00Z"}]}
List your entries
GET /api/customer-tags/{tag_id}/entries?page=1&size=100
page starts at 1 (default 1), size is 1 to 1000 (default 100); any other value, or one that isn't an integer, answers 400 invalid_request. A page past the end, however large its number, is empty. Newest first; only entries your merchant added through this API. Every key is present in each item: value is null for cards, and transaction_id or payment_method_id is the card ID you sent.
{"items":[{"entry_id":"e0000000000000000001","type":"card","value":null,"masked_card":"411111******1111",
"transaction_id":"tx0000000000000000001","payment_method_id":null,"added_at":"2026-10-19T08:05:00Z"}],
"page":1,"size":100,"has_more":false}
No endpoint accepts entry_id: you remove an entry by its value or card ID.
Add entries
POST /api/customer-tags/{tag_id}/entries
Content-Type: application/json
{"entries":[{"type":"email","value":"b@x.com"},
{"type":"card","transaction_id":"tx0000000000000000001"},
{"type":"card","payment_method_id":"pm000000000000000001"}]}
1 to 1,000 entries per request. The answer is 200 with one result per entry, in the order you sent them. index is the 0-based position; type, transaction_id and payment_method_id echo what you sent when they are strings; masked_card is present on an added card. Keys without a value are left out, and no entry ID is returned.
{"results":[{"index":0,"type":"email","code":"added","message":"Added"},
{"index":1,"type":"card","code":"added","message":"Added","masked_card":"411111******1111","transaction_id":"tx0000000000000000001"},
{"index":2,"type":"card","code":"card_not_yet_fingerprinted","message":"The saved card has no fingerprinted transaction yet","payment_method_id":"pm000000000000000001"}]}
Entries with a per-entry error don't stop the others. The same value twice in one request answers added both times and is stored once.
Remove entries
POST /api/customer-tags/{tag_id}/entries/remove
Content-Type: application/json
Same body and answer as adding. You can remove only entries your merchant added through this API. A card is found by the card behind the transaction_id or payment_method_id you send, so the same card added through another ID is removed too.
Result codes
Per-entry codes come in the 200 answer; the others are the code of a refused request.
| Code | HTTP | When |
|---|---|---|
added |
200 | The entry was added, or it was already in the tag. |
removed |
200 | Your entry was removed. |
entry_not_found |
200 | Nothing to remove: absent, added by someone else, or already removed (also a repeat in the same request). |
reference_not_found |
200 | The transaction or saved payment method doesn't exist for your merchant. |
no_fingerprint |
200 | The transaction has no card fingerprint, for example a wallet payment or a payment made before card fingerprints were recorded. |
card_not_yet_fingerprinted |
200 | The saved card has no fingerprinted transaction yet. |
invalid_value |
200 | Malformed email; empty, too long or card-like reference; unknown or missing type; an entry that isn't an object; a card with both or neither ID, or with a value; or card entries not enabled. |
invalid_request |
400 | The body isn't a JSON object, entries is missing, not an array or empty, or page/size is invalid. |
batch_too_large |
400 | More than 1,000 entries. |
invalid_request |
403 | The credential doesn't select exactly one merchant. Such a token is normally refused earlier with a plain 403 (see Authentication). |
tag_api_writes_disabled |
403 | Adding and removing are switched off for your merchant. |
tag_not_opened |
404 | The tag doesn't exist, was deleted, isn't a tag of your business account, or isn't opened to your merchant. |
limit_exceeded |
422 | The business account's entry limit would be exceeded; nothing was added. details has limit, would_add and remaining. |
rate_limited |
429 | Too many requests; wait Retry-After seconds. Nothing was changed. |
temporarily_unavailable |
503 | The rate limit can't be checked, or another change to the same tags (an import) is holding them for longer than 2 seconds; wait Retry-After seconds (5) and send the same request again. Nothing was changed. |