Checked-in OpenAPI 3.1 contract

API reference

Read the EuniPay server API contract, request fields, response schemas, and examples. This reference never sends a request or accepts an API key.

Authentication

Verify an environment-scoped EuniPay server API key.

get/v1/auth-check

apiKeyAuthenticationCheck

Verify a server API key without returning application data

Bearer API keyServer to server

Responses

API key authenticated

Integration

Read the non-secret merchant integration readiness projection.

get/v1/integration-status

integrationStatus

Read non-secret merchant integration readiness

Bearer API keyServer to server

Responses

Scoped seller, currency, Receipt-origin, and readiness projection

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

environmentstringrequired

Allowed: test · live

merchant_idstringrequired

integration_idstringrequired

sellerobjectrequired

Additional properties: not allowed

configuredbooleanrequired
countrystringrequired
versionintegerrequired: Format: int64
Minimum: 0

currencyobjectrequired

Additional properties: not allowed

configuredbooleanrequired
base_currencystringrequired
default_display_currencystringrequired
payment_currenciesarrayrequired: Items: string
Array item schema
Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
config_versionintegerrequired: Format: int64
Minimum: 0

checkout_sdk_urlstringrequired

Format: uri

receipt_download_originstringrequired

Format: uri

readybooleanrequired

Payment Context

Resolve the currency and version context required before a strict price is displayed.

post/v1/payment-contexts/resolve

resolvePaymentContext

Resolve the forced payment currency, display metadata, and informational VAT context

Resolves country in permanent-lock, supplied-IP, then merchant-default order. An unlocked Buyer Profile does not select the country. IP data is not inspected when a valid permanent lock exists. When IP resolution is needed, malformed syntax is rejected while an unknown or temporarily unavailable lookup selects the merchant default. An explicit empty buyer_ip also selects the default. The request never creates a Buyer or formal tax evidence, and buyer_ip is never returned. VAT fields are estimated display information only; create a fresh Tax Quote before a payment is created or confirmed.

Bearer API keyServer to server

Request body

application/json · Required

{
  "external_customer_id": "customer_123",
  "buyer_ip": "203.0.113.10",
  "location_fixture": {
    "country": "DE"
  }
}

Additional properties: not allowed

external_customer_idstring

Merchant-owned identifier. Omit for anonymous display.

Minimum length: 1
Maximum length: 128

buyer_ipstringrequired

Explicit empty string permits merchant-default resolution; a nonempty value must be a plain IPv4 or IPv6 address.

Maximum length: 64

location_fixtureobject

Additional properties: not allowed

countrystringrequired: Required uppercase two-letter Test-only location country. Live requests are rejected.
Pattern: ^[A-Z]{2}$

Responses

Resolved currency context with only the applicable rate and configuration metadata

application/json

{
  "data": {
    "country": "DE",
    "country_supported": true,
    "source": "ip_country",
    "currency": "EUR",
    "symbol": "€",
    "symbol_position": "before",
    "display_precision": 2,
    "minor_exponent": 2,
    "base_currency": "SEK",
    "base_to_payment_rate": "0.087500000000",
    "tax_semantics": "inclusive",
    "vat_mode": "oss_vat",
    "vat_rate_bps": 1900,
    "estimated": true,
    "rate_version": "rate_test_20260801",
    "vat_rate_version_id": "vat_DE_20260801",
    "config_version": 3,
    "buyer_profile_version": null,
    "resolved_at": "2026-08-01T12:00:00Z"
  }
}

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed
One of: 2 schemas

countrystring: Pattern: ^[A-Z]{2}$
country_supportedbooleanrequired
sourcestringrequired: Allowed: locked_country · ip_country · default
currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
symbolstringrequired: Effective merchant currency symbol for non-transaction presentation.
Minimum length: 1
Maximum length: 8
symbol_positionstringrequired: Effective merchant placement of the symbol relative to an amount.
Allowed: before · after
display_precisionintegerrequired: Merchant-configured non-transaction presentation precision; authoritative amounts remain integer minor units.
Minimum: 0
Maximum: 6
minor_exponentintegerrequired: Immutable ISO financial precision used by authoritative integer minor-unit amounts.
Minimum: 0
Maximum: 6
base_currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
base_to_payment_ratestringrequired: Pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,12})?$
tax_semanticsstringrequired: The effective environment default used to interpret an omitted tax_semantics request field; tax semantics are separate from tax mode.
Allowed: inclusive · exclusive
vat_modestringrequired: Informational VAT mode; it is not VIES authorization or payment evidence.
Allowed: domestic_vat · oss_vat · vat_validation_required
vat_rate_bpsintegerrequired: Minimum: 0
Maximum: 5000
estimatedbooleanrequired
rate_versionstringrequired: Empty only when base and payment currency match and the identity rate 1 applies.
vat_rate_version_idstringrequired: Immutable version identifier of the informational VAT rate.
config_versionintegerrequired: Minimum: 1
buyer_profile_versioninteger | nullrequired: Minimum: 1
resolved_atstringrequired: Format: date-time

One-of schema 1

vat_modeunknownrequired: Constant: vat_validation_required
vat_rate_bpsunknownrequired: Constant: 0
vat_rate_version_idunknownrequired: Constant:

One-of schema 2

vat_modeunknownrequired: Allowed: domestic_vat · oss_vat
vat_rate_bpsunknownrequired: Minimum: 1
Maximum: 5000
vat_rate_version_idunknownrequired: Minimum length: 1

Tax Preview

Calculate a non-binding VAT estimate without creating a confirmable snapshot.

post/v1/tax-previews

createTaxPreview

Calculate a non-binding estimated VAT breakdown

Reuses Payment Context country and currency priority without persisting location evidence, allocating an ID, or producing a confirmable token. An authoritative cross-border-business Preview with authoritative Buyer profile evidence performs a fresh VIES check and returns reverse_charge only when it succeeds. Without authoritative Buyer evidence, the Preview remains non-binding in vat_validation_required mode. Unknown or unsupported buyer countries use Swedish seller VAT and are distinguished by vat_country.

Bearer API keyServer to server

