The Orders API from Scalapay — 8 operation(s) for orders.
openapi: 3.2.0
info:
title: Scalapay Orders 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: []
tags:
- name: Orders
paths:
/v2/orders:
post:
tags:
- Orders
summary: Create order
description: Create a Scalapay order. The endpoint returns a `token` required to capture the payment and a `checkoutUrl` that redirects the customer to Scalapay Checkout, where the payment is authorized.
parameters:
- name: Idempotency-Key
in: header
description: Idempotency key used for retrying requests. Can be used for retrying failed requests.
required: false
schema:
type: string
requestBody:
required: true
description: 'Request body must be JSON (Content-Type: application/json). Responses are always JSON.'
content:
application/json:
schema:
type: object
required:
- consumer
- items
- merchant
- shipping
- totalAmount
properties:
totalAmount:
allOf:
- $ref: '#/components/schemas/amount'
description: Total amount of the order.
consumer:
type: object
required:
- phoneNumber
- givenNames
- surname
- email
description: Consumer information.
properties:
phoneNumber:
type: string
description: Customer phone number with country code.
givenNames:
type: string
description: Consumer first name.
surname:
type: string
description: Consumer last name.
email:
type: string
description: Consumer email address.
billing:
allOf:
- $ref: '#/components/schemas/address'
description: Customer billing address.
shipping:
allOf:
- $ref: '#/components/schemas/address'
required:
- phoneNumber
- countryCode
- name
- postcode
- suburb
- line1
description: Customer shipping address.
items:
allOf:
- $ref: '#/components/schemas/items'
description: Items purchased by the consumer.
discounts:
type: array
description: Discounts applied to the order.
items:
type: object
properties:
amount:
$ref: '#/components/schemas/amount'
displayName:
type: string
description: Display name of the discount.
merchant:
type: object
required:
- redirectCancelUrl
- redirectConfirmUrl
description: Redirection URLs for completing the payment.
properties:
redirectCancelUrl:
type: string
description: Use https://portal.integration.scalapay.com/failure-url for testing.
redirectConfirmUrl:
type: string
description: Use https://portal.integration.scalapay.com/success-url for testing.
merchantReference:
$ref: '#/components/schemas/merchantReference'
shippingAmount:
allOf:
- $ref: '#/components/schemas/amount'
description: Shipping amount.
taxAmount:
allOf:
- $ref: '#/components/schemas/amount'
description: Tax amount.
type:
type: string
enum:
- ''
- online
- offline
- link
example: online
description: Type of order. Use `online` for online orders, `offline` for offline orders, and `link` for orders sent by SMS. When using `link`, include the extensions field.
product:
type: string
enum:
- ''
- pay-in-3
- pay-in-4
- later
description: Product type. Could be empty. Use `pay-in-3` for pay in 3, `pay-in-4` for pay in 4, and `later` for pay later.
frequency:
type: object
description: Specify the frequency of the payment. This is useful for pay later products. Do not include when using pay-in-3 or pay-in-4.
properties:
number:
type: integer
example: 1
frequencyType:
type: string
example: monthly
orderExpiryMilliseconds:
type: integer
example: 2400000
description: Length of time (in milliseconds) that the order is valid. The maximum value is determined by your Scalapay contract. To extend it, contact Scalapay support.
extensions:
$ref: '#/components/schemas/extensions'
examples:
Order:
$ref: '#/components/examples/CreateOrderExample'
Pay by link:
$ref: '#/components/examples/CreatePayByLinkExample'
responses:
'200':
description: Successful order creation
content:
application/json:
schema:
type: object
required:
- token
properties:
token:
type: string
description: The order token used to capture the payment.
expires:
type: string
description: Expiry timestamp of the order.
checkoutUrl:
type: string
description: URL that redirects the customer to Scalapay Checkout.
example:
token: 71KH916VPE
expires: '2024-11-08T13:06:17.858Z'
checkoutUrl: https://portal.scalapay.com/checkout/71KH916VPE
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'409':
$ref: '#/components/responses/409Error'
/v2/orders/{token}:
post:
tags:
- Orders
summary: Update order
description: Update an order by changing the `merchantReference`. Use this endpoint when specifying the `merchantReference` during order creation was not possible.
parameters:
- name: token
in: path
required: true
style: simple
explode: false
schema:
type: string
format: string
description: Order token.
- name: Idempotency-Key
in: header
description: Idempotency key used for retrying requests. Can be used for retrying failed requests.
required: false
schema:
type: string
requestBody:
required: true
description: 'Request body must be JSON (Content-Type: application/json). Responses are always JSON.'
content:
application/json:
schema:
type: object
properties:
merchantReference:
type: string
minLength: 1
description: Merchant reference for tracking the order in your system. Omit the field to remove the value.
merchantProcessorReference:
type: string
minLength: 1
description: Merchant processor reference for tracking the order in your system.
example:
merchantReference: merchantOrder-1234
merchantProcessorReference: processorOrder-1234
responses:
'200':
description: Order updated successfully
headers:
Request-Idempotency:
schema:
type: string
enum:
- 'true'
description: Present when the response was served from the idempotency cache.
required: false
content:
application/json:
schema:
type: object
required:
- token
properties:
token:
type: string
description: The order token that was updated.
merchantReference:
type: string
description: The updated merchant reference, returned if provided in the request.
merchantProcessorReference:
type: string
description: The updated merchant processor reference, returned if provided in the request.
example:
token: 71KH916VPE
merchantReference: merchantOrder-1234
merchantProcessorReference: processorOrder-1234
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'409':
$ref: '#/components/responses/409Error'
/v2/payments/capture:
post:
tags:
- Orders
summary: Capture order
description: Capture the payment associated with the order. The specified amount is deducted from the user's account and transferred to the merchant's account. You can capture an amount up to the total specified during order creation. You may also provide an updated `merchantReference` to update the order.
parameters:
- name: Idempotency-Key
in: header
description: Idempotency key used for retrying requests. Can be used for retrying failed requests.
required: false
schema:
type: string
requestBody:
required: true
description: 'Request body must be JSON (Content-Type: application/json). Responses are always JSON.'
content:
application/json:
schema:
title: amount
type: object
required:
- token
properties:
token:
type: string
description: Order token.
merchantReference:
$ref: '#/components/schemas/merchantReference'
amount:
allOf:
- $ref: '#/components/schemas/amount'
description: Amount to capture.
example:
token: 71KH916VPE
merchantReference: merchantOrder-updated
amount:
amount: 190,00
currency: EUR
responses:
'200':
description: Payment captured successfully
headers:
Request-Idempotency:
schema:
type: string
enum:
- 'true'
description: Present when the response was served from the idempotency cache.
required: false
content:
application/json:
schema:
type: object
required:
- token
- status
properties:
token:
type: string
description: The order token.
status:
type: string
description: The status of the capture.
totalAmount:
type: object
description: The total amount captured.
properties:
amount:
type: string
description: The amount value.
currency:
type: string
description: The currency code (ISO 4217).
orderDetails:
type: object
description: The full order details.
capturedAt:
type: string
description: The date and time when the capture was processed.
example:
token: 71KH916VPE
status: APPROVED
totalAmount:
currency: EUR
amount: '190.00'
orderDetails:
items:
- sku: '12341234'
gtin: '123458791330'
name: T-Shirt
brand: TopChoice
price:
amount: '10.00'
currency: EUR
category: clothes
quantity: 1
subcategory:
- shirt
- long-sleeve
- sku: '12341235'
gtin: '123458722222'
name: Jeans
brand: TopChoice
price:
amount: '20.00'
currency: EUR
category: clothes
quantity: 1
subcategory:
- pants
- jeans
billing:
name: Mario Rossi
line1: Via Puglia, 58
suburb: Castelfranco Veneto
postcode: '31033'
countryCode: IT
phoneNumber: '393001234567'
consumer:
email: test@scalapay.com
surname: Consumer
givenNames: Joe
phoneNumber: '0400000001'
merchant:
redirectCancelUrl: https://integration.api.scalapay.com/failure-url
redirectConfirmUrl: https://integration.api.scalapay.com/success-url
shipping:
name: Mario Rossi
line1: Via Puglia, 58
suburb: Castelfranco Veneto
postcode: '31033'
countryCode: IT
phoneNumber: '393001234567'
discounts:
- amount:
amount: '3.00'
currency: EUR
displayName: 10% Off
taxAmount:
amount: '3.70'
currency: EUR
totalAmount:
amount: '190.00'
currency: EUR
shippingAmount:
amount: '10.00'
currency: EUR
merchantReference: merchantOrder-1234-updated
capturedAt: '2023-10-19T15:11:20.000Z'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'409':
$ref: '#/components/responses/409Error'
/v2/payments/references:
get:
tags:
- Orders
summary: Get orders by reference
description: 'Retrieve a list of 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).
'
parameters:
- name: orderToken
in: query
required: false
style: form
explode: false
schema:
type: string
minLength: 1
description: Order token to search for.
example: 71KH916VPE
- 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: 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: 71KH916VPE
merchantOrderReference: merchantOrder-1234
merchantProcessorReference: processor-ref-5678
createdAt: '2024-11-08T11:26:17.000Z'
- orderToken: 71KH916VPD
merchantOrderReference: merchantOrder-1234
merchantProcessorReference: null
createdAt: '2024-11-07T09:15:32.000Z'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
/v2/payments/{token}:
get:
tags:
- Orders
summary: Get order details
description: Return all details regarding the specified order.
parameters:
- name: token
in: path
required: true
style: simple
explode: false
schema:
type: string
format: string
minimum: 1
description: Order token.
example: 71KH916VPE
responses:
'200':
description: Order details retrieved successfully.
content:
application/json:
examples:
charged:
summary: Charged order
value:
token: 71KH916VPE
created: '2024-11-08T11:26:17.000Z'
status: charged
captureStatus: captured
totalAmount:
amount: '190.00'
currency: EUR
orderDetails:
items:
- sku: '12341234'
gtin: '123458791330'
name: T-Shirt
brand: TopChoice
price:
amount: '10.00'
currency: EUR
category: clothes
quantity: 1
subcategory:
- shirt
- long-sleeve
- sku: '12341235'
gtin: '123458722222'
name: Jeans
brand: TopChoice
price:
amount: '20.00'
currency: EUR
category: clothes
quantity: 1
subcategory:
- pants
- jeans
billing:
name: Mario Rossi
line1: Via Piglia, 58
suburb: Castelfranco Veneto
postcode: '31033'
countryCode: IT
phoneNumber: '393001234567'
consumer:
email: test@scalapay.com
surname: Consumer
givenNames: Joe
phoneNumber: '393001234567'
merchant:
redirectCancelUrl: https://integration.api.scalapay.com/failure-url
redirectConfirmUrl: https://integration.api.scalapay.com/success-url
shipping:
name: Mario Rossi
line1: Via Puglia, 58
suburb: Castelfranco Veneto
geoCode:
place_id: VklBK0RFTExBK1JPU0ErNTgrLE1PTlRFTFVQTytGSU9SRU5USU5PLDUwMDU2LElU
postcode: '31033'
countryCode: IT
phoneNumber: '393001234567'
discounts:
- amount:
amount: '3.00'
currency: EUR
displayName: 10% Off
taxAmount:
amount: '3.70'
currency: EUR
totalAmount:
amount: '190.00'
currency: EUR
shippingAmount:
amount: '10.00'
currency: EUR
merchantReference: merchantOrder-1234-updated
expired:
summary: Expired order with eligibility feedback
value:
token: 82LJ027WQF
created: '2024-11-08T11:26:17.000Z'
status: expired
captureStatus: pending
lastEligibilityFeedback: DECLINED_FRAUD
totalAmount:
amount: '190.00'
currency: EUR
orderDetails:
items:
- sku: '12341234'
gtin: '123458791330'
name: T-Shirt
brand: TopChoice
price:
amount: '10.00'
currency: EUR
category: clothes
quantity: 1
consumer:
email: test@scalapay.com
surname: Consumer
givenNames: Joe
phoneNumber: '393001234567'
merchant:
redirectCancelUrl: https://integration.api.scalapay.com/failure-url
redirectConfirmUrl: https://integration.api.scalapay.com/success-url
totalAmount:
amount: '190.00'
currency: EUR
merchantReference: merchantOrder-5678
'401':
$ref: '#/components/responses/401Error'
'422':
$ref: '#/components/responses/422Error'
/v2/payments/{token}/delay:
post:
tags:
- Orders
summary: Delay order
description: Request a delayed capture for the order. The payment schedule for the customer is created; however, no funds are settled until a capture call is made. Outstanding authorizations are automatically voided once the authorization expiry time is reached.
parameters:
- name: token
in: path
required: true
style: simple
explode: false
schema:
type: string
format: string
description: Order token.
example: 71KH916VPE
- name: Idempotency-Key
in: header
description: Idempotency key used for retrying requests. Can be used for retrying failed requests.
required: false
schema:
type: string
requestBody:
required: true
description: 'Request body must be JSON (Content-Type: application/json). Responses are always JSON.'
content:
application/json:
schema:
type: object
required:
- authorizationExpiryMilliseconds
properties:
authorizationExpiryMilliseconds:
type: integer
default: 432000000
description: Length of time (in milliseconds) that the authorization is valid.
merchantReference:
$ref: '#/components/schemas/merchantReference'
example:
authorizationExpiryMilliseconds: 432000000
merchantReference: merchantOrder-1234
responses:
'200':
description: Order delayed successfully
headers:
Request-Idempotency:
schema:
type: string
enum:
- 'true'
description: Present when the response was served from the idempotency cache.
required: false
content:
application/json:
schema:
type: object
required:
- token
- status
properties:
token:
type: string
description: The order token.
status:
type: string
description: The current status of the order after delay.
authorizationExpiryAt:
type: string
description: The date and time when the authorization expires.
totalAmount:
type: object
description: The total amount of the order.
properties:
amount:
type: string
description: The amount value.
currency:
type: string
description: The currency code (ISO 4217).
orderDetails:
type: object
description: The full order details.
example:
token: 71KH916VPE
status: AUTHORIZED
authorizationExpiryAt: '2024-12-25T23:02:13.000Z'
totalAmount:
amount: 40,70
currency: EUR
orderDetails:
items:
- sku: '12341234'
gtin: '123458791330'
name: T-Shirt
brand: TopChoice
price:
amount: '10.00'
currency: EUR
category: clothes
quantity: 1
subcategory:
- shirt
- long-sleeve
- sku: '12341235'
gtin: '123458722222'
name: Jeans
brand: TopChoice
price:
amount: '20.00'
currency: EUR
category: clothes
quantity: 1
subcategory:
- pants
- jeans
billing:
name: Mario Rossi
line1: Via Puglia, 23
suburb: Castelfranco Veneto
postcode: '31033'
countryCode: IT
phoneNumber: '393001234567'
consumer:
email: test@scalapay.com
surname: Consumer
givenNames: Joe
phoneNumber: '0400000001'
merchant:
redirectCancelUrl: https://portal.integration.com/failure-url
redirectConfirmUrl: https://portal.integration.scalapay.com/success-url
shipping:
name: Mario Rossi
line1: Via Puglia, 23
suburb: Castelfranco Veneto
geoCode:
place_id: VklBK0RFTExBK1JPU0ErMjMrLE1PTlRFTFVQTytGSU9SRU5USU5PLDUwMDU2LElU
postcode: '31033'
countryCode: IT
phoneNumber: '393001234567'
discounts:
- amount:
amount: '3.00'
currency: EUR
displayName: 10% Off
taxAmount:
amount: '3.70'
currency: EUR
totalAmount:
amount: '40.70'
currency: EUR
shippingAmount:
amount: '10.00'
currency: EUR
merchantReference: merchantOrder-1234
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'409':
$ref: '#/components/responses/409Error'
/v2/payments/{token}/refund:
post:
tags:
- Orders
summary: Refund order
description: Refund a fulfilled payment. The funds are reversed from the merchant's account and returned to the customer.
parameters:
- name: token
in: path
required: true
style: simple
explode: false
schema:
type: string
format: string
description: Order token.
example: 71KH916VPE
- name: Idempotency-Key
in: header
description: Idempotency key used for retrying requests. Can be used for retrying failed requests.
required: false
schema:
type: string
requestBody:
required: true
description: 'Request body must be JSON (Content-Type: application/json). Responses are always JSON.'
content:
application/json:
schema:
type: object
required:
- refundAmount
properties:
refundAmount:
allOf:
- $ref: '#/components/schemas/amount'
description: Amount to refund.
merchantRefundReference:
type: string
description: Merchant reference for the refund. Use this to track the refund in your system.
example:
refundAmount:
amount: '190.00'
currency: EUR
merchantRefundReference: ABC123
responses:
'200':
description: Refund processed successfully
headers:
Request-Idempotency:
schema:
type: string
enum:
- 'true'
description: Present when the response was served from the idempotency cache.
required: false
content:
application/json:
schema:
type: object
required:
- token
properties:
token:
type: string
description: The order token.
amount:
type: object
description: The refund amount.
properties:
amount:
type: string
description: The amount value.
currency:
type: string
description: The currency code (ISO 4217).
merchantReference:
type: string
description: The merchant reference.
merchantRefundReference:
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/scalapay/refs/heads/main/openapi/scalapay-orders-api-openapi.yml