General Requirements

Everything cross-cutting that every integration must know — the core principles, the configuration and credentials LoyaltyPlant provisions, security, operating constraints, and a glossary — regardless of whether you build with the SDK or the raw API. The build guides (SDK / API) reference this page.

Read after the Overview. This is a two-party setup — you build and host the service; LoyaltyPlant provisions the credentials and configuration that make it live. You cannot self-configure these values; LoyaltyPlant sets them for you.

---

1. Core principles

These five ideas run through the whole API. Each is detailed in Payment Flows.

1. Capabilities-driven. You declare a set of capabilities at GET /v1/capabilities. LoyaltyPlant will never call an operation whose capability you didn't declare. Declare only what you have actually implemented and tested.
2. Business outcome lives in HTTP 200. A business result — approved, declined, pending — is always returned as HTTP 200 with a status field. HTTP 4xx/5xx are reserved for infrastructure errors (bad request, auth failure, your service is down). A declined card is not an HTTP error.
3. Idempotent. Every mutating call carries an Idempotency-Key. The same key must always produce the same result — LoyaltyPlant retries on transient failures and must never double-charge.
4. Synchronous when possible, asynchronous when needed. If a payment needs 3-D Secure or a redirect, you return PENDING with a redirectUrl, then report the final result with the asynchronous callback.
5. Reconcilable. If an outcome is ever ambiguous (timeout, lost callback), LoyaltyPlant can ask your PSP for the truth via POST /v1/inquire-status — or, for a card binding, POST /v1/inquire-enrollment-status.

These five apply unchanged to card enrollment: it is capability-gated (TOKENIZATION), returns its outcome in a 200 body, is idempotent, suspends on a redirect, and is reconcilable. See Card enrollment.

2. What you provide to LoyaltyPlant