Request body

application/json · Required

{
  "buyer_ip": "203.0.113.10",
  "payment_currency": "EUR",
  "amount": 10000,
  "tax_semantics": "exclusive",
  "location_fixture": {
    "country": "DE"
  }
}

Additional properties: not allowed

external_customer_idstring

Merchant-owned identifier. Omit for anonymous preview.

Minimum length: 1
Maximum length: 128

buyer_ipstringrequired

Maximum length: 64

location_fixtureobject

Additional properties: not allowed

countrystringrequired: Required uppercase two-letter Test-only location country. Live requests are rejected.
Pattern: ^[A-Z]{2}$

payment_currencystringrequired

Must equal the currency forced by the freshly resolved Payment Context.

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

amountintegerrequired

Payment-currency amount in integer minor units, interpreted using tax_semantics.

Format: int64
Minimum: 0

tax_semanticsstring

Omit to use the selected Test or Live environment default. Inclusive treats amount as the final VAT-inclusive total; exclusive treats amount as the VAT-exclusive net amount.

Allowed: inclusive · exclusive

Responses

Non-binding estimated tax and dual-currency amount breakdown

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Non-binding payment output. An authoritative cross-border-business Preview with authoritative Buyer profile evidence performs fresh VIES and returns reverse_charge only when valid; without authoritative Buyer evidence it remains vat_validation_required. It has no ID, Quote ID, or confirmation token.

Additional properties: not allowed
One of: 2 schemas

estimatedbooleanrequired

Constant: true

countrystringrequired

Resolved buyer country; empty when no supported or known country resolved.

Pattern: ^$|^[A-Z]{2}$

vat_countrystringrequired

Country whose versioned VAT rate is used, including Swedish seller fallback; empty for zero-VAT reverse-charge or pending validation.

Pattern: ^$|^[A-Z]{2}$

country_supportedbooleanrequired

sourcestringrequired

Allowed: locked_country · billing_profile · ip_country · default

modestringrequired

vat_validation_required is non-binding pending validation and is never accepted by Quote confirmation. reverse_charge carries validated zero-VAT evidence.

Allowed: domestic_vat · oss_vat · reverse_charge · vat_validation_required

tax_semanticsstringrequired

The effective tax semantic used for this calculation; tax semantics are separate from tax mode.

Allowed: inclusive · exclusive

vat_rate_bpsintegerrequired

Minimum: 0
Maximum: 5000

price_multiplierstringrequired

Pattern: ^[1-9][0-9]*\.[0-9]{4}$

vat_rate_version_idstringrequired

Empty for zero-VAT reverse-charge or pending validation because no VAT rate version is applied.

Minimum length: 0

vat_rate_effective_atstringrequired

The zero timestamp for zero-VAT reverse-charge or pending validation because no VAT rate version is applied.

Format: date-time

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

businessobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

platform_feeobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

percentage_bpsintegerrequired

Format: int64
Minimum: 0
Maximum: 10000

fixed_minorintegerrequired

Format: int64
Minimum: 0

base_to_payment_ratestringrequired

commercial_rate_idstringrequired

Empty only for the identity rate when base and payment currencies match.

config_versionintegerrequired

Minimum: 1

buyer_profile_versioninteger | nullrequired

Minimum: 1

estimated_atstringrequired

Format: date-time

One-of schema 1

modeunknownrequired: Allowed: reverse_charge · vat_validation_required
vat_rate_bpsunknownrequired: Constant: 0
vat_countryunknownrequired: Constant:
vat_rate_version_idunknownrequired: Constant:
vat_rate_effective_atunknownrequired: Constant: 0001-01-01T00:00:00Z
price_multiplierunknownrequired: Constant: 1.0000

One-of schema 2

modeunknownrequired: Allowed: domestic_vat · oss_vat
vat_rate_bpsunknownrequired: Minimum: 1
vat_countryunknownrequired: Pattern: ^[A-Z]{2}$
vat_rate_version_idunknownrequired: Minimum length: 1
vat_rate_effective_atunknownrequired

Tax Quotes

Create and read immutable tax snapshots. Eligible cross-border business Quotes include EuniPay's internal VIES decision evidence; VIES is not a separate public operation.

post/v1/tax-quotes

createTaxQuote

Create a time-bounded immutable Tax Quote

Re-resolves the Buyer, location, Payment Context, commercial rate, VAT rate, and when required repeats a fresh VIES check; the Quote remains authoritative. The returned payment amount and expiration must be copied unchanged into one provider-side payment resource. Completed requests are replayed by Idempotency-Key before external dependencies are called. Responses expose only safe Quote binding identities and ip_country/country_source from location evidence; they never expose buyer IP, seller, or VIES snapshots.

Bearer API keyIdempotency-Key requiredServer to server

Parameters

Name	Location	Requirement	Schema	Description
`Idempotency-Key`	header	Required	Type: string Minimum length: 1 Maximum length: 255	One nonempty request key, unique within merchant, environment, and operation. Multiple or comma-joined values are rejected.

Request body

application/json · Required

{
  "external_payment_attempt_id": "attempt_123",
  "external_customer_id": "customer_123",
  "buyer_profile_version": 1,
  "context_country": "DE",
  "context_currency": "EUR",
  "config_version": 3,
  "rate_version": "rate_test_20260801",
  "payment_currency": "EUR",
  "amount": 12000,
  "tax_semantics": "inclusive",
  "description": "Usage credits",
  "buyer_ip": "203.0.113.10",
  "location_fixture": {
    "country": "DE"
  },
  "vies_fixture": {
    "status": "valid"
  }
}

Additional properties: not allowed

external_payment_attempt_idstringrequired

Minimum length: 1
Maximum length: 128

external_customer_idstringrequired

Minimum length: 1
Maximum length: 128

buyer_profile_versionintegerrequired

Minimum: 1

context_countrystringrequired

Pattern: ^[A-Z]{2}$

context_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

config_versionintegerrequired

Minimum: 1

rate_versionstringrequired

Empty only when base and payment currency match.

Maximum length: 48

payment_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

amountintegerrequired

