Choosing a Token Scope

Decide whether a saved card belongs to one merchant or to every merchant on your platform, and set that scope when the token is created.

Every multi-use token has a scope: merchant or platform. A merchant token works only for the merchant it was created on. A platform token works for any merchant on your platform. Preczn sets the scope once, when it creates the token, and you can't change it afterward. Choose the scope before you save a card.

For example, Hedgerow is a platform for landscaping businesses. If Hedgerow saves a homeowner's card as a merchant token on Cedar Hollow Landscaping, only Cedar Hollow can charge it. If Hedgerow saves it as a platform token, Cedar Hollow and any other landscaping business on Hedgerow can charge it.

Merchant and platform scope


Merchant tokenPlatform token
How it's createdThe first approved transaction includes ?merchantToken=trueThe first approved transaction omits merchantToken. This is the default.
Which merchants can use itOnly the merchant on that first transactionAny merchant on your platform, in the same mode (test or live)
Same card on another merchantA separate merchant token for each merchantThe same platform token
Listed by GET /v1/tokens?merchantId=...YesNo. Retrieve it without the merchantId filter.

A transaction that sends a merchant token with a different merchantId is rejected with 403 Forbidden and the message token cannot be used.

Scope applies to card and bank account tokens. Loan tokens always belong to one merchant.

How Preczn sets the scope


Preczn creates a multi-use token when a transaction that uses a single-use token, or raw payment details, is approved or pending. The single-use token is consumed at that point. The merchantToken query parameter on that transaction decides the scope:

First approved transactionResulting multi-use token
POST /v1/transactions?tokenize=truePlatform
POST /v1/transactions?tokenize=true&merchantToken=trueMerchant, locked to the transaction's merchantId

tokenize=true controls only whether the token comes back in the response. Preczn creates the token and sets its scope either way. For the request format, see Multi-Use Tokens.

A transaction that already uses a multi-use token doesn't create a new one, so it can't change the scope. Apple Pay and Google Pay payments don't create multi-use tokens.

Use cases


Cards that stay with one merchant

Use merchant tokens when each merchant owns its customers and no other merchant on your platform should be able to charge them. For example, Hedgerow might decide that each landscaping business keeps its own client list, so a card saved for a Cedar Hollow Landscaping client can never be charged by another business on Hedgerow.

Send merchantToken=true on the transaction that saves the card.

Cards shared across merchants

Use platform tokens when one customer pays more than one merchant on your platform, and you want them to enter their card once. For example, a homeowner on Hedgerow pays Cedar Hollow Landscaping for lawn care and a separate tree service for pruning. With a platform token, the homeowner saves their card once and both businesses can charge it.

Omit merchantToken. Store the token against the customer in your system, and send the merchantId of the business being paid on each transaction. The merchantId decides which account the payment settles to. The token supplies only the card.

One business with two accounts at the same provider

A business that holds two accounts at the same provider, such as two Payrix accounts or two Cardpointe accounts, needs two merchant records in Preczn. Each provider account has its own merchant ID (MID), and each Preczn merchant record holds one of them. See When a business needs two MIDs at the same provider. To charge one saved card to either account, the card's token must be a platform token.

The provider's MID and the Preczn merchantId are different identifiers. The provider assigns the MID to the account. Preczn assigns the merchantId, which starts with mid_, to the merchant record. Transactions name the merchant record by its merchantId.

In the example below, Hedgerow has decided to give Cedar Hollow Landscaping two merchant records: one for residential service plans and one for commercial contracts. Each record holds its own account at the same provider, such as two separate Payrix accounts, each with its own MID. A customer who pays both enters their card once:

  1. Capture the card. Hedgerow's checkout collects the card with PaymentElements or PaymentFields and receives a single-use token.
  2. Exchange it for a platform token. Hedgerow sends a Verify with the single-use token and ?tokenize=true to either merchant record, without merchantToken. If the verify is approved, the response returns a platform token in payment.token. An approved sale or auth works the same way when the first payment is due right away.
  3. Charge either account. Hedgerow stores the platform token against the customer. Each later transaction sends that token with the merchantId of the record that should receive the payment. A monthly lawn care charge goes to the residential record and settles to the residential Payrix account. A commercial invoice goes to the commercial record and settles to the commercial Payrix account.
{
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "type": "sale",
  "amount": 4500,
  "payment": {
    "token": "tkn_5kpqt630zh9kdrev2kxmdr66tr"
  }
}

A single-use token can't be sent to both records. The first approved transaction consumes it, so exchange it once and use the platform token from then on.

FAQ


Can I change a token's scope after it's created?

No. Preczn sets the scope on the first approved transaction, and later transactions that use the token can't change it.

A card is already saved as a merchant token. How do I use it on another merchant?

For example, Cedar Hollow Landscaping's residential record saved a client's card as a merchant token before the commercial record existed, and the commercial record now needs to charge the same card.

Collect the card again and save it as a platform token. Capture it with PaymentElements or PaymentFields, then send a Verify without merchantToken. Preczn creates a new platform token for the card. The original merchant token stays valid for its merchant.

Do I need a verify, or can a sale or auth save the card?

Any of the three works. An approved verify, sale, or auth that uses a single-use token converts it into a multi-use token, with the scope set by merchantToken on that transaction. Choose the type by what the customer is doing:

  • Verify saves the card without charging it.
  • Sale saves the card and charges it in one step.
  • Auth saves the card and places a hold that you capture later.
Does the same card always return the same token?

For platform tokens, yes. The same card number and expiration date return the same platform token for every merchant on your platform. Merchant tokens are separate for each merchant. If Cedar Hollow Landscaping's residential and commercial records each save the same card as a merchant token, the card has two different merchant tokens, one for each record.


Did this page help you?