Fees & Delivery

Before issuing a physical card, partners typically want to surface the cost of the card itself and the cost of getting it into the customer's hand. The Fees & Delivery endpoints let you look those numbers up without triggering an actual issuance — they're pure price-quote calls.

The data of fees

The fee endpoints return a single JSON object with the resolved price (or price components). The inputs are validated against checkFeePayloadSchema (in validations/partnerFeeValidation.ts), which requires:

Body field	Required	Allowed values
CustomerType	yes	Consumer Debit, Business Debit, Consumer Prepaid, Business Prepaid
ProductType	yes	R001, R002, R003, R004, R005, R006 (one of the configured CIP products)
cardKey	optional	At least one of cardKey, clientId, or iban must be present so the downstream fee lookup has a stable identifier.
clientId	optional	—
iban	optional	—

The OperationType ('Card Issuing Fee' / 'Card Delivery Fee') is not part of the request body — it's fixed per endpoint on the server side so partners cannot probe other operation types.

Delivery methods

GET /fees/delivery-methods?country=XX returns the list of available physical-card delivery methods for an ISO 3166-1 alpha-2 country code. Each method record is sourced from the PocztaPost or DHLDeliveryMethods Mongo collection and carries:

Field	Meaning
methodId	Stable identifier (e.g. STANDARD, EXPRESS, PICKUP).
standardWeight	The card weight tier this method applies to (grams).
deliveryTime	Human-readable delivery estimate (e.g. "3-5 days").
price	Base courier price for this method.
isActive	Whether this method is currently available in the country.
zoneId	Internal zone identifier the method belongs to.

The endpoint normalises PocztaPost and DHL records into a single shape so the partner UI can render them uniformly.

When to call these endpoints

The typical issuance flow looks like:

1. List the available delivery methods for the customer's country — GET /fees/delivery-methods?country=....
2. Compute the issuing fee for the chosen product/country/customer type — POST /fees/issuing-fee.
3. Compute the delivery fee for the chosen product/country/method — POST /fees/delivery-fee.
4. Display both to the customer for confirmation, then proceed to issue the card.

Currency & rounding

Fee amounts are returned in the partner's settlement currency, already rounded to the smallest currency unit. Display them verbatim to the customer.

What you can do

• Quote a card price before issuing — GET /fees/delivery-methods, POST /fees/issuing-fee, POST /fees/delivery-fee.
• Combine with the card lifecycle — the same cardKey returned by POST /cards/physical can be reused as the cardKey body field on the fee endpoints to look up the exact price for that card.
• Pre-check before commit — the fee endpoints never create or modify state. They are safe to call from your pricing UI.

Validation

The fee-check endpoints validate the request body with checkFeePayloadSchema (see validations/partnerFeeValidation.ts). Validation is performed with abortEarly: false, so all errors come back in a single response.

For the exact endpoint shapes, parameters, and the Try it widget, see the List of endpoints → page.