Payment-currency amount in integer minor units, interpreted using tax_semantics.

Format: int64
Minimum: 1

tax_semanticsstring

Omit to use the selected Test or Live environment default. Inclusive treats amount as the final VAT-inclusive total; exclusive treats amount as the VAT-exclusive net amount.

Allowed: inclusive · exclusive

descriptionstringrequired

Minimum length: 1
Maximum length: 500

buyer_ipstringrequired

Current raw IPv4 or IPv6 evidence. It is encrypted in the snapshot and never returned.

Minimum length: 1
Maximum length: 64

location_fixtureobject

Additional properties: not allowed

countrystringrequired: Required uppercase two-letter Test-only location country. Live requests are rejected.
Pattern: ^[A-Z]{2}$

vies_fixtureobject

Test-only. Accepted only for a cross-border business Quote that actually performs VIES validation.

Additional properties: not allowed

statusstringrequired: Allowed: valid · invalid · unavailable · error

Responses

Immutable Tax Quote created or replayed

application/json

{
  "data": {
    "tax_quote_id": "tq_test_01J4EXAMPLE",
    "external_payment_attempt_id": "attempt_123",
    "external_customer_id": "customer_123",
    "buyer_profile_version": 1,
    "context_country": "DE",
    "context_currency": "EUR",
    "config_version": 1,
    "status": "valid",
    "created_at": "2026-08-01T12:00:00Z",
    "payment_create_by": "2026-08-01T12:05:00Z",
    "expires_at": "2026-08-01T12:35:00Z",
    "tax_mode": "reverse_charge",
    "tax_semantics": "inclusive",
    "rate_bps": 0,
    "payment": {
      "currency": "EUR",
      "gross_amount": 12000,
      "net_amount": 12000,
      "vat_amount": 0
    },
    "base": {
      "currency": "SEK",
      "gross_amount": 137143,
      "net_amount": 137143,
      "vat_amount": 0
    },
    "base_currency": "SEK",
    "base_to_payment_rate": "0.087500000000",
    "rate_version": "rate_test_20260801",
    "ip_country": "DE",
    "country_source": "test_fixture"
  }
}

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

tax_quote_idstringrequired

external_payment_attempt_idstringrequired

Minimum length: 1
Maximum length: 128

external_customer_idstringrequired

Minimum length: 1
Maximum length: 128

buyer_profile_versionintegerrequired

Format: int64
Minimum: 1

context_countrystringrequired

Pattern: ^[A-Z]{2}$

context_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

config_versionintegerrequired

Format: int64
Minimum: 1

statusstringrequired

Allowed: valid · void · expired · confirmed

created_atstringrequired

Format: date-time

payment_create_bystringrequired

The provider-side payment resource must be created no later than this time.

Format: date-time

expires_atstringrequired

Apply this expiration to the provider-side payment resource where supported.

Format: date-time

tax_modestringrequired

Allowed: domestic_vat · oss_vat · reverse_charge

tax_semanticsstringrequired

The effective tax semantic locked by this Quote; tax semantics are separate from tax mode.

Allowed: inclusive · exclusive

rate_bpsintegerrequired

Minimum: 0
Maximum: 5000

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

businessobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

platform_feeobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

percentage_bpsintegerrequired

Format: int64
Minimum: 0
Maximum: 10000

fixed_minorintegerrequired

Format: int64
Minimum: 0

base_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

base_to_payment_ratestringrequired

rate_versionstringrequired

Empty only for same-currency identity conversion.

ip_countrystringrequired

Country code derived from the source IP evidence retained for this Quote. Empty only on replay of a response persisted before country evidence was added.

Pattern: ^$|^[A-Z]{2}$

country_sourcestringrequired

Safe source label for ip_country; empty only on a historical replay, and no raw or encrypted IP data is returned.

get/v1/tax-quotes/{tax_quote_id}

getTaxQuote

Get an immutable Tax Quote from its stored snapshot

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`tax_quote_id`	path	Required	Type: string Minimum length: 1 Maximum length: 48	—

Responses

Stored Tax Quote; no tax or currency values are recalculated

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

tax_quote_idstringrequired

external_payment_attempt_idstringrequired

Minimum length: 1
Maximum length: 128

external_customer_idstringrequired

Minimum length: 1
Maximum length: 128

buyer_profile_versionintegerrequired

Format: int64
Minimum: 1

context_countrystringrequired

Pattern: ^[A-Z]{2}$

context_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

config_versionintegerrequired

Format: int64
Minimum: 1

statusstringrequired

Allowed: valid · void · expired · confirmed

created_atstringrequired

Format: date-time

payment_create_bystringrequired

The provider-side payment resource must be created no later than this time.

Format: date-time

expires_atstringrequired

Apply this expiration to the provider-side payment resource where supported.

Format: date-time

tax_modestringrequired

Allowed: domestic_vat · oss_vat · reverse_charge

tax_semanticsstringrequired

The effective tax semantic locked by this Quote; tax semantics are separate from tax mode.

Allowed: inclusive · exclusive

rate_bpsintegerrequired

Minimum: 0
Maximum: 5000

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

businessobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

platform_feeobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

percentage_bpsintegerrequired

Format: int64
Minimum: 0
Maximum: 10000

fixed_minorintegerrequired

Format: int64
Minimum: 0

base_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

base_to_payment_ratestringrequired

rate_versionstringrequired

Empty only for same-currency identity conversion.

ip_countrystringrequired

Country code derived from the source IP evidence retained for this Quote. Empty only on replay of a response persisted before country evidence was added.

Pattern: ^$|^[A-Z]{2}$

country_sourcestringrequired

Safe source label for ip_country; empty only on a historical replay, and no raw or encrypted IP data is returned.

post/v1/tax-quotes/{tax_quote_id}/void

voidTaxQuote

Mark a valid Tax Quote void after the merchant expires its payment resource

This operation does not contact or expire the payment provider. It accepts no request body. Repeating it for an already void Quote returns the stored void state. Confirmed, expired, or already-due Quotes cannot be voided.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`tax_quote_id`	path	Required	Type: string Minimum length: 1 Maximum length: 48	—

