Margin Configuration

Margins define additional spread applied to exchange rates (quote). They directly affect the rate and totalAmount values returned by the quote endpoint.

---

Overview

A margin is a cost adjustment applied on top of the base exchange rate. When a quote is generated, any configured margins for the matching context and currency are automatically applied.

Margins are evaluated before executing payment orders operations

Endpoint

PUT /margin

API Reference: Create or update margin settings

---

Authentication

This endpoint requires a valid Bearer Token in the Authorization header:

Authorization: Bearer <your_token>

The following user roles are authorized to use this endpoint:

Role	Capabilities
store	Create global and individual margins
branch	Manage margins scoped to their own data

---

Margin Types

The type field determines how the margin value is applied to the base rate:

Type	Description
fixed	Adds a fixed absolute amount to the operation
percentage	Applies a percentage over the base exchange rate

---

Scope

Margins can be scoped globally or to a specific branch:

Global

• Can be created by both store and branch users.
• When created by a store:
• • The margin applies to the store itself.
• • It is automatically propagated to all its branches.
• When created by a branch:
• • The margin applies only to that specific branch. ownerId must NOT be included in the request body.

Individual

• Can only be created from store user into a branch user via ownerId
• ownerId represents the branch identifier (branch.id)

---

Request Example

Example

curl -X PUT "/api/v1/margin" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "type": "percentage",
    "context": "payment_order",
    "value": 2.5,
    "currency": "BRL",
    "ownerId": "123e4567-e89b-12d3-a456-426614174010"
  }'

In this example, a 2.5% margin is applied to payment_order operations in BRL, scoped to the branch identified by ownerId.

Owner id is the id of the branch entity (branch.id)

---

Example: How Margins Affect a Quote

Base values

• Base quote: 5.00
• Global store margin: 0.01

---

1. Store global margin only

When only the store-level global margin is applied, it affects the store itself and all of its branches. Every branch inherits this margin by default:

5.00 + 0.01 = 5.01

---

2. Individual branch margin + globa store margin

If a branch has its own fixed margin created by it store, it overrides the global store margin:

• Individual branch margin created by store: 0.02

5.00 + 0.02 = 5.02

---

3. Branch with indivdual store margin + branch global margin

If the branch has:

• Store individual margin: 0.01
• Branch global margin: 0.02

Then both are applied together:

5.00 + 0.01 + 0.02 = 5.03

---

4. Branch with both store margin + branch global margin

If the branch has:

• Store global margin: 0.01
• Branch global margin: 0.02

Then both are applied together:

5.00 + 0.01 + 0.02 = 5.03

---

Important Notes

• store users can create both global and individual margins
• branch users can only manage margins scoped to their own branch
• Margins directly affect financial operations — review them carefully before going live