Skip to content

Operate · Customer Tags API

Keep your customers in the tags your routing rules use

A customer tag is a named list (for example VIP) of emails, cards and your own customer references. Your business account admin creates the tag in the dashboard and opens it to your merchant; you then add and remove your own entries with /api/customer-tags.

Opened tags only. The API sees only tags your business account admin has opened to your merchant. Entries added in the dashboard or by another merchant are never listed or removed through it.

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:

  1. The access token and its merchant (see Authentication).
  2. The rate limit: 120 requests per 60 seconds per merchant, counted over all four endpoints, in a fixed window. Over that the API answers 429 rate_limited with a Retry-After header (seconds until the window ends, at least 1). If Finrelay can't count your requests, it answers 503 temporarily_unavailable with Retry-After: 5.
  3. The tag: it must exist, be active, belong to your business account and be opened to your merchant. Otherwise 404 tag_not_opened.
  4. For adding and removing: the write switch for your merchant. If it is off, 403 tag_api_writes_disabled.
  5. The body: a JSON object with a non-empty entries array, else 400 invalid_request; more than 1,000 entries, 400 batch_too_large. For the entry list, page and size are checked here instead.
  6. Each entry, which gets its own result code.
  7. For adding: your business account's entry limit, counted over all its tags. If the new entries would exceed it, 422 limit_exceeded and 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/payment and /api/transactions/payout;
  • /api/hosted-payment-page and /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 422 and nothing is created. This is checked on every endpoint above, /api/transactions/retry included:

    {"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 added and 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 answers added without 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.