Responses

Stored void Tax Quote

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

tax_quote_idstringrequired

external_payment_attempt_idstringrequired

Minimum length: 1
Maximum length: 128

external_customer_idstringrequired

Minimum length: 1
Maximum length: 128

buyer_profile_versionintegerrequired

Format: int64
Minimum: 1

context_countrystringrequired

Pattern: ^[A-Z]{2}$

context_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

config_versionintegerrequired

Format: int64
Minimum: 1

statusstringrequired

Allowed: valid · void · expired · confirmed

created_atstringrequired

Format: date-time

payment_create_bystringrequired

The provider-side payment resource must be created no later than this time.

Format: date-time

expires_atstringrequired

Apply this expiration to the provider-side payment resource where supported.

Format: date-time

tax_modestringrequired

Allowed: domestic_vat · oss_vat · reverse_charge

tax_semanticsstringrequired

The effective tax semantic locked by this Quote; tax semantics are separate from tax mode.

Allowed: inclusive · exclusive

rate_bpsintegerrequired

Minimum: 0
Maximum: 5000

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

businessobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

platform_feeobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

percentage_bpsintegerrequired

Format: int64
Minimum: 0
Maximum: 10000

fixed_minorintegerrequired

Format: int64
Minimum: 0

base_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

base_to_payment_ratestringrequired

rate_versionstringrequired

Empty only for same-currency identity conversion.

ip_countrystringrequired

Country code derived from the source IP evidence retained for this Quote. Empty only on replay of a response persisted before country evidence was added.

Pattern: ^$|^[A-Z]{2}$

country_sourcestringrequired

Safe source label for ip_country; empty only on a historical replay, and no raw or encrypted IP data is returned.

Checkouts

Create EuniPay-owned Stripe Embedded Checkouts and read their safe merchant fulfilment state.

post/v1/checkouts

createCheckout

Create or replay one EuniPay-owned Stripe Embedded Checkout

Resolves the current Buyer, Billing Profile and IP evidence, Payment Context, commercial rate, VAT rate, and when required VIES before creating the authoritative Tax Quote and Stripe resources. Stripe is charged the Quote's frozen gross amount. The request accepts business inputs only; it does not accept a Tax Quote ID or a context/version snapshot. A simultaneous replay while creation is claimed returns 409 checkout_in_progress and can be retried. Completed replays return the same Checkout with a newly rotated browser token and immutable settlement, and never expose the Stripe Client Secret.

Bearer API keyIdempotency-Key requiredServer to server

Parameters

Name	Location	Requirement	Schema	Description
`Idempotency-Key`	header	Required	Type: string Minimum length: 1 Maximum length: 255	One nonempty request key, unique within merchant, environment, and operation. Multiple or comma-joined values are rejected.

Request body

application/json · Required

{
  "external_order_id": "topup_123",
  "external_customer_id": "customer_123",
  "payment_currency": "SEK",
  "amount": 10000,
  "tax_semantics": "inclusive",
  "description": "Usage credits",
  "buyer_ip": "203.0.113.10",
  "browser_origin": "https://merchant.example",
  "return_url": "https://merchant.example/console/billing"
}

Additional properties: not allowed

external_order_idstringrequired

Minimum length: 1
Maximum length: 128

external_customer_idstringrequired

Minimum length: 1
Maximum length: 128

payment_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

amountintegerrequired

Payment-currency amount in minor units. Inclusive means the final VAT-inclusive total; exclusive means the VAT-exclusive net amount. Stripe charges the authoritative Tax Quote gross amount.

Format: int64
Minimum: 1

tax_semanticsstringrequired

Allowed: inclusive · exclusive

descriptionstringrequired

Minimum length: 1
Maximum length: 500

buyer_ipstringrequired

Current IPv4 or IPv6 evidence; encrypted in the Quote snapshot and never returned.

Minimum length: 1
Maximum length: 64

location_fixtureobject

Additional properties: not allowed

countrystringrequired: Required uppercase two-letter Test-only location country. Live requests are rejected.
Pattern: ^[A-Z]{2}$

vies_fixtureobject

Test-only. Accepted only for a cross-border business Quote that actually performs VIES validation.

Additional properties: not allowed

statusstringrequired: Allowed: valid · invalid · unavailable · error

browser_originstringrequired

Exact origin bound to the one-time browser token. Live requires HTTPS.

Format: uri

return_urlstring

Optional post-payment browser destination. It must use the same origin as browser_origin; omitted requests fall back to browser_origin.

Format: uri

Responses

Checkout created or safely replayed

application/json

{
  "data": {
    "checkout_id": "eco_01J4EXAMPLE",
    "checkout_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "status": "open",
    "expires_at": "2026-08-17T12:30:00Z",
    "settlement": {
      "tax_quote_id": "tq_01J4EXAMPLE",
      "quote_created_at": "2026-08-17T12:00:00Z",
      "payment_create_by": "2026-08-17T12:10:00Z",
      "quote_expires_at": "2026-08-17T12:30:00Z",
      "buyer_profile_version": 1,
      "context_country": "SE",
      "context_currency": "SEK",
      "config_version": 3,
      "rate_version": "fx_20260817",
      "tax_semantics": "inclusive",
      "tax_mode": "domestic_vat",
      "rate_bps": 2500,
      "payment": {
        "currency": "SEK",
        "gross_amount": 10000,
        "net_amount": 8000,
        "vat_amount": 2000
      },
      "base": {
        "currency": "EUR",
        "gross_amount": 870,
        "net_amount": 696,
        "vat_amount": 174
      },
      "settlement_base_net_amount": "6.956521739130434782608696",
      "ip_country": "SE",
      "country_source": "geoip"
    }
  }
}

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

checkout_idstringrequired

Minimum length: 1
Maximum length: 48

checkout_tokenstringrequired

Returned once per create response; only its hash is retained.

Minimum length: 43
Maximum length: 43

statusstringrequired

Allowed: creating · open · processing · paid · failed · expired

expires_atstringrequired

Format: date-time

settlementobjectrequired

Additional properties: not allowed

tax_quote_idstringrequired

