customerId when creating the payment.
This ID links the stored card to the customer and enables quick-checkout functionality in future sessions.
security:
- BearerAuth: []
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
requestBody:
description: MIT authorization request payload.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MitAuthorizationRequest"
example:
subscriptionId: "01929a94-5fce-7ccc-a7e4-7e9249133b39"
amount: 500
currency: "DKK"
reference: "reference-2"
instantCapture: "OFF"
textOnStatement: "The text"
notificationUrl: "https://yape.dev"
attributes:
key1: "value1"
key2: "value2"
responses:
"200":
description: MIT authorization requested successfully created. Processing will begin shortly.
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionResponse"
example:
transaction:
id: "LDG7M4WW44G"
amount: 500
currency: "DKK"
clientIp: ""
customerId: "User159"
exemptions: []
instantCapture: "OFF"
paymentMethodId: "01924756-d1f6-738d-8040-90d76cedf01f"
paymentMethodType: "CARD"
paymentMethodSubType: "Visa"
paymentMethodExpiry: "2050-01-01"
paymentMethodDisplayText: "40000000XXXX0003"
pointOfSaleId: "01924737-9c18-71c0-ab1a-88698eaceabf"
reference: "reference-2"
scaMode: "SKIP"
sessionId: null
state: "PENDING"
errorCode: null
subscriptionId: "01929a94-5fce-7ccc-a7e4-7e9249133b39"
textOnStatement: "The text"
createdAt: "2024-10-17T15:07:03.290909169+02:00"
attributes:
key1: "value1"
key2: "value2"
type: "PAYMENT"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/mit/batch:
post:
tags:
- Transactions
summary: MIT Batch Authorization
description: >
:::warning Rate limits
Please review our rate limits before you begin your implementation.
:::
Create multiple MIT (Merchant-Initiated Transaction) authorizations in a single request.
Each entry mirrors the single MIT endpoint and is processed asynchronously, supporting partial success across the batch.
Each transaction is processed individually, if the transaction passes initial validation then a transaction is created for background processing and a `transaction` is returned.
If the initial validation fails, instead an `error` is returned. You will receive one callback for each individual transaction.
customerId when creating the payment.
This ID links the stored card to the customer and enables quick-checkout functionality in future sessions.
security:
- BearerAuth: []
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
requestBody:
description: MIT batch authorization request payload.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateMitBatchTransactionRequest"
responses:
"200":
description: MIT batch accepted; returns per-entry creation results while processing continues asynchronously. Each transaction is processed individually, if the transaction passes initial validation then a transaction is created for background processing and a `transaction` is returned. If the initial validation fails, instead an `error` is returned.
content:
application/json:
schema:
$ref: "#/components/schemas/CreateMitBatchTransactionResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/moto:
post:
tags:
- Transactions
summary: MOTO Authorization
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
description: |
:::warning PCI-DSS Compliance
As this endpoint receives raw payment data, the integrator is required to provide documentation for PCI-DSS compliance before access can be granted.
:::
This endpoints creates and processes an online MOTO transaction and returns the authorization result in the response.
This is typically used within the travel industry, where it is more common for customers to provide their card info over the phone when booking a vacation.
This can be used by merchants to automate authorizations when receiving card info from brokers such as hotels.com and booking.com.
security:
- BearerAuth: []
requestBody:
description: Transaction processing result
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateMotoTransactionRequest"
responses:
"200":
description: Successful payment session initialization response.
content:
application/json:
schema:
$ref: "#/components/schemas/NotificationWebhook"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/transactions/{transactionId}/capture:
post:
tags:
- Transactions
summary: Capture Payment
description: Capture a payment by transferring funds from the cardholder's bank.
security:
- BearerAuth: []
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
- name: transactionId
in: path
description: The id of the transaction to capture.
required: true
schema:
type: string
requestBody:
description: Capture request payload.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CaptureRequest"
example:
amount: 1095
responses:
"200":
description: Capture operation response.
content:
application/json:
schema:
$ref: "#/components/schemas/OperationResponse"
example:
operationId: "019248e0-0ff4-7c1e-9438-f7648c9ff0fe"
success: false
errorCode:
code: "DECLINED_BY_ISSUER_OR_SCHEME"
message: "The operation was rejected by either the issuer or schemes."
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/transactions/{transactionId}/refund:
post:
tags:
- Transactions
summary: Refund Payment
description: >
Refund a captured payment. Partial refunds are allowed.
/cit](/api/initialize-payment-session) endpoint, and perform MIT transactions directly.
/cit](/api/initialize-payment-session) endpoint by sending the Subscription object.
- Billing Plan: Defines recurring details like price, interval, and retry policy. Used only when ePay manages the billing schedule automatically.
- Billing Agreement: Connects a Subscription to a Billing Plan. Tracks scheduled processing and charge lifecycle.
- Billing Agreement Charge: Represents a scheduled billing event created from an agreement. Each charge can have multiple transaction attempts and a completion deadline.
- Transaction: The base payment model used for all processing. Charges and transactions are linked to maintain attempt history.
:::
security:
- BearerAuth: [ ]
requestBody:
description: Create billing agreement data
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateBillingAgreementRequest"
responses:
"200":
description: Billing agreement details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingAgreementResource"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
get:
tags:
- Subscription Billing
summary: List Billing Agreements
description: Returns a paginated list of all billing agreements associated to your account.
security:
- BearerAuth: [ ]
responses:
"200":
description: Billing agreement details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingAgreementsListResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/subscriptions/billing/agreements/{agreementId}:
get:
tags:
- Subscription Billing
summary: Get Billing Agreement
description: Returns the specific billing agreement from its id
security:
- BearerAuth: [ ]
parameters:
- name: agreementId
in: path
description: The id of the agreement to fetch.
required: true
schema:
type: string
responses:
"200":
description: Billing agreement details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingAgreementResource"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/subscriptions/billing/agreements/{agreementId}/stop:
post:
tags:
- Subscription Billing
summary: Stop Billing Agreement
description: Stop automatic billing charges for the given billing agreement. No more automatic charges will be made for the agreement, until `/resume` is called.
security:
- BearerAuth: [ ]
parameters:
- name: agreementId
in: path
description: The id of the agreement to stop.
required: true
schema:
type: string
responses:
"200":
description: Billing agreement details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingAgreementResource"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/subscriptions/billing/agreements/{agreementId}/resume:
post:
tags:
- Subscription Billing
summary: Resume Billing Agreement
description: Resume automatic billing charges for the given billing agreement. Charges will begin again, with the first charge made on the given `nextChargeAt` date.
security:
- BearerAuth: [ ]
parameters:
- name: agreementId
in: path
description: The id of the agreement to stop.
required: true
schema:
type: string
requestBody:
description: Create billing agreement data
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ResumeBillingAgreementRequest"
responses:
"200":
description: Billing agreement details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingAgreementResource"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/subscriptions/billing/plans:
post:
tags:
- Subscription Billing
summary: Create Billing Plan
description: >
Creates a new billing plan. Billing plans are the basis of all billing agreements with automatic charges.
:::info Relationship to other components
- Subscription: The underlying link between a merchant and a stored payment method. Created via the [Initialize Payment Session /cit](/api/initialize-payment-session) endpoint by sending the Subscription object.
- Billing Plan: Defines recurring details like price, interval, and retry policy. Used only when ePay manages the billing schedule automatically.
- Billing Agreement: Connects a Subscription to a Billing Plan. Tracks scheduled processing and charge lifecycle.
- Billing Agreement Charge: Represents a scheduled billing event created from an agreement. Each charge can have multiple transaction attempts and a completion deadline.
- Transaction: The base payment model used for all processing. Charges and transactions are linked to maintain attempt history.
:::
security:
- BearerAuth: [ ]
requestBody:
description: Create billing plan data
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateBillingPlanRequest"
responses:
"200":
description: Billing plan details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingPlanResource"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
get:
tags:
- Subscription Billing
summary: List Billing Plans
description: Returns a paginated list of all the billing plans associated your account. Billing plans are the basis for all billing agreement and automatic charges. They define the price and interval between charges.
security:
- BearerAuth: [ ]
responses:
"200":
description: Billing plan details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingPlansListResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/subscriptions/billing/plans/{planId}:
get:
tags:
- Subscription Billing
summary: Get Billing Plan
description: Returns the specific billing plan from its id
security:
- BearerAuth: [ ]
parameters:
- name: planId
in: path
description: The id of the plan to fetch.
required: true
schema:
type: string
responses:
"200":
description: Billing plan details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingPlanResource"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/subscriptions/billing/charges:
get:
tags:
- Subscription Billing
summary: List Billing Charges
description: >
Returns a paginated list of billing agreement charges created for your merchant account.
Use this endpoint to audit scheduled billing events, see their states, and review current or historic attempts.
You can optionally filter the list by `billingAgreementId` to focus on a single agreement.
security:
- BearerAuth: [ ]
parameters:
- name: billingAgreementId
in: query
description: Optional UUID of a billing agreement to filter the charges list.
schema:
type: string
format: uuid
- name: page
in: query
description: Page number.
schema:
type: integer
default: 1
- name: perPage
in: query
description: Number of items per page.
schema:
type: integer
default: 25
maximum: 500
responses:
"200":
description: Billing agreement charge details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingAgreementChargesListResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/subscriptions/billing/charges/{billingAgreementChargeId}:
get:
tags:
- Subscription Billing
summary: Get Billing Charge
description: Returns the specific billing agreement charge by id.
security:
- BearerAuth: [ ]
parameters:
- name: billingAgreementChargeId
in: path
description: The id of the billing agreement charge to fetch.
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Billing agreement charge details.
content:
application/json:
schema:
$ref: "#/components/schemas/BillingAgreementChargeResource"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/webhooks:
get:
tags:
- Webhooks
summary: List Webhooks
description: >
Returns a paginated list of active webhooks configured for the authenticated merchant.
Use this endpoint to audit webhook destinations, verify subscribed events, and ensure each webhook aligns with your point-of-sale domains.
security:
- BearerAuth: [ ]
parameters:
- name: page
in: query
description: Page number.
schema:
type: integer
default: 1
- name: perPage
in: query
description: Number of items per page.
schema:
type: integer
default: 25
maximum: 500
responses:
"200":
description: Paginated webhook collection.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhooksListResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
post:
tags:
- Webhooks
summary: Create Webhook
description: >
Registers a new webhook endpoint limited to domains already approved on your point of sale configuration.
A maximum of 10 active webhooks is allowed per merchant. Each webhook must subscribe to one or more supported events and include a shared secret used as the value of the `Authorization` header when sending webhook.
security:
- BearerAuth: [ ]
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
requestBody:
description: Webhook configuration payload.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/StoreWebhookRequest"
responses:
"200":
description: Newly created webhook.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookResource"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/webhooks/{webhookId}:
delete:
tags:
- Webhooks
summary: Delete Webhook
description: Deletes a webhook configuration, stopping ePay from delivering further notifications to the URL.
security:
- BearerAuth: [ ]
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
- name: webhookId
in: path
description: ID of the webhook to delete.
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Webhook deleted successfully. No content returned.
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/cit:
post:
tags:
- Sessions
summary: Initialize Payment Session
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
description: |
Initializes a new payment session with the ePay Payments API.
This endpoint requires a valid ApiKey and must be called from the server side
to ensure the ApiKey is never exposed client-side.
:::info Required or configurable fields
In the ePay backoffice, under Advanced Point of Sale Settings, you can set default values for many session initialization parameters. This allows you to manage your setup without updating your code.
Each property must be defined either in the backoffice or in the API request. If a value is provided in the API request, it overrides the backoffice default.
The following fields can be configured:
- `scaMode`
- `timeout`
- `instantCapture`
- `processor`
- `maxAttempts`
- `notificationUrl`
- `successUrl`
- `failureUrl`
- `exemptions`
Note: Only a subset of these fields are strictly required for the API request. The table below indicates which fields are mandatory or optional.
:::
security:
- BearerAuth: []
requestBody:
description: Payment session initialization payload.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentSessionInitializationRequest"
example:
pointOfSaleId: "01924737-9c18-71c0-ab1a-88698eaceabf"
reference: "reference-1"
amount: 1000
currency: "DKK"
scaMode: "SKIP"
timeout: 60
instantCapture: "OFF"
processor: ["shift4", "clearhaus", "nets"]
exemptions: ["TRA"]
textOnStatement: "The text"
attributes:
key1: "value1"
key2: "value2"
customerId: "User159"
maxAttempts: 10
reportFailure: false
dynamicAmount: false
notificationUrl: "https://example.com/notification"
preAuthUrl: "https://example.com/pre-auth"
successUrl: "https://example.com/success"
failureUrl: "https://example.com/failure"
subscription:
type: "SCHEDULED"
reference: "subscription-1"
expiryDate: "2050-01-01"
interval:
period: "MONTH"
frequency: 1
responses:
"200":
description: Successful payment session initialization response.
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentSessionInitializationResponse"
example:
paymentWindowUrl: "https://payments.epay.eu/payment-window?sessionId=0192473a-e382-79a9-bfc2-65da88fe812f&sessionKey=4651656e-f29e-4dfa-a1cd-a65647862011"
javascript: "https://payments.epay.eu/sessions/0192473a-e382-79a9-bfc2-65da88fe812f/client.js"
key: "4651656e-f29e-4dfa-a1cd-a65647862011"
session:
id: "0192473a-e382-79a9-bfc2-65da88fe812f"
subscriptionId: "01929a94-5fce-7ccc-a7e4-7e9249133b39"
amount: 1000
attributes:
key1: "value1"
key2: "value2"
exemptions: ["TRA"]
currency: "DKK"
expiresAt: "2024-10-01T12:41:14.658688472+02:00"
instantCapture: "OFF"
maxAttempts: 10
reportFailure: false
dynamicAmount: false
notificationUrl: "https://example.com/notification"
preAuthUrl: "https://example.com/pre-auth"
successUrl: "https://example.com/success"
failureUrl: "https://example.com/failure"
pointOfSaleId: "0192473a-e381-705c-b61c-fc2ac9624afc"
reference: "reference-1"
state: "PENDING"
textOnStatement: "The text"
scaMode: "SKIP"
timeout: 60
createdAt: "2024-10-01T10:38:14.658688472+02:00"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/payment-links:
post:
tags:
- Payment Links
summary: Create Payment Link
description: |
Creates a new payment link with the ePay Payments API.
This endpoint requires a valid ApiKey and must be called from the server side
to ensure the ApiKey is never exposed client-side.
:::info Required fields
In the ePay backoffice in the advanced Point of Sale settings you can set the default for many of the session initialization parameters, allowing you to change your setup from the interface without updating your code.
Properties must be defined in either the point of sale settings or the API request. The API request takes precedence and overwrites any point of sale settings if present.
These fields are:
- `scaMode`
- `timeout`
- `instantCapture`
- `processor`
- `maxAttempts`
- `notificationUrl`
- `successUrl`
- `failureUrl`
:::
security:
- BearerAuth: []
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
requestBody:
description: Create payment link initialization payload.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePaymentLinkRequest"
responses:
"200":
description: Successful payment link creation response.
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePaymentLinkResponse"
example:
id: "KSNMWEWZPPA"
sessionId: "01975f11-329f-7c14-a03a-3739d8b48ef3"
url: "https://payments.epay.eu/link/KSNMWEWZPPA"
qrCode: "/9j/2wCEAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4n...."
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/payment-links/{id}:
delete:
tags:
- Payment Links
summary: Cancel Payment Link
description: |
Cancels a payment link that has not yet been completed.
A payment link can only be cancelled if no transactions are currently being processed for it. If the payment link cannot be cancelled, an `UNEXPECTED_SESSION_STATE` error is returned.
security:
- BearerAuth: [ ]
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
- name: id
in: path
description: ID of the payment-link to cancel.
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Payment link cancelled successfully. No content returned.
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/payment-methods/imported:
get:
tags:
- Payment Methods
summary: List Imported Payment Methods
description: >
Retrieve imported payment methods for the authenticated merchant using cursor-based pagination ordered by newest `id`.
Each entry includes the imported payment method, its underlying payment method, and associated card details (if any).
security:
- BearerAuth: []
parameters:
- name: perPage
in: query
description: Maximum number of results to return in the response.
schema:
type: integer
default: 25
maximum: 500
minimum: 1
- name: offset
in: query
description: Cursor returned by `nextOffset`. Provide the id of the last item from the previous page to fetch entries with a lower `id`. Use an empty string to fetch the first page.
schema:
type: string
example: ""
responses:
"200":
description: Cursor paginated imported payment methods.
content:
application/json:
schema:
$ref: "#/components/schemas/ImportedPaymentMethodsListResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/settlements/transfers:
get:
tags:
- Settlements
summary: List settlement transfers
description: >
List settlement transfers. Settlement transfers models the actual bank payouts from the acquirer to your bank.
:::info Relationship to other components
- Settlement Transfer: A bank transfer / payout / settlement from the acquirer to your bank.
- Settlement Transaction: Settlement data for a specific transaction, can be related to an ePay transaction if the transaction was made through ePay.
- Adjustments: Any modifications the acquirer makes to the transaction amount, before arriving at the net amount being paid out. This includes both transaction, settlement and service fees, but also any reimbursements or currency exchange fees.
- Transactions: An ePay transaction. If an acquirer transaction within the settlement data was processed through ePay, it will be linked to the Settlement Transaction.
:::
security:
- BearerAuth: []
parameters:
- name: perPage
in: query
description: Maximum number of results to return in the response.
schema:
type: integer
default: 25
maximum: 500
minimum: 1
- name: offset
in: query
description: Cursor returned by `nextOffset`. Omit or pass an empty string to fetch the first page.
schema:
type: string
example: 019b3168-9334-770c-b34f-829d3c9c65d1
responses:
"200":
description: Cursor-paginated settlement transfers
content:
application/json:
schema:
$ref: "#/components/schemas/SettlementTransferCursor"
"401":
description: Missing/invalid API key
"500":
description: Server error
/public/api/v1/settlements/transfers/{transferId}:
get:
tags:
- Settlements
summary: Show settlement transfer
description: >
Show settlement transfers. Settlement transfers models the actual bank payouts from the acquirer to your bank.
:::info Relationship to other components
- Settlement Transfer: A bank transfer / payout / settlement from the acquirer to your bank.
- Settlement Transaction: Settlement data for a specific transaction, can be related to an ePay transaction if the transaction was made through ePay.
- Adjustments: Any modifications the acquirer makes to the transaction amount, before arriving at the net amount being paid out. This includes both transaction, settlement and service fees, but also any reimbursements or currency exchange fees.
- Transactions: An ePay transaction. If an acquirer transaction within the settlement data was processed through ePay, it will be linked to the Settlement Transaction.
:::
security:
- BearerAuth: []
parameters:
- in: path
name: transferId
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Settlement transfer
content:
application/json:
schema:
type: object
properties:
settlementTransfer:
$ref: "#/components/schemas/SettlementTransfer"
"401":
description: Missing/invalid API key
"404":
description: Transfer not found or not owned by merchant
"500":
description: Server error
/public/api/v1/settlements/transfers/{transferId}/transactions:
get:
tags:
- Settlements
summary: List settlement transactions
description: >
List settlement transactions. Settlement transactions gives pr. transaction insight into the fees paid to the acquirer, scheme and network.
Normal acquirer agreements often only contain a single `acquirer` fee, which represent your blended pricing at the acquirer.
Larger merchants working with IC++ pricing will typically see a breakdown of the transaction cost into `interchange` fees (Set by the issuer bank), `scheme` fee (Set by Visa/Mastercard) and `acquirer` fee (Set by the acquirer).
Do note, one ePay transaction can be linked to multiple settlement transactions if multiple partial captures or refunds are used.
:::info Relationship to other components
- Settlement Transfer: A bank transfer / payout / settlement from the acquirer to your bank.
- Settlement Transaction: Settlement data for a specific transaction, can be related to an ePay transaction if the transaction was made through ePay.
- Adjustments: Any modifications the acquirer makes to the transaction amount, before arriving at the net amount being paid out. This includes both transaction, settlement and service fees, but also any reimbursements or currency exchange fees.
- Transactions: An ePay transaction. If a settlement transaction was processed through ePay, it will be linked to the ePay Transaction.
:::
security:
- BearerAuth: []
parameters:
- in: path
name: transferId
required: true
schema:
type: string
format: uuid
- name: perPage
in: query
description: Maximum number of results to return in the response.
schema:
type: integer
default: 25
maximum: 500
minimum: 1
- name: offset
in: query
description: Cursor returned by `nextOffset`. Omit or pass an empty string to fetch the first page.
schema:
type: string
example: 019b3168-9334-770c-b34f-829d3c9c65d1
responses:
"200":
description: Cursor-paginated settlement transactions
content:
application/json:
schema:
$ref: "#/components/schemas/SettlementTransactionCursor"
"401":
description: Missing/invalid API key
"404":
description: Transfer not found or not owned by merchant
"500":
description: Server error
/public/api/v1/management/point-of-sales:
post:
tags:
- Management
summary: Create Point of Sale
description: >
Create a new Point of Sale and its associated hosted configuration.
Note: The `webhookAuthentication` value is the entire `Authorization` header value send for any webhook. So you must include the auth scheme such as `Bearer` or `Basic`.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/StorePointOfSaleRequest"
responses:
"200":
description: Created
content:
application/json:
schema:
$ref: "#/components/schemas/DetailedPointOfSale"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
get:
tags:
- Management
summary: List Points of Sales
description: >
Retrieve a paginated list of points of sale.
Query parameters `page` and `perPage` can be used to control pagination.
security:
- BearerAuth: []
parameters:
- name: page
in: query
description: Page number.
schema:
type: integer
default: 1
- name: perPage
in: query
description: Number of items per page.
schema:
type: integer
default: 25
maximum: 500
responses:
"200":
description: A paginated list of points of sale.
content:
application/json:
schema:
$ref: "#/components/schemas/PointOfSaleListResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/management/point-of-sales/{pointOfSaleId}:
get:
tags:
- Management
summary: Get Point of Sale
description: Retrieve a single Point of Sale with its hosted configuration.
security:
- BearerAuth: []
parameters:
- name: pointOfSaleId
in: path
required: true
description: UUID of the Point of Sale
schema:
type: string
format: uuid
responses:
"200":
description: The requested Point of Sale.
content:
application/json:
schema:
$ref: "#/components/schemas/DetailedPointOfSale"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/management/api-keys:
post:
summary: "Create API key"
description: |
Creates a new merchant API key. This is the key merchants and external systems must use to communicate with the ePay API.
*Partner Specific:* Partners should instead use partner keys to generate an access token, when accessing ePay apis on behalf our merchants.
tags:
- Management
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateApiKeyRequest"
responses:
"200":
description: API key created
content:
application/json:
schema:
$ref: "#/components/schemas/CreateApiKeyResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/partner/accounts:
post:
summary: "Create merchant Account"
description: Use this endpoint to create a new merchant account associated with your partner profile.
tags:
- Partner
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePartnerAccountRequest"
responses:
"200":
description: Account created
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePartnerAccountResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
get:
summary: "List merchant Accounts"
tags:
- Partner
parameters:
- name: page
in: query
description: Page number.
schema:
type: integer
default: 1
- name: perPage
in: query
description: Number of items per page.
schema:
type: integer
default: 25
maximum: 500
responses:
"200":
description: This endpoint can be used to fetch all merchant accounts associated with your partner profile.
content:
application/json:
schema:
$ref: "#/components/schemas/AccountsListResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/partner/accounts/{accountId}:
get:
summary: "Show merchant Account"
description: Fetches merchant account details for the request id.
tags:
- Partner
parameters:
- name: accountId
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Account details
content:
application/json:
schema:
$ref: "#/components/schemas/ShowPartnerAccountResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
delete:
summary: "Close merchant Account"
description: Marks a merchant account for closing. The account is not instantly closed, but will be closed during the next billing period by ePay.
tags:
- Partner
parameters:
- name: accountId
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Account closed successfully
content: {}
"400":
$ref: "#/components/responses/ErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/partner/accounts/{accountId}/activate:
patch:
summary: "Activate merchant Live Account"
description: To enable a merchant to go live, and begin billing, use this endpoint. To receive real production payments, a merchant account must be marked as live.
tags:
- Partner
parameters:
- name: accountId
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Account activated successfully
content: {}
"400":
$ref: "#/components/responses/ErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
/public/api/v1/partner/accounts/{accountId}/access-token:
post:
summary: "Request Merchant Access Token"
description: |
To access the ePay API on behalf of a merchant under your partner profile, partners must create a access token for the merchant before sending requests. An access token expires after 8 hours.
Access token requests are cached in one hour, so any subsequent access token requests for the same merchant and environment may return the same token as previously requested, within the cache period.
The returned access token is used in-place of the merchant API key in the `Authorization` header.
tags:
- Partner
parameters:
- name: accountId
in: path
required: true
schema:
type: string
format: uuid
- name: Authorization
in: header
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePartnerAccessTokenRequest"
responses:
"200":
description: Access token created
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePartnerAccessTokenResponse"
"400":
$ref: "#/components/responses/ErrorResponse"
"422":
$ref: "#/components/responses/ValidationErrorResponse"
"500":
$ref: "#/components/responses/ErrorResponse"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
description: |
Ensures that a request can be safely retried without causing duplicate operations.
Typically used for actions like payment creation and operations such as refund and void to prevent accidental double processing.
- If a response is replayed due to using the same key, the response will include the header `Idempotent-Replayed: true`.
- Idempotency keys are scoped by **[Key, Endpoint, HTTP Verb]**; the same key on a different endpoint or method will not replay the original response.
- Responses are cached for **24 hours**. After that, the cache is cleared, so idempotency is only guaranteed within 24 hours of the initial request.
required: false
schema:
type: string
example: "c4f5e8d2-1234-5678-90ab-cdef12345678"
responses:
ErrorResponse:
description: |
Standard error response returned when a request fails.
Contains a machine-readable error code, a human-readable message.
content:
application/json:
schema:
type: object
properties:
errorCode:
type: string
example: "SERVER_ERROR"
description: A system error code to identify the issue. Can be used by your system to detect what went wrong.
message:
type: string
example: "An unexpected system error"
description: Contains a human readable explanation of the error code. Any situational detail is appended to the end of the description.
ValidationErrorResponse:
description: |
Standard error response returned when a request fails.
Contains a machine-readable error code, a human-readable message,
and an `errors` object with field-specific validation issues.
content:
application/json:
schema:
type: object
properties:
errorCode:
type: string
description: Machine-readable error code indicating the type of error.
example: VALIDATION_ERROR
message:
type: string
description: Human-readable description of the error.
example: Input validation errors
errors:
type: object
description: |
Object where each key corresponds to the name of an invalid field.
Each value is an array of strings, where each string describes
a specific validation issue for that field.
additionalProperties:
type: array
items:
type: string
example:
amount:
- "[required]: Is a required non-nullable field"
- "[int]: Must be an integer"
- "[min:0]: Must be greater than 0"
- "[max:999999999]: Must be less than 999999999"
required:
- errorCode
- message
schemas:
Account:
type: object
properties:
id:
type: string
format: uuid
example: 019a0abe-f093-72c7-9f89-be4e48b9e01e
description: The primary id of the merchant account
name:
type: string
description: The name of the account
addressLineOne:
type: string
nullable: true
description: The address line of the merchant
addressLineTwo:
type: string
nullable: true
description: The address line of the merchant
city:
type: string
nullable: true
description: The city of the merchant
postalCode:
type: string
nullable: true
description: The postal code of the merchant
countryCode:
type: string
nullable: true
description: The country code of the merchant
phone:
type: string
nullable: true
description: The primary contact number of the merchant
email:
type: string
nullable: true
description: The primary contact email of the merchant
timezone:
type: string
nullable: true
description: The primary timezone of the merchant
invoiceEmail:
type: string
nullable: true
description: The email used when sending invoices.
invoiceAttention:
type: string
nullable: true
description: The receiver name of the invoice email.
vat:
type: string
nullable: true
description: The VAT number of the merchant
currencyCode:
type: string
nullable: true
description: The primary currency code of the merchant
status:
type: string
description: The current status of the merchant account
createdAt:
type: string
format: date-time
description: The merchant account creation time
AccountsListResponse:
allOf:
- $ref: "#/components/schemas/PaginatedResponse"
- type: object
properties:
items:
type: array
description: The page contents
items:
type: object
properties:
account:
$ref: "#/components/schemas/Account"
CreateApiKeyRequest:
type: object
required: [name]
properties:
name:
description: A display name for the API key visible in the ePay backoffice. This can be used to indicate the reason or usage of the API key.
type: string
example: My Name
CreateApiKeyResponse:
type: object
properties:
name:
type: string
example: My Name
description: A display name for the API key visible in the ePay backoffice. This can be used to indicate the reason or usage of the API key.
key:
type: string
example: test_13cfbcbf-fd20-4dc5-9b16-209f6c708119
description: The API key. Keys starting with `test_` is for the test environment and keys starting with `live_` is for the live environment.
CreatePartnerAccountRequest:
type: object
required: [name, email, currencyCode, timezone, domain]
properties:
name:
type: string
example: Merchant Name
description: The name of the merchant. This is typically the company name or the name of the merchant domain or app.
email:
type: string
format: email
example: owner@merchant.dk
description: The email address of the merchant account owner. This email will automatically be invited to join the created merchant account and granted ownership privileges.
currencyCode:
type: string
example: DKK
description: The primary currency of the merchant. Alpha-3.
language:
type: string
example: da
description: The primary language of the merchant. ISO 639.
timezone:
type: string
example: Europe/Copenhagen
description: The primary timezone of the merchant.
domain:
type: string
example: merchant.dk
description: The primary domain used by the merchant. This should be the URL that purchases are expected to take place from.
CreatePartnerAccountResponse:
type: object
properties:
account:
$ref: "#/components/schemas/Account"
ShowPartnerAccountResponse:
type: object
properties:
account:
$ref: "#/components/schemas/Account"
CreatePartnerAccessTokenRequest:
type: object
required: [environment]
properties:
environment:
description: The environment for which to create an access token. This can be either `test` or `live`. The created access token will only have access to the respective environment for the merchant account.
type: string
enum: [test, live]
example: live
CreatePartnerAccessTokenResponse:
type: object
properties:
expiresAt:
description: The time at which the access token expires. It is recommended to create a new access token before the current one expires to avoid inflight clock skew issues.
type: string
format: date-time
example: 2030-07-29T15:51:28.071Z
accessToken:
description: A JWT access token granting access to the merchant account for either the live or test environment. As a partner you can send this access token instead of a merchant API key, when accessing the ePay API on behalf of the merchant.
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0N...
Processor:
type: string
description: |
Identifier of a payment processor.
This value determines which payment gateway(s) are used to process a payment.
enum:
- shift4
- clearhaus
- nets
- worldline
PaymentMethodType:
type: string
example: "CARD"
description: The type of the payment method.
enum:
- CARD
- VIPPS_MOBILEPAY
- MOBILEPAY_ONLINE
- APPLE_PAY
- GOOGLE_PAY
- SWISH
- VIABILL
- ANYDAY
MitAuthorizationRequest:
type: object
properties:
subscriptionId:
type: string
format: uuid
description: The ID of the subscription to charge
example: "01929a94-5fce-7ccc-a7e4-7e9249133b39"
amount:
type: integer
description: Amount in minor units (e.g., 1095 = 10.95 DKK)
example: 100
currency:
pattern: ^[A-Z]{3}$
type: string
description: The currency of the transaction. If set to null, then the same currency as the subscription was created for will be used.
nullable: true
example: "DKK"
reference:
type: string
example: "subscription-charge-1"
description: The merchant reference for the payment. This is typically used for the order id.
instantCapture:
type: string
example: "OFF"
description: "If the payment should be captured instantly or not.All URL properties support dynamic templating with session and transaction data, allowing merchants to define URLs that include ePay-generated resource ID's.
This feature can be particularly helpful for some merchants, especially with success and failure URLs, as it simplifies fetching order information upon transaction completion.
Unknown template keys will be rejected during request validation.
- `${transaction.id}`: The primary id of the associated transaction. - `${transaction.reference}`: The merchant supplied reference from session init. - `${session.id}`: The primary id of the associated session. - `${subscription.id}`: The primary id of the associated subscription.