openapi: 3.0.1
info:
title: Scalapay API
description: Interact with Scalapay.
version: '3.0'
servers:
- url: https://integration.api.scalapay.com
description: Sandbox server that uses test data. Use this server for testing purposes.
- url: https://api.scalapay.com
description: Production server that uses live data.
security:
- ApiKeyAuth: []
x-samples-enabled: true
x-explorer-enabled: true
paths:
/v1/instore/orders:
post:
tags:
- Instore
summary: Create instore order
description: Create an instore order and charge the customer. Use the correct Bearer token for authentication.
security:
- InstoreApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- merchantOperatorId
- merchantReference
- preApprovalCode
- requestId
- totalAmount
- items
properties:
totalAmount:
$ref: '#/components/schemas/amount'
preApprovalCode:
type: string
description: Barcode presented by the customer. It is the code shown to the cashier for payment.
requestId:
type: string
description: Unique identifier for the v2/instore/orders request from the POS system. It is available in
your merchant dashboard.
merchantOperatorId:
type: string
description: String identifier of the POS operator, such as an employee ID or name.
items:
$ref: '#/components/schemas/items'
merchantReference:
$ref: '#/components/schemas/merchantReference'
example:
merchantOperatorId: Test Integration
requestId: EKMXO6QFN
preApprovalCode: '85633887'
totalAmount:
amount: '10.00'
currency: EUR
items:
- name: T-Shirt
category: clothes
subcategory:
- shirt
- long-sleeve
brand: TopChoice
gtin: '123458791330'
sku: '12341234'
quantity: 1
price:
amount: '10.00'
currency: EUR
- name: Jeans
category: clothes
subcategory:
- pants
- jeans
brand: TopChoice
gtin: '123458722222'
sku: '12341235'
quantity: 1
price:
amount: '20.00'
currency: EUR
merchantReference: merchantOrder-1234
responses:
'200':
description: Instore order created successfully.
content:
application/json:
example:
requestId: EKMXO6QFN
token: 769DKMXOC52H
status: charged
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
/v1/instore/orders/references:
get:
tags:
- Instore
summary: Get instore orders by reference
description: 'Retrieve a list of instore order references based on one or more known reference values. At least one
query parameter must be provided. Multiple parameters are combined with AND logic.
The endpoint returns a maximum of 100 matching orders, sorted by creation date (newest first).
'
security:
- InstoreApiKeyAuth: []
parameters:
- name: orderToken
in: query
required: false
style: form
explode: false
schema:
type: string
minLength: 1
description: Order token to search for.
example: 769DKMXOC52H
- name: merchantOrderReference
in: query
required: false
style: form
explode: false
schema:
type: string
minLength: 1
description: Merchant reference to search for.
example: merchantOrder-1234
- name: merchantProcessorReference
in: query
required: false
style: form
explode: false
schema:
type: string
minLength: 1
description: Merchant processor reference to search for.
example: processor-ref-5678
responses:
'200':
description: Instore orders retrieved successfully.
content:
application/json:
schema:
type: array
items:
type: object
properties:
orderToken:
type: string
description: Order token.
merchantOrderReference:
type: string
description: Merchant reference.
merchantProcessorReference:
type: string
description: Merchant processor reference.
createdAt:
type: string
format: date-time
description: Order creation timestamp.
example:
- orderToken: 769DKMXOC52H
merchantOrderReference: merchantOrder-1234
merchantProcessorReference: processor-ref-5678
createdAt: '2024-11-08T11:26:17.000Z'
- orderToken: 769DKMXOC51H
merchantOrderReference: merchantOrder-1234
merchantProcessorReference: null
createdAt: '2024-11-07T09:15:32.000Z'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
/v1/instore/orders/{token}:
get:
tags:
- Instore
summary: Get an instore order
description: Retrieve the status of an instore order.
security:
- InstoreApiKeyAuth: []
parameters:
- name: token
in: path
required: true
style: simple
explode: false
schema:
type: string
format: string
minimum: 1
description: Order token.
responses:
'200':
description: Instore order retrieved successfully.
content:
application/json:
examples:
charged:
summary: Charged order
value:
token: 769DKMXOC52H
status: charged
expired:
summary: Expired order with eligibility feedback
value:
token: 82LJ027WQF
status: expired
lastEligibilityFeedback: DECLINED_FRAUD
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
/v1/instore/orders/{token}/refund:
post:
tags:
- Instore
summary: Refund an instore order
description: Refund an instore order. The refund is processed and funds are transferred back to the customer.
security:
- InstoreApiKeyAuth: []
parameters:
- name: token
in: path
required: true
style: simple
explode: false
schema:
type: string
format: string
minimum: 1
description: Order token.
example: 71KH916VPE
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- merchantOperatorId
- refundAmount
- requestId
properties:
requestId:
type: string
description: Unique identifier for the refund request.
merchantOperatorId:
type: string
description: Identifier of the POS operator.
refundAmount:
allOf:
- $ref: '#/components/schemas/amount'
description: Refund amount.
example:
merchantOperatorId: Test Integration
requestId: EKMXO6QFN
refundAmount:
amount: '10.00'
currency: EUR
responses:
'200':
description: Instore order refunded successfully.
content:
application/json:
example:
merchantOperatorId: Test Integration
requestId: EKMXO6QFN
refundAmount:
amount: 10
currency: EUR
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
/v1/reporting/disputes:
get:
tags:
- Reporting
summary: Get disputes
description: Retrieves a paginated list of disputes for reporting purposes with filtering options.
parameters:
- name: startDate
in: query
required: true
style: form
explode: false
schema:
type: string
format: date
description: ISO 8601 date string for filtering disputes from this date.
- name: endDate
in: query
required: true
style: form
explode: false
schema:
type: string
format: date
description: ISO 8601 date string for filtering disputes to this date.
- name: disputeStatus
in: query
required: false
style: form
explode: false
schema:
type: string
enum:
- open
- processing
- won
- lost
- closed
description: Filter by dispute status.
- name: page
in: query
required: false
style: form
explode: false
schema:
type: integer
minimum: 0
default: 0
description: Page number, zero-based (default 0).
- name: size
in: query
required: false
style: form
explode: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Number of items per page (default 20, max 100).
responses:
'200':
description: Disputes retrieved successfully.
content:
application/json:
schema:
type: object
required:
- items
- total
- page
- size
- hasMore
properties:
items:
type: array
items:
type: object
required:
- disputeToken
- orderToken
- disputeStatus
- amountInCents
- currency
- openingReason
- createdAt
- expiresAt
properties:
disputeToken:
type: string
description: Unique dispute identifier
orderToken:
type: string
description: Token of the associated order
merchantOrderReference:
type: string
nullable: true
description: Merchant's order reference
merchantDisputeReference:
type: string
nullable: true
description: Merchant's internal reference
disputeStatus:
type: string
enum:
- open
- processing
- won
- lost
- closed
description: Dispute status
openingReason:
type: string
enum:
- credit_not_processed
- duplicate
- fraudulent
- general
- product_not_received
- product_unacceptable
- subscription_canceled
- unrecognized_payment
description: Reason dispute was opened
resolvingReason:
type: string
nullable: true
enum:
- customer_canceled
- evidence_accepted
- evidence_deadline_expired
- evidence_rejected
- merchant_accepted
- resolution_deadline_expired
description: How dispute was resolved
amountInCents:
type: integer
description: Disputed amount in cents
currency:
type: string
description: Currency code
liability:
type: string
nullable: true
enum:
- pending
- merchant
- scalapay
description: Indicates who bears liability for the dispute
createdAt:
type: string
format: date-time
description: ISO 8601 datetime when dispute was created
expiresAt:
type: string
format: date-time
description: ISO 8601 datetime when dispute expires
updatedAt:
type: string
format: date-time
nullable: true
description: ISO 8601 datetime of last update
resolvedAt:
type: string
format: date-time
nullable: true
description: ISO 8601 datetime when resolved
total:
type: integer
description: Total number of disputes matching filters
page:
type: integer
description: Current page number (zero-based)
size:
type: integer
description: Number of items per page
hasMore:
type: boolean
description: Whether there are more pages available
example:
items:
- disputeToken: MOD123
orderToken: ORD123
merchantOrderReference: ORDER-2025-001
merchantDisputeReference: DISP-2025-DEF
disputeStatus: open
openingReason: credit_not_processed
amountInCents: 5000
currency: EUR
liability: null
resolvingReason: null
createdAt: '2025-08-18T10:30:00.000Z'
expiresAt: '2025-08-25T10:30:00.000Z'
updatedAt: '2025-08-18T10:30:00.000Z'
resolvedAt: null
- disputeToken: MOD456
orderToken: ORD456
merchantOrderReference: ORDER-2025-002
merchantDisputeReference: DISP-2025-LTE
disputeStatus: won
openingReason: credit_not_processed
amountInCents: 5000
currency: EUR
liability: merchant
resolvingReason: evidence_accepted
createdAt: '2025-08-18T10:30:00.000Z'
expiresAt: '2025-08-25T10:30:00.000Z'
updatedAt: '2025-08-18T10:30:00.000Z'
resolvedAt: '2025-08-19T10:30:00.000Z'
total: 2
page: 0
size: 20
hasMore: false
'400':
description: Bad request. (HTTP 400).
content:
application/json:
example:
errorCode: pre_condition_failed
errorId: error-19g6il4h3evp0
httpStatusCode: 400
'401':
$ref: '#/components/responses/401Error'
'500':
description: Internal server error. (HTTP 500).
content:
application/json:
example:
errorCode: internal_server
errorId: error-59k0mqmzmrs77
httpStatusCode: 500
/v1/reporting/orders:
get:
tags:
- Reporting
summary: Get orders
description: Retrieve orders. This endpoint enables merchants to reconcile bank transactions with orders and refunds
within the Scalapay platform. Use the Scalapay API key Bearer token to access this endpoint.
parameters:
- name: startDate
in: query
required: false
style: form
explode: false
schema:
type: string
format: string
minimum: 1
description: 'Start date for bank transactions in "YYYY-MM-DD" format. (Default: today).'
- name: endDate
in: query
required: false
style: form
explode: false
schema:
type: string
format: string
minimum: 1
description: 'End date for bank transactions in "YYYY-MM-DD" format. (Default: today).'
- name: size
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
maximum: 5000
default: 5000
description: 'Number of items returned (default: 5000).'
- name: page
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
default: 0
description: 'Page to show (default: 0).'
responses:
'200':
description: Orders retrieved successfully.
content:
application/json:
example: '{"items":[{"storeReference":null,"deviceReference":null,"orderStatus":"charged","orderTokenLast4":"******AYPA","orderCreatedDate":"2022-05-26T15:28:53.000","channel":null,"type":"online","product":"pay-in-3","merchantReference":"merchantOrder-1234","captureStatus":"captured","captureAmount":{"amount":"10.00","currency":"EUR"},"transferId":"tr_1L3ZJ6FHjEtCWkTsJqGDRYXZ","payoutDetails":{"merchantPayoutToken":"3BQD2I26MRG3","transactionDate":"2022-05-27T11:19:52.000","status":"processed","grossAmount":{"currency":"EUR","amount":"10.00"},"netAmount":{"currency":"EUR","amount":"10.00"},"totalFeeAmount":{"currency":"EUR","amount":"0.98"},"scalapayFeeAmount":{"currency":"EUR","amount":"0.80"},"scalapayFeeTaxAmount":{"currency":"EUR","amount":"0.18"},"otherFeeAmount":{"currency":"EUR","amount":"0.00"},"otherFeeTaxAmount":{"currency":"EUR","amount":"0.00"}}},{"storeReference":null,"deviceReference":null,"orderStatus":"authorized","orderTokenLast4":"******FH4R","orderCreatedDate":"2022-06-13T20:50:35.000","channel":null,"type":"online","product":"pay-in-3","merchantReference":"OjbKlbnuMNMlN9j_g9dqdIhh","captureStatus":"delayed","captureAmount":{"amount":"0.00","currency":"EUR"},"transferId":null,"payoutDetails":null},{"storeReference":null,"deviceReference":null,"orderStatus":"expired","orderTokenLast4":"******T9KP","orderCreatedDate":"2022-07-01T10:15:22.000","channel":null,"type":"online","product":"pay-in-3","merchantReference":"merchantOrder-5678","captureStatus":"voided","captureAmount":{"amount":"0.00","currency":"EUR"},"transferId":null,"payoutDetails":null}],"total":3,"page":0,"size":5000,"hasMore":false}
'
'400':
description: Bad request. (HTTP 400).
content:
application/json:
example: '{"errorCode": "pre_condition_failed","errorId": "error-19g6il4h3evp0","message": "startDate cannot
be greater than endDate","httpStatusCode": 400}
'
'401':
$ref: '#/components/responses/401Error'
/v1/reporting/payouts:
get:
tags:
- Reporting
summary: Get payouts
description: Retrieve payouts. This endpoint provides a list of all payouts received from Scalapay. Use the Scalapay
API key Bearer token to access this endpoint.
parameters:
- name: startDate
in: query
required: false
style: form
explode: false
schema:
type: string
format: string
minimum: 1
description: 'Start date for bank transactions in "YYYY-MM-DD" format. (Default: today).'
- name: endDate
in: query
required: false
style: form
explode: false
schema:
type: string
format: string
minimum: 1
description: 'End date for bank transactions in "YYYY-MM-DD" format. (Default: today).'
- name: size
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
maximum: 5000
default: 5000
description: 'Number of items returned (default: 5000).'
- name: page
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
default: 0
description: 'Page to show (default: 0).'
responses:
'200':
description: Payouts retrieved successfully.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
merchantPayoutToken:
type: string
description: Merchant payout token.
transactionDate:
type: string
description: Transaction date.
totalAmount:
type: object
description: Total amount of the payout.
status:
type: string
description: Payout status.
example: '{"items":[{"merchantPayoutToken":"FELGDH3XJDRS","transactionDate":"2022-05-26T11:29:55.000","totalAmount":{"amount":"26080.02","currency":"EUR"},"status":"processed"},{"merchantPayoutToken":"3BQD2I26MRG3","transactionDate":"2022-05-27T11:19:52.000","totalAmount":{"amount":"24188.61","currency":"EUR"},"status":"processed"}],"total":2,"page":0,"size":5000,"hasMore":false}
'
'400':
description: Bad request. (HTTP 400).
content:
application/json:
example: '{"errorCode": "pre_condition_failed","errorId": "error-19g6il4h3evp0","message": "startDate cannot
be greater than endDate","httpStatusCode": 400}
'
'401':
$ref: '#/components/responses/401Error'
/v1/reporting/payouts/{token}/orders:
get:
tags:
- Reporting
summary: Get orders from payout
description: Retrieve orders from a payout. This endpoint provides a list of orders associated with a specific payout.
Use the Scalapay API key Bearer token to access this endpoint.
parameters:
- name: token
in: path
required: true
style: simple
explode: false
schema:
type: string
format: string
minimum: 1
description: Payout token.
example: 3BQD2I26MRG3
- name: size
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
maximum: 5000
default: 5000
description: 'Number of items returned (default: 5000).'
- name: page
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
default: 0
description: 'Page to show (default: 0).'
responses:
'200':
description: Orders from payout retrieved successfully.
content:
application/json:
example: '{"items":[{"orderStatus":"charged","orderTokenLast4":"******AYPA","orderCreatedDate":"2022-05-26T15:28:53.000","channel":null,"type":"online","product":"pay-in-3","merchantReference":"merchantOrder-1234","captureStatus":"captured","captureAmount":{"amount":"10.00","currency":"EUR"},"transferId":"tr_1L3ZJ6FHjEtCWkTsJqGDRYXZ","details":{"storeReference":null,"deviceReference":null,"grossAmount":{"currency":"EUR","amount":"10.00"},"netAmount":{"currency":"EUR","amount":"10.00"},"totalFeeAmount":{"currency":"EUR","amount":"0.98"},"scalapayFeeAmount":{"currency":"EUR","amount":"0.80"},"scalapayFeeTaxAmount":{"currency":"EUR","amount":"0.18"},"otherFeeAmount":{"currency":"EUR","amount":"0.00"},"otherFeeTaxAmount":{"currency":"EUR","amount":"0.00"}}},{"orderStatus":"charged","orderTokenLast4":"******YKNN","orderCreatedDate":"2022-05-26T16:12:49.000","channel":null,"type":"online","product":"pay-in-3","merchantReference":"merchantOrder-1234","captureStatus":"captured","captureAmount":{"amount":"10.00","currency":"EUR"},"transferId":"tr_1L3ZwoFHjEtCWkTsMyDuEAm4","details":{"storeReference":null,"deviceReference":null,"grossAmount":{"currency":"EUR","amount":"10.00"},"netAmount":{"currency":"EUR","amount":"10.00"},"totalFeeAmount":{"currency":"EUR","amount":"0.98"},"scalapayFeeAmount":{"currency":"EUR","amount":"0.80"},"scalapayFeeTaxAmount":{"currency":"EUR","amount":"0.18"},"otherFeeAmount":{"currency":"EUR","amount":"0.00"},"otherFeeTaxAmount":{"currency":"EUR","amount":"0.00"}}}],"total":2,"page":0,"size":5000,"hasMore":false}
'
'400':
description: Bad request. (HTTP 400).
content:
application/json:
example: '{"errorCode":"pre_condition_failed","errorId":"error-19g6il4h6tr5l","message":"an invalidmerchant
PayoutToken was provided","httpStatusCode":400}
'
'401':
$ref: '#/components/responses/401Error'
/v1/reporting/payouts/{token}/refunds:
get:
tags:
- Reporting
summary: Get refunds from payout
description: Retrieve refunds from a payout. This endpoint provides a list of refunds associated with a specific payout.
Use the Scalapay API key Bearer token to access this endpoint.
parameters:
- name: token
in: path
required: true
style: simple
explode: false
schema:
type: string
format: string
minimum: 1
description: Payout token.
example: NRF55213PDYK
- name: size
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
maximum: 5000
default: 5000
description: 'Number of items returned (default: 5000).'
- name: page
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
default: 0
description: 'Page to show (default: 0).'
responses:
'200':
description: Refunds from payout retrieved successfully.
content:
application/json:
example: '{"items":[{"orderTokenLast4":"******TNV9","merchantReference":"merchantOrder-1234","refundAmount":{"amount":"20.00","currency":"EUR"},"transferId":"trr_1L5M7hFHjEtCWkTsWAIDNuta","details":{"grossAmount":{"amount":"20.00","currency":"EUR"},"netAmount":{"amount":"20.00","currency":"EUR"},"totalFeeAmount":{"amount":"-1.22","currency":"EUR"},"scalapayFeeAmount":{"amount":"-1.00","currency":"EUR"},"scalapayFeeTaxAmount":{"amount":"-0.22","currency":"EUR"},"otherFeeAmount":{"amount":"0.00","currency":"EUR"},"otherFeeTaxAmount":{"amount":"0.00","currency":"EUR"}}},{"orderTokenLast4":"******JHP2","merchantReference":"merchantOrder-1234","refundAmount":{"amount":"20.00","currency":"EUR"},"transferId":"trr_1L5M90FHjEtCWkTsoyHuImNL","details":{"grossAmount":{"amount":"20.00","currency":"EUR"},"netAmount":{"amount":"20.00","currency":"EUR"},"totalFeeAmount":{"amount":"-1.22","currency":"EUR"},"scalapayFeeAmount":{"amount":"-1.00","currency":"EUR"},"scalapayFeeTaxAmount":{"amount":"-0.22","currency":"EUR"},"otherFeeAmount":{"amount":"0.00","currency":"EUR"},"otherFeeTaxAmount":{"amount":"0.00","currency":"EUR"}}}],"total":2,"page":0,"size":500,"hasMore":false}
'
'400':
description: Bad request. (HTTP 400).
content:
application/json:
example: '{"errorCode":"pre_condition_failed","errorId":"error-19g6il4h6tr5l","message":"an invalidmerchant
PayoutToken was provided","httpStatusCode":400}
'
'401':
$ref: '#/components/responses/401Error'
/v1/reporting/refunds:
get:
tags:
- Reporting
summary: Get refunds
description: Retrieve refunds. This endpoint enables merchants to reconcile bank transactions with orders and refunds
within the Scalapay platform. Use the Scalapay API key Bearer token to access this endpoint.
parameters:
- name: startDate
in: query
required: false
style: form
explode: false
schema:
type: string
format: string
minimum: 1
description: 'Start date for bank transactions in "YYYY-MM-DD" format. (Default: today).'
- name: endDate
in: query
required: false
style: form
explode: false
schema:
type: string
format: string
minimum: 1
description: 'End date for bank transactions in "YYYY-MM-DD" format. (Default: today).'
- name: size
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
maximum: 5000
default: 5000
description: 'Number of items returned (default: 5000).'
- name: page
in: query
required: false
style: form
explode: false
schema:
type: integer
format: integer
minimum: 0
default: 0
description: 'Page to show (default: 0).'
responses:
'200':
description: Refunds retrieved successfully.
content:
application/json:
example: '{"items":[{"storeReference":null,"deviceReference":null,"orderStatus":"charged","orderTokenLast4":"******AYPA","orderCreatedDate":"2022-05-26T15:28:53.000","channel":null,"type":"online","product":"pay-in-3","merchantReference":"merchantOrder-1234","captureStatus":"captured","captureAmount":{"amount":"10.00","currency":"EUR"},"transferId":"tr_1L3ZJ6FHjEtCWkTsJqGDRYXZ","payoutDetails":{"merchantPayoutToken":"3BQD2I26MRG3","transactionDate":"2022-05-27T11:19:52.000","status":"processed","grossAmount":{"currency":"EUR","amount":"10.00"},"netAmount":{"currency":"EUR","am
# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/scalapay/refs/heads/main/openapi/scalapay-openapi-original.yml