Minimum length: 1
Maximum length: 48

quote_created_atstringrequired

Format: date-time

payment_create_bystringrequired

Format: date-time

quote_expires_atstringrequired

Format: date-time

buyer_profile_versionintegerrequired

Format: int64
Minimum: 1

context_countrystringrequired

Pattern: ^[A-Z]{2}$

context_currencystringrequired

Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY

config_versionintegerrequired

Format: int64
Minimum: 1

rate_versionstringrequired

Maximum length: 48

tax_semanticsstringrequired

Allowed: inclusive · exclusive

tax_modestringrequired

Allowed: domestic_vat · oss_vat · reverse_charge

rate_bpsintegerrequired

Format: int64
Minimum: 0
Maximum: 5000

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

businessobjectrequired

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

platform_feeobject

Additional properties: not allowed

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

settlement_base_net_amountstring

Minimum length: 1

percentage_bpsintegerrequired

Format: int64
Minimum: 0
Maximum: 10000

fixed_minorintegerrequired

Format: int64
Minimum: 0

settlement_base_net_amountstringrequired

Minimum length: 1

ip_countrystringrequired

Pattern: ^[A-Z]{2}$

country_sourcestringrequired

Minimum length: 1

get/v1/checkouts/{checkout_id}

getCheckout

Read safe EuniPay Checkout state for merchant fulfilment

Paid responses add only immutable Quote, Transaction, Receipt, money, tax, Buyer-country, and IP-country/source fields. Raw IP, VAT number, VIES evidence, Stripe credentials, Client Secret, and provider event bodies are never returned.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`checkout_id`	path	Required	Type: string Minimum length: 1 Maximum length: 48	—

Responses

Scoped Checkout state

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

checkout_idstringrequired

Minimum length: 1
Maximum length: 48

statusstringrequired

Allowed: creating · open · processing · paid · failed · expired

paidobject

Additional properties: not allowed

tax_quote_idstringrequired

Minimum length: 1
Maximum length: 48

transaction_idstringrequired

Minimum length: 1
Maximum length: 48

receipt_idstringrequired

Minimum length: 1
Maximum length: 48

receipt_numberstringrequired

Minimum length: 1
Maximum length: 32

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

tax_modestringrequired

Allowed: domestic_vat · oss_vat · reverse_charge

rate_bpsintegerrequired

Format: int64
Minimum: 0
Maximum: 5000

buyer_countrystringrequired

Pattern: ^[A-Z]{2}$

ip_countrystringrequired

Pattern: ^[A-Z]{2}$

country_sourcestringrequired

Allowed: geoip · test_fixture

get/v1/webhook-endpoint

getMerchantWebhookEndpoint

Read the configured merchant Checkout callback

The signing secret is write-once and is never returned by this read.

Bearer API keyServer to server

Responses

Merchant callback configuration without its full signing secret

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

configuredbooleanrequired
urlstring: Maximum length: 2048
signing_secretstring: EuniPay-generated epwhsec_ signing secret, present only in the first successful registration response or an exact idempotent replay.
signing_secret_suffixstring: Minimum length: 1
Maximum length: 16

put/v1/webhook-endpoint

registerMerchantWebhookEndpoint

Register the signed Checkout callback for this merchant environment

The Idempotency-Key must be reused only for the identical URL and rotate_signing_secret value. Set rotate_signing_secret to true only when intentionally replacing the callback signing secret. The full signing secret is returned once on a successful registration or exact idempotent replay. EuniPay sends checkout.paid with EuniPay-Timestamp, EuniPay-Signature, and EuniPay-Event-ID headers; the signature is HMAC-SHA256 over timestamp + "." + the raw JSON body. Non-2xx deliveries are retried with the same event ID.

Bearer API keyIdempotency-Key requiredServer to server

Parameters

Name	Location	Requirement	Schema	Description
`Idempotency-Key`	header	Required	Type: string Minimum length: 1 Maximum length: 255	One nonempty request key, unique within merchant, environment, and operation. Multiple or comma-joined values are rejected.

Request body

application/json · Required

No example provided.

Additional properties: not allowed

urlstringrequired: HTTPS callback URL. Test additionally permits loopback HTTP for local development.
Minimum length: 1
Maximum length: 2048
rotate_signing_secretbooleanrequired: Set true to replace the callback signing secret; set false to preserve it.

Responses

Registered merchant callback; only this response may contain signing_secret

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

configuredbooleanrequired
urlstring: Maximum length: 2048
signing_secretstring: EuniPay-generated epwhsec_ signing secret, present only in the first successful registration response or an exact idempotent replay.
signing_secret_suffixstring: Minimum length: 1
Maximum length: 16

Transactions

Confirm merchant-verified payments and read immutable Transactions.

post/v1/transactions/confirm

confirmTransaction

Confirm a merchant-declared payment from an immutable Tax Quote

Trusts the merchant declaration and does not contact Stripe or any other provider. Omitted confirmation_source defaults to provider, which requires provider_session_id and provider_payment_id. merchant_manual instead requires merchant_reference and forbids provider references. Tax values, amounts, rates, and snapshots are copied from the locked Tax Quote without recalculation. An identical confirmation of the same Quote returns its original Transaction and Receipt even under a different Idempotency-Key.

Bearer API keyIdempotency-Key requiredServer to server

Parameters

Name	Location	Requirement	Schema	Description
`Idempotency-Key`	header	Required	Type: string Minimum length: 1 Maximum length: 255	One nonempty request key, unique within merchant, environment, and operation. Multiple or comma-joined values are rejected.

Request body

application/json · Required

{
  "tax_quote_id": "tq_test_01J4EXAMPLE",
  "confirmation_source": "provider",
  "provider_session_id": "session_test_example",
  "provider_payment_id": "payment_test_example",
  "paid_at": "2026-08-01T12:10:00Z"
}

Additional properties: not allowed
One of: 2 schemas