You provide	Notes
Your service base URL	Public HTTPS endpoint LoyaltyPlant will call (e.g. https://payments.your-domain.example). LoyaltyPlant appends /v1/....
Supported apiVersion	The version segment of the contract you implement (currently v1).
Declared capabilities	Must match what GET /v1/capabilities returns.
Egress IPs (optional)	Source IPs your service calls LoyaltyPlant from, if you want them allow-listed.
Required settings keys	Any PSP-specific config (beyond currency) you need LoyaltyPlant to pass on each request — e.g. merchantId, processing IDs.
Operational contacts	On-call / incident contacts and your maintenance windows.

3. What LoyaltyPlant provisions for you

LoyaltyPlant configures the following and shares the secrets with you over a secure channel:

LoyaltyPlant provides	What it's for
integrationId	Your integration's identifier; appears in the result-callback URL /gate/integration/{integrationId}/result.
Outbound token	Bearer token LoyaltyPlant sends you on every request. You validate it (see §4).
Inbound token	Bearer token you send LoyaltyPlant on the result and enrollment callbacks.
settings map	The per-client/outlet key/values (e.g. merchantId) provisioned by LoyaltyPlant at onboarding and delivered on each operation (currency always present, plus any keys you requested). You receive it; you don't define it.
Callback host	The payments-service host you POST results to.
Limits	Rate, concurrency, and timeout limits LoyaltyPlant enforces in front of your service (see §7).

Internally, LoyaltyPlant stores these in its own configuration system — that's not your concern. From your side, they simply arrive during onboarding; treat the tokens as secrets.

4. Token directionality (read this twice)

There are two tokens and they travel in opposite directions. Mixing them up is the most common integration mistake.

	Outbound token	Inbound token
Direction	LoyaltyPlant → you	You → LoyaltyPlant
Where it appears	Authorization on incoming /v1/* requests	Authorization on POST /gate/integration/{id}/result and .../enrollment-result
Your job	Validate it (constant-time); reject others with 401	Send it on the callback
If wrong	You accept unauthenticated traffic (security hole)	LoyaltyPlant returns 401 and the payment never resumes

Store both as secrets (vault / secret manager), never in source control or logs. Rotate via LoyaltyPlant; support overlapping old+new during rotation so there's no downtime.

5. Security

• TLS with a valid certificate on your service; reject plaintext.
• Validate the outbound token on every /v1/* request, using a constant-time comparison; reject mismatches with 401 (see §4).
• Protect the inbound token (your callback credential) like any secret; never log it.
• Verify PSP webhook signatures before acting on a PSP notification — never trust an unverified payload (it drives the result callback).
• Durable idempotency store, keyed per integration (the Idempotency-Key contract is in the spec).
• Consider IP allow-listing LoyaltyPlant's egress ranges (provided during onboarding).
• Never log full PANs or tokens; keep reason strings free of sensitive data.

6. Environments

LoyaltyPlant provisions you separately in a sandbox/staging environment and in production. Each environment has its own integrationId, tokens, callback host, and limits — never reuse staging credentials in production. Point your service at your PSP's sandbox in staging and at the live PSP in production. Complete certification in staging first.

7. Operational limits

LoyaltyPlant protects both sides with a rate limiter, a concurrency bulkhead, a circuit breaker, and request timeouts in front of your service. Typical default limits (LoyaltyPlant sets the actual values per integration during onboarding):

Limit	Default	What it means for you
Request timeout	10 s	Respond well within this; slow responses are abandoned and treated as retriable.
Connect timeout	2 s	Your TLS/connection setup must be prompt.
Rate limit	100 / s	Sustained request rate ceiling.
Max concurrency	25	Concurrent in-flight requests LoyaltyPlant will run against you.
Circuit-breaker threshold	5	Repeated failures trip a breaker that briefly stops traffic to protect you.

Design for these: keep synchronous endpoints fast (push slow work to the async callback), make operations idempotent, and keep health honest so the breaker and routing work for you.

8. Glossary

Term	Meaning
Integration	The standalone REST service you host that implements this API.
integrationId	The identifier LoyaltyPlant assigns to your integration; appears in the result-callback URL (see §3).
PSP	Payment service provider — the gateway/acquirer behind your integration (your existing system).
Capability	A feature flag you declare (CAPTURE, SALE, DIRECT_REFUND, REDIRECT_FLOW, DIRECT_WEBHOOK, STATUS_POLLING, TOKENIZATION, APPLE_PAY, GOOGLE_PAY). Gates which operations LP calls.
Authorize	Reserve/hold funds without capturing them (first phase of a two-phase payment).
Capture	Settle funds previously held by an authorize.
Sale	Authorize and capture in a single step (single-phase payment).
Reverse	Void/cancel an authorization before capture (releases the hold).
Refund	Return funds after capture.
transactionReference	Your identifier for a payment at the PSP. You return it; LP stores it and uses it for follow-up operations and to match async callbacks.
outbound token	Bearer token LP sends you on every request; you validate it (see §4).
inbound token	Bearer token you send LP on the result and enrollment callbacks (see §4).
Idempotency-Key	UUID on every mutating request; repeats must return the same result.
Redirect flow	A payment that needs the customer to complete authentication on another page (e.g. 3-D Secure) before it resolves.
Result callback	The POST /gate/integration/{id}/result request you send LP after an async payment resolves.
Status inquiry	POST /v1/inquire-status — LP asks you for the PSP's current status of a payment (reconciliation).
Enrollment	Binding a customer's card so it can be charged later without re-entering details. Started by POST /v1/enroll; gated by TOKENIZATION.
Enrollment callback	The POST /gate/integration/{id}/enrollment-result request you send LP to deliver a card token. The only channel that delivers one.
enrollmentId	LP's identifier for an enrollment, sent in /v1/enroll and echoed back in the callback. The one key both sides always share.
paymentInstrument	Optional field in authorize/sale naming what to charge: a CARD_TOKEN, or an APPLE_PAY/GOOGLE_PAY walletPayload.
Card token	The reference to a bound card that you issue at enrollment and LP sends back as paymentInstrument.token. A secret — never log it.
SUCCESS / PENDING / DECLINED / RETRIABLE / UNKNOWN	The five operation outcomes carried in the status field. See Payment Flows.

---

Next: Payment Flows →