tax_quote_idstringrequired: Minimum length: 1
Maximum length: 48
confirmation_sourcestring: Omit to use provider. Each source accepts only its conditional evidence fields.
Allowed: provider · merchant_manual
provider_session_idstring: Required only when confirmation_source is provider or omitted.
Minimum length: 1
Maximum length: 255
provider_payment_idstring: Required only when confirmation_source is provider or omitted.
Minimum length: 1
Maximum length: 255
merchant_referencestring: Required only when confirmation_source is merchant_manual.
Minimum length: 1
Maximum length: 255
paid_atstringrequired: Merchant-declared payment time. Provider confirmations must fall inside the original Quote window; manual confirmations use the retained-Quote eligibility window.
Format: date-time

One-of schema 1

confirmation_sourceunknown: Allowed: provider

One-of schema 2

confirmation_sourceunknownrequired: Constant: merchant_manual

Responses

Compact confirmation and pending Receipt state created or identically replayed

application/json

{
  "data": {
    "transaction_id": "txn_test_01J4EXAMPLE",
    "receipt_id": "rcp_test_01J4EXAMPLE",
    "receipt_number": "RCP-2026-000001",
    "pdf_status": "pending",
    "confirmed_at": "2026-08-01T12:10:01Z"
  }
}

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

transaction_idstringrequired
receipt_idstringrequired
receipt_numberstringrequired: Pattern: ^RCP-[0-9]{4}-[0-9]{6,}$
pdf_statusstringrequired: Allowed: pending · ready · failed
confirmed_atstringrequired: Format: date-time

get/v1/transactions/manual-confirmations/lookup

getManualConfirmation

Look up one merchant-manual confirmation by its exact merchant reference

Returns only a compact confirmation and Receipt identity for a merchant_manual Transaction in the authenticated merchant and API-key environment. This is an exact recovery lookup, not a Transaction list or general filter. Provider-confirmed Transactions never match.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`merchant_reference`	query	Required	Type: string Minimum length: 1 Maximum length: 255	Exact merchant-manual reference; no leading or trailing whitespace or control characters.

Responses

Existing merchant-manual confirmation and current safe Receipt state

application/json

{
  "data": {
    "confirmation_source": "merchant_manual",
    "merchant_reference": "merchant-manual:trade-123",
    "transaction_id": "txn_test_01J4EXAMPLE",
    "receipt_id": "rcp_test_01J4EXAMPLE",
    "receipt_number": "RCP-2026-000001",
    "pdf_status": "pending",
    "confirmed_at": "2026-08-01T12:10:01Z"
  }
}

Additional properties: not allowed

dataobjectrequired

Compact recovery view that never includes provider, Buyer, tax, location, VIES, retention, or object-store evidence.

Additional properties: not allowed

confirmation_sourcestringrequired: Constant: merchant_manual
merchant_referencestringrequired: Minimum length: 1
Maximum length: 255
transaction_idstringrequired: Maximum length: 48
Pattern: ^txn_[A-Za-z0-9_-]+$
receipt_idstringrequired: Maximum length: 48
Pattern: ^rcp_[A-Za-z0-9_-]+$
receipt_numberstringrequired: Maximum length: 64
Pattern: ^RCP-[0-9]{4}-[0-9]{6,}$
pdf_statusstringrequired: Allowed: pending · ready · failed
confirmed_atstringrequired: Format: date-time

get/v1/transactions/{transaction_id}

getTransaction

Get a scoped immutable Transaction and its safe Receipt state

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`transaction_id`	path	Required	Type: string Minimum length: 1 Maximum length: 48	—

Responses

Stored Transaction; no tax or currency value is recalculated

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Safe immutable view; raw seller, Buyer, location, VIES, retention, object-store, and worker snapshots are never returned.

Additional properties: not allowed
One of: 2 schemas

transaction_idstringrequired

tax_quote_idstringrequired

external_payment_attempt_idstringrequired

confirmation_sourcestringrequired

Identifies whether provider evidence or a merchant-manual reference confirmed the payment.

Allowed: provider · merchant_manual

provider_session_idstring

Present only for provider confirmations.

provider_payment_idstring

Present only for provider confirmations.

merchant_referencestring

Present only for merchant_manual confirmations.

paid_atstringrequired

Format: date-time

confirmed_atstringrequired

Format: date-time

buyer_countrystringrequired

Pattern: ^[A-Z]{2}$

buyer_entity_typestringrequired

Allowed: personal · business

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

tax_modestringrequired

Allowed: domestic_vat · oss_vat · reverse_charge

tax_semanticsstringrequired

The effective tax semantic inherited from the immutable Tax Quote; tax semantics are separate from tax mode.

Allowed: inclusive · exclusive

rate_bpsintegerrequired

Minimum: 0
Maximum: 5000

line_descriptionstringrequired

Minimum length: 1
Maximum length: 500

receiptobjectrequired

Additional properties: not allowed

receipt_idstringrequired
receipt_numberstringrequired: Pattern: ^RCP-[0-9]{4}-[0-9]{6,}$
issued_atstringrequired: Format: date-time
pdf_statusstringrequired: Allowed: pending · ready · failed

One-of schema 1

confirmation_sourceunknown: Constant: provider

One-of schema 2

confirmation_sourceunknown: Constant: merchant_manual

get/v1/transactions

listTransactions

List scoped Transactions using offset pagination

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`limit`	query	Optional	Type: integer Default: 100 Minimum: 1 Maximum: 200	—
`offset`	query	Optional	Type: integer Default: 0 Minimum: 0 Maximum: 100000	—

Responses

Transactions ordered by paid_at descending then Transaction ID descending

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

itemsarrayrequired

Items: object

Array item schema

Additional properties: not allowed
One of: 2 schemas

transaction_idstringrequired

tax_quote_idstringrequired

external_payment_attempt_idstringrequired

confirmation_sourcestringrequired

Identifies whether provider evidence or a merchant-manual reference confirmed the payment.

Allowed: provider · merchant_manual

provider_session_idstring

Present only for provider confirmations.

provider_payment_idstring

Present only for provider confirmations.

merchant_referencestring

Present only for merchant_manual confirmations.

paid_atstringrequired

Format: date-time

confirmed_atstringrequired

Format: date-time

buyer_countrystringrequired

Pattern: ^[A-Z]{2}$

buyer_entity_typestringrequired

Allowed: personal · business

paymentobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

baseobjectrequired

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

tax_modestringrequired

Allowed: domestic_vat · oss_vat · reverse_charge

tax_semanticsstringrequired

The effective tax semantic inherited from the immutable Tax Quote; tax semantics are separate from tax mode.

Allowed: inclusive · exclusive

rate_bpsintegerrequired

Minimum: 0
Maximum: 5000

line_descriptionstringrequired

Minimum length: 1
Maximum length: 500

receiptobjectrequired

Additional properties: not allowed

receipt_idstringrequired
receipt_numberstringrequired: Pattern: ^RCP-[0-9]{4}-[0-9]{6,}$
issued_atstringrequired: Format: date-time
pdf_statusstringrequired: Allowed: pending · ready · failed

One-of schema 1

confirmation_sourceunknown: Constant: provider

One-of schema 2

confirmation_sourceunknown: Constant: merchant_manual

totalintegerrequired

Minimum: 0

limitintegerrequired

Minimum: 1
Maximum: 200

offsetintegerrequired

Minimum: 0
Maximum: 100000

Reports

Export scoped transaction records without cross-currency totals.

get/v1/reports/transactions.csv

exportTransactionsCSV

Export scoped immutable Transactions as CSV

Exports Transactions whose paid_at is in the required half-open [from,to) interval, ordered by paid_at descending then Transaction ID descending. All amounts are integer minor units. Payment and base currencies remain explicit and no cross-currency or grand total is emitted. The export includes merchant-owned buyer/payment identifiers, commercial and VAT-rate versions, redacted VIES and location evidence metadata, Receipt state, and payment provider references. It never includes raw or encrypted IP data, VAT numbers, Buyer contact/address data, VIES raw responses, private object keys, PDF checksums, or stored snapshots. The requested interval may span at most 366 days. Each export is limited to 10,000 Transactions and 32 MiB of projected text. The same 30-second budget covers the database query and CSV encoding.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`from`	query	Required	Type: string Format: date-time	Inclusive paid_at lower bound.
`to`	query	Required	Type: string Format: date-time	Exclusive paid_at upper bound.
`buyer_country`	query	Optional	Type: string Pattern: ^[A-Z]{2}$	—
`buyer_entity_type`	query	Optional	Type: string Allowed: personal · business	—
`tax_mode`	query	Optional	Type: string Allowed: domestic_vat · oss_vat · reverse_charge	—
`payment_currency`	query	Optional	Type: string Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY	—
`rate_bps`	query	Optional	Type: integer Format: int64 Minimum: 0 Maximum: 5000	—

Responses

UTF-8 transaction CSV with a fixed header and formula-safe text cells

text/csv

transaction_id,integration_id,tax_quote_id,buyer_id,external_customer_id,external_payment_attempt_id,confirmation_source,merchant_reference,provider_session_id,provider_payment_id,paid_at,confirmed_at,late_confirmed,buyer_country,buyer_entity_type,line_description,tax_mode,rate_bps,payment_currency,payment_gross_minor,payment_net_minor,payment_vat_minor,business_payment_gross_minor,business_payment_net_minor,business_payment_vat_minor,platform_fee_payment_gross_minor,platform_fee_payment_net_minor,platform_fee_payment_vat_minor,base_currency,base_gross_minor,base_net_minor,base_vat_minor,business_base_gross_minor,business_base_net_minor,business_base_vat_minor,platform_fee_base_gross_minor,platform_fee_base_net_minor,platform_fee_base_vat_minor,base_to_payment_rate,commercial_rate_version_id,vat_rate_version_id,vies_status,vies_checked_at,vies_request_identifier,location_evidence_status,location_source,location_country,location_checked_at,location_database_build,location_database_checksum,location_country_matches_buyer,receipt_id,receipt_number,receipt_issued_at,receipt_pdf_status
txn_1,,tq_1,buy_1,customer_1,attempt_1,provider,,cs_1,pi_1,2026-07-01T12:00:00Z,2026-07-01T12:01:00Z,true,DE,personal,Service,oss_vat,1900,EUR,11900,10000,1900,0,0,0,0,0,0,SEK,119000,100000,19000,0,0,0,0,0,0,0.100000000000,fx_1,vat_1,skipped,2026-07-01T11:59:00Z,,captured,client_ip,DE,2026-07-01T11:59:00Z,GeoLite2-20260701,aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa,true,rcp_1,RCP-2026-000001,2026-07-01T12:01:00Z,ready

No schema constraints provided.

Receipts

Read Receipt generation state and create short-lived private PDF links.

get/v1/receipts/{receipt_id}

getReceipt

Get safe Receipt metadata and payment breakdowns

Returns a Receipt only in the API key's merchant and Test/Live environment. Pending and failed Receipts are returned normally so the merchant can poll. Query parameters are rejected. Tax snapshots, object-store keys, checksums, retention metadata, and worker errors are never returned. Optional payment, business, and platform_fee amounts come only from the validated stored Receipt snapshot; no current fee or tax settings are consulted. Missing or invalid snapshots omit these fields without preventing metadata reads or existing PDF downloads.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`receipt_id`	path	Required	Type: string	—

Responses

Safe Receipt metadata

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Safe scoped PDF-generation state and optional payment-currency amounts in integer minor units. Amounts are copied or derived from the validated stored Receipt snapshot after matching its receipt number and issue time. Missing or invalid snapshots omit all three amount objects. Historical snapshots without a fee return equal payment and business amounts and omit platform_fee. Raw snapshots, buyer and seller details, base-currency amounts, tax evidence, and private storage metadata are never returned.

Additional properties: not allowed

receipt_idstringrequired

Minimum length: 1
Maximum length: 48

transaction_idstringrequired

Minimum length: 1
Maximum length: 48

receipt_numberstringrequired

Pattern: ^RCP-[0-9]{4}-[0-9]{6,}$

issued_atstringrequired

Format: date-time

pdf_statusstringrequired

Allowed: pending · ready · failed

pdf_generated_atstring

Present only when pdf_status is ready.

Format: date-time

paymentobject

Total paid amount including any Platform fees and VAT.

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

businessobject

Business amount; payment minus platform_fee, component by component.

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

platform_feeobject

Platform fees stored on the Receipt; omitted when no fee was recorded.

Additional properties: not allowed

currencystringrequired: Allowed: EUR · CZK · DKK · HUF · PLN · RON · SEK · CNY
gross_amountintegerrequired: Format: int64
Minimum: 0
net_amountintegerrequired: Format: int64
Minimum: 0
vat_amountintegerrequired: Format: int64
Minimum: 0

get/v1/receipts/{receipt_id}/pdf

getReceiptPDF

Download a ready Receipt PDF through EuniPay

Returns PDF bytes only after the Receipt and private object key match the authenticated merchant, integration, and Test/Live environment. Query parameters are rejected. Pending and failed Receipts return 409.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`receipt_id`	path	Required	Type: string	—

Responses

Ready Receipt PDF

application/pdf

No example provided.

Format: binary

post/v1/receipts/{receipt_id}/download-link

createReceiptDownloadLink

Create a private ten-minute Receipt PDF download URL

Accepts exactly one empty JSON object and no query parameters. Pending and failed Receipts return 409 without contacting object storage. A ready Receipt is signed only after its private object key matches the authenticated merchant and Test/Live environment. Signed URLs must not be logged or persisted by clients.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`receipt_id`	path	Required	Type: string	—

Request body

application/json · Required

No example provided.

Maximum properties: 0
Additional properties: not allowed

Responses

Short-lived private download URL

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

download_urlstringrequired: Private HTTP(S) URL valid for exactly ten minutes.
Format: uri
expires_atstringrequired: Format: date-time

Buyers

Create, version, and read merchant-scoped Buyer Profiles.

get/v1/buyers/{external_customer_id}

getBuyerProfile

Get the current Buyer Profile version

When the Buyer is permanently locked, country, entity type, and VAT display values are projected from the permanent identity lock even if the latest historical profile predates the lock and differs. The returned version remains the current profile version.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`external_customer_id`	path	Required	Type: string Minimum length: 1	Immutable merchant-local customer identifier; 1-128 UTF-8 bytes, no control characters, and no leading or trailing whitespace.

Responses

Current Buyer Profile

application/json

No example provided.

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

buyer_idstringrequired

external_customer_idstringrequired

versionintegerrequired

Minimum: 1

entity_typestringrequired

Allowed: personal · business

namestringrequired

emailstringrequired

countrystringrequired

postal_codestringrequired

state_regionstring

citystringrequired

line_1stringrequired

line_2string

vat_number_displaystring

identity_lockobjectrequired

Additional properties: not allowed

lockedbooleanrequired
locked_atstring | nullrequired: Format: date-time
locked_fieldsarrayrequired: Items: string
Array item schema
Allowed: country · entity_type · vat_number
locked_by_transaction_idstring

created_atstringrequired

Format: date-time

put/v1/buyers/{external_customer_id}

putBuyerProfile

Create or update a versioned Buyer Profile

Initial creation requires expected_version 0. Every later successful update must use the exact current version. External customer IDs are never trimmed or rewritten; leading or trailing whitespace is rejected.

Bearer API keyServer to server

Parameters

Name	Location	Requirement	Schema	Description
`external_customer_id`	path	Required	Type: string Minimum length: 1	Immutable merchant-local customer identifier; 1-128 UTF-8 bytes, no control characters, and no leading or trailing whitespace.

Request body

application/json · Required

{
  "expected_version": 0,
  "entity_type": "business",
  "name": "Example GmbH",
  "email": "billing@example.invalid",
  "country": "DE",
  "postal_code": "10115",
  "city": "Berlin",
  "line_1": "Invalidenstrasse 1",
  "vat_number": "DE123456789"
}

Additional properties: not allowed
All of: 1 schema

expected_versionintegerrequired: Minimum: 0
entity_typestringrequired: Allowed: personal · business
namestringrequired: Minimum length: 1
Maximum length: 256
emailstringrequired: Must contain @.
Minimum length: 1
Maximum length: 256
Pattern: .*@.*
countrystringrequired: EU 27 billing country.
Pattern: ^[A-Z]{2}$
postal_codestringrequired: Minimum length: 1
Maximum length: 32
state_regionstring: Maximum length: 128
citystringrequired: Minimum length: 1
Maximum length: 128
line_1stringrequired: Minimum length: 1
Maximum length: 512
line_2string: Maximum length: 512
vat_numberstring: Required for business profiles. Format validation only; optional matching country prefix
Maximum length: 64

All-of schema 1

Condition

entity_typeunknown: Constant: business

When condition matches

Required fields: vat_number

Responses

New immutable Buyer Profile version

application/json

{
  "data": {
    "buyer_id": "byr_test_01J4EXAMPLE",
    "external_customer_id": "customer_123",
    "version": 1,
    "entity_type": "business",
    "name": "Example GmbH",
    "email": "billing@example.invalid",
    "country": "DE",
    "postal_code": "10115",
    "city": "Berlin",
    "line_1": "Invalidenstrasse 1",
    "vat_number_display": "DE123456789",
    "identity_lock": {
      "locked": false,
      "locked_at": null,
      "locked_fields": []
    },
    "created_at": "2026-08-01T11:59:00Z"
  }
}

Additional properties: not allowed

dataobjectrequired

Additional properties: not allowed

buyer_idstringrequired

external_customer_idstringrequired

versionintegerrequired

Minimum: 1

entity_typestringrequired

Allowed: personal · business

namestringrequired

emailstringrequired

countrystringrequired

postal_codestringrequired

state_regionstring

citystringrequired

line_1stringrequired

line_2string

vat_number_displaystring

identity_lockobjectrequired

Additional properties: not allowed

lockedbooleanrequired
locked_atstring | nullrequired: Format: date-time
locked_fieldsarrayrequired: Items: string
Array item schema
Allowed: country · entity_type · vat_number
locked_by_transaction_idstring

created_atstringrequired

Format: date-time