Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Emporix Transaction API
version: ''
contact:
email: documentation@emporix.com
description: 'Operations tagged Transaction across 2 of this provider''s published API definitions: emporix-payment-gateway-openapi.yml, emporix-payment-gateway-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2: []
tags:
- name: Transaction
paths:
/payment-gateway/{tenant}/transactions:
parameters:
- $ref: '#/components/parameters/path_tenant'
get:
summary: Retrieving many transactions
tags:
- Transaction
responses:
'200':
$ref: '#/components/responses/paymentTransactionsResponse'
'401':
$ref: '#/components/responses/common_response_Unauthorized_401'
'403':
$ref: '#/components/responses/common_response_Forbidden_403'
'500':
$ref: '#/components/responses/common_response_InternalServerError_500'
operationId: GET-payment-gateway-list-transactions
description: Retrieves many payment transactions. A particular transaction contains all transactions' events attached as an entries of the response body.
security:
- OAuth2:
- payment-gateway.paymenttransactions_read
parameters:
- $ref: '#/components/parameters/page_number_query_param'
- $ref: '#/components/parameters/page_size_query_param'
- $ref: '#/components/parameters/sort_query_param'
- $ref: '#/components/parameters/x_total_count_header'
servers:
- url: https://api.emporix.io
/payment-gateway/{tenant}/transactions/{transactionId}:
parameters:
- $ref: '#/components/parameters/path_tenant'
- $ref: '#/components/parameters/path_transaction_id'
get:
summary: Retrieving a single transaction
tags:
- Transaction
responses:
'200':
$ref: '#/components/responses/paymentTransactionResponse'
'401':
$ref: '#/components/responses/common_response_Unauthorized_401'
'403':
$ref: '#/components/responses/common_response_Forbidden_403'
'404':
$ref: '#/components/responses/common_response_NotFound_404'
'500':
$ref: '#/components/responses/common_response_InternalServerError_500'
operationId: GET-payment-gateway-retrieve-transaction-by-transactionId
security:
- OAuth2:
- payment-gateway.paymenttransactions_read
description: Retrieves a single payment transaction. The transaction contains all the transaction's events attached as an entries of the response body.
servers:
- url: https://api.emporix.io
components:
parameters:
x_total_count_header:
name: X-Total-Count
in: header
required: false
schema:
type: boolean
description: To get information how many entities meet the filtering requirements, the `X-Total-Count` header has been introduced. The header is optional and its default value is `false`. If the header is provided and it is set to `true`, then the total count is returned in the `X-Total-Count` response header. In both cases (X-Total-Count `true`, `false` or not provided), the response body has the same format (array of entities). This means that the information about the total count is returned only on demand, provided that the X-Total-Count header is present in a request.
path_tenant:
name: tenant
in: path
required: true
description: 'Your Emporix tenant''s name.
**Note**: The tenant name should always be written in lowercase.
'
schema:
pattern: ^[a-z][a-z0-9]+$
minLength: 3
maxLength: 16
type: string
page_size_query_param:
name: pageSize
in: query
required: false
schema:
type: integer
default: 50
minimum: 1
maximum: 50
description: The number of documents being retrieved on one page.
sort_query_param:
name: sort
in: query
required: false
schema:
type: string
example: sort=name,metadata.createdAt:desc
description: 'Fields to sort the response data by following the order of the parameters from left to right. Can contain multiple fields in the following format: `field name:sort direction`, separated by a comma. The colon preceding the `sort direction` parameter is optional, and the descending order is taken only if it is equal to `desc` or `DESC`. The ascending order is assumed in any other case.'
path_transaction_id:
name: transactionId
in: path
required: true
schema:
type: string
description: Unique identifier of a payment transaction.
page_number_query_param:
name: pageNumber
in: query
schema:
type: integer
default: 1
minimum: 1
description: The page number to be retrieved, where the size of the pages is specified by the `pageSize` parameter. The number of the first page is 1.
schemas:
paymentTransactionResponse:
title: paymentTransactionResponse
type: object
properties:
id:
type: string
description: A unique identifier of a payment transaction.
provider:
$ref: '#/components/schemas/provider'
description: Indicates which provider should be used.
paymentInformation:
type: object
description: Information related to a payment mode.
properties:
paymentMode:
type: string
description: A unique identifier of a payment mode configured for the tenant.
creditCardToken:
type: string
description: Token of the credit card.
cardHolderName:
type: string
description: Name of the card holder.
payByLinkURL:
type: string
description: URL for pay-by-link payment flow.
iban:
type: string
description: International Bank Account Number.
bic:
type: string
description: Bank Identifier Code (SWIFT).
sepaMandateReference:
type: string
description: SEPA mandate reference.
entries:
type: array
description: List of transaction entries representing payment events.
items:
type: object
properties:
id:
type: string
description: Unique identifier of a payment transaction entry.
createdDate:
type: string
format: date-time
description: Timestamp when the event happened.
example: '2023-07-04T22:08:05.465Z'
type:
type: string
description: Event type.
enum:
- INITIALIZATION
- AUTHORIZATION
- CAPTURE
- REFUND
- CANCEL
- AUTHORIZATION_START
- AUTHORIZATION_CALLBACK
successful:
type: boolean
description: Indicates if the event completed successfully.
amount:
type: object
properties:
amount:
type: number
description: Amount related to the event.
currency:
type: string
description: ISO currency code.
example: EUR
summary:
type: string
description: Summary of the event.
remoteRequest:
type: string
description: Serialized request body sent to payment provider.
remoteResponse:
type: string
description: Serialized response body from payment provider.
remoteToken:
type: string
description: Remote token returned by payment provider.
additionalInfo:
type: object
description: Additional info about the transaction.
additionalProperties: true
provider:
type: string
enum:
- INVOICE
- CASH_ON_DELIVERY
- SPREEDLY
- SPREEDLY_SAFERPAY
- UNZER
coreErrorMessage:
anyOf:
- type: object
properties:
code:
type: integer
description: HTTP Status code.
timestamp:
type: string
description: Indicates a timestamp when the error occurred.
message:
type: string
description: Error message.
- type: object
properties:
type:
type: string
description: HTTP error type.
status:
type: integer
description: HTTP Status code.
message:
type: string
description: Error message.
moreInfo:
type: string
description: URL which additional information.
details:
type: array
items:
type: object
properties:
message:
type: string
description: Detailed message.
responses:
paymentTransactionResponse:
description: Payment transaction response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentTransactionResponse'
examples:
Payment transaction:
value:
id: d8abfb12-0266-43dc-905e-415158029d45
provider: SPREEDLY
paymentInformation:
paymentMode: 92d77b2b-9385-43ad-a859-55176fbcbd2f
creditCardToken: FrHVCFtcshQ8gkOR8t5RlneLy02
entries:
- id: 5ab6f875-5414-4845-afe9-8976531a2573
createdDate: '2023-07-02T09:19:42.170Z'
type: AUTHORIZATION
successful: true
amount:
amount: 36.63
currency: EUR
summary: Succeeded!
remoteRequest: "{\n \"transaction\" : {\n \"amount\" : 3663,\n \"payment_method_token\" : \"O7z9EVXYwzzxgQO78nobou22ET1\",\n \"currency_code\" : \"EUR\",\n \"order_id\" : \"EON1562\",\n \"retain_on_success\" : false\n }\n}"
remoteResponse: "{\n \"transaction\" : {\n \"token\" : \"FrHVCFtcshQ8gkOR8t5RlneLy02\",\n \"succeeded\" : true,\n \"message\" : \"Succeeded!\",\n \"response\" : {\n \"success\" : true,\n \"message\" : \"Successful authorize\",\n \"pending\" : false,\n \"cancelled\" : false,\n \"result_unknown\" : false,\n \"created_at\" : \"2023-07-02T09:19:42Z\",\n \"updated_at\" : \"2023-07-02T09:19:42Z\"\n },\n \"state\" : \"succeeded\",\n \"retained\" : false,\n \"amount\" : \"3663\",\n \"gateway_transaction_id\" : \"48\",\n \"created_at\" : \"2023-07-02T09:19:42Z\",\n \"updated_at\" : \"2023-07-02T09:19:42Z\",\n \"transaction_type\" : \"Authorization\",\n \"order_id\" : \"EON1562\",\n \"gateway_token\" : \"5xGx9vcZlMe1AVuHQk00CZTS8YM\",\n \"currency_code\" : \"EUR\",\n \"shipping_address\" : {\n \"name\" : \"John Smith\"\n },\n \"payment_method\" : {\n \"token\" : \"O7z9EVXYwzzxgQO78nobou22ET1\",\n \"test\" : true,\n \"month\" : 9,\n \"year\" : 2023,\n \"number\" : \"XXXX-XXXX-XXXX-1111\",\n \"fingerprint\" : \"78250e7a0b53b34f526fbf99be66982e1127\",\n \"created_at\" : \"2023-07-02T09:19:39Z\",\n \"updated_at\" : \"2023-07-02T09:19:39Z\",\n \"storage_state\" : \"cached\",\n \"last_four_digits\" : \"1111\",\n \"first_name\" : \"John\",\n \"last_name\" : \"Smith\",\n \"full_name\" : \"John Smith\",\n \"eligible_for_card_updater\" : true,\n \"issuer_identification_number\" : \"41111111\",\n \"payment_method_type\" : \"credit_card\",\n \"verification_value\" : \"XXX\"\n }\n }\n}"
- id: b5c995f9-0ae8-455d-af0a-68f6995305bd
createdDate: '2023-07-02T09:20:17.333Z'
type: CAPTURE
successful: true
amount:
amount: 36.63
currency: EUR
summary: Succeeded!
remoteRequest: "{\n \"amount\" : 3663,\n \"currency_code\" : \"EUR\"\n}"
remoteResponse: "{\n \"transaction\" : {\n \"token\" : \"ReaQQuCxWIhL1h1gyfE0VAuKQlI\",\n \"succeeded\" : true,\n \"message\" : \"Succeeded!\",\n \"response\" : {\n \"success\" : true,\n \"message\" : \"Successful capture\",\n \"pending\" : false,\n \"cancelled\" : false,\n \"result_unknown\" : false,\n \"created_at\" : \"2023-07-02T09:20:17Z\",\n \"updated_at\" : \"2023-07-02T09:20:17Z\"\n },\n \"gateway_transaction_id\" : \"51\"\n }\n}"
- id: a080a8e1-c48f-410d-bd5a-7b921f5ce549
createdDate: '2023-07-02T09:20:28.650Z'
type: REFUND
successful: true
amount:
amount: 1
currency: EUR
summary: Succeeded!
remoteRequest: "{\n \"amount\" : 100,\n \"currency_code\" : \"EUR\"\n}"
remoteResponse: "{\n \"transaction\" : {\n \"token\" : \"Xn8g3ZiTFJ1Sbd3AOlvr2aZtdaW\",\n \"succeeded\" : true,\n \"message\" : \"Succeeded!\",\n \"response\" : {\n \"success\" : true,\n \"message\" : \"Successful credit\",\n \"pending\" : false,\n \"cancelled\" : false,\n \"result_unknown\" : false,\n \"created_at\" : \"2023-07-02T09:20:28Z\",\n \"updated_at\" : \"2023-07-02T09:20:28Z\"\n },\n \"gateway_transaction_id\" : \"59\"\n }\n}"
- id: e7d19c09-322b-4596-9206-4b45a532bff1
createdDate: '2023-07-02T09:20:38.441Z'
type: REFUND
successful: true
amount:
amount: 2
currency: EUR
summary: Succeeded!
remoteRequest: "{\n \"amount\" : 200,\n \"currency_code\" : \"EUR\"\n}"
remoteResponse: "{\n \"transaction\" : {\n \"token\" : \"CfcdzCUsXFlkNYNrnQsYoAquNAn\",\n \"succeeded\" : true,\n \"message\" : \"Succeeded!\",\n \"response\" : {\n \"success\" : true,\n \"message\" : \"Successful credit\",\n \"pending\" : false,\n \"cancelled\" : false,\n \"result_unknown\" : false,\n \"created_at\" : \"2023-07-02T09:20:38Z\",\n \"updated_at\" : \"2023-07-02T09:20:38Z\"\n },\n \"gateway_transaction_id\" : \"68\"\n }\n}"
common_response_Unauthorized_401:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
fault:
type: object
properties:
faultstring:
type: string
detail:
type: object
properties:
errorcode:
type: string
examples:
Invalid access token:
value:
fault:
faultstring: Invalid access token
detail:
errorcode: oauth.v2.InvalidAccessToken
Access token expired:
value:
fault:
faultstring: Access Token expired
detail:
errorcode: keymanagement.service.access_token_expired
paymentTransactionsResponse:
description: Payment transactions response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/paymentTransactionResponse'
examples:
Payment transactions response:
value:
- id: d8abfb12-0266-43dc-905e-415158029d45
provider: SPREEDLY
paymentInformation:
paymentMode: 92d77b2b-9385-43ad-a859-55176fbcbd2f
creditCardToken: FrHVCFtcshQ8gkOR8t5RlneLy02
entries:
- id: 5ab6f875-5414-4845-afe9-8976531a2573
createdDate: '2023-07-02T09:19:42.170Z'
type: AUTHORIZATION
successful: true
amount:
amount: 36.63
currency: EUR
summary: Succeeded!
remoteRequest: "{\n \"transaction\" : {\n \"amount\" : 3663,\n \"payment_method_token\" : \"O7z9EVXYwzzxgQO78nobou22ET1\",\n \"currency_code\" : \"EUR\",\n \"order_id\" : \"EON1562\",\n \"retain_on_success\" : false\n }\n}"
remoteResponse: "{\n \"transaction\" : {\n \"token\" : \"FrHVCFtcshQ8gkOR8t5RlneLy02\",\n \"succeeded\" : true,\n \"message\" : \"Succeeded!\",\n \"response\" : {\n \"success\" : true,\n \"message\" : \"Successful authorize\",\n \"pending\" : false,\n \"cancelled\" : false,\n \"result_unknown\" : false,\n \"created_at\" : \"2023-07-02T09:19:42Z\",\n \"updated_at\" : \"2023-07-02T09:19:42Z\"\n },\n \"state\" : \"succeeded\",\n \"retained\" : false,\n \"amount\" : \"3663\",\n \"gateway_transaction_id\" : \"48\",\n \"created_at\" : \"2023-07-02T09:19:42Z\",\n \"updated_at\" : \"2023-07-02T09:19:42Z\",\n \"transaction_type\" : \"Authorization\",\n \"order_id\" : \"EON1562\",\n \"gateway_token\" : \"5xGx9vcZlMe1AVuHQk00CZTS8YM\",\n \"currency_code\" : \"EUR\",\n \"shipping_address\" : {\n \"name\" : \"John Smith\"\n },\n \"payment_method\" : {\n \"token\" : \"O7z9EVXYwzzxgQO78nobou22ET1\",\n \"test\" : true,\n \"month\" : 9,\n \"year\" : 2023,\n \"number\" : \"XXXX-XXXX-XXXX-1111\",\n \"fingerprint\" : \"78250e7a0b53b34f526fbf99be66982e1127\",\n \"created_at\" : \"2023-07-02T09:19:39Z\",\n \"updated_at\" : \"2023-07-02T09:19:39Z\",\n \"storage_state\" : \"cached\",\n \"last_four_digits\" : \"1111\",\n \"first_name\" : \"John\",\n \"last_name\" : \"Smith\",\n \"full_name\" : \"John Smith\",\n \"eligible_for_card_updater\" : true,\n \"issuer_identification_number\" : \"41111111\",\n \"payment_method_type\" : \"credit_card\",\n \"verification_value\" : \"XXX\"\n }\n }\n}"
- id: b5c995f9-0ae8-455d-af0a-68f6995305bd
createdDate: '2023-07-02T09:20:17.333Z'
type: CAPTURE
successful: true
amount:
amount: 36.63
currency: EUR
summary: Succeeded!
remoteRequest: "{\n \"amount\" : 3663,\n \"currency_code\" : \"EUR\"\n}"
remoteResponse: "{\n \"transaction\" : {\n \"token\" : \"ReaQQuCxWIhL1h1gyfE0VAuKQlI\",\n \"succeeded\" : true,\n \"message\" : \"Succeeded!\",\n \"response\" : {\n \"success\" : true,\n \"message\" : \"Successful capture\",\n \"pending\" : false,\n \"cancelled\" : false,\n \"result_unknown\" : false,\n \"created_at\" : \"2023-07-02T09:20:17Z\",\n \"updated_at\" : \"2023-07-02T09:20:17Z\"\n },\n \"gateway_transaction_id\" : \"51\"\n }\n}"
- id: a080a8e1-c48f-410d-bd5a-7b921f5ce549
createdDate: '2023-07-02T09:20:28.650Z'
type: REFUND
successful: true
amount:
amount: 1
currency: EUR
summary: Succeeded!
remoteRequest: "{\n \"amount\" : 100,\n \"currency_code\" : \"EUR\"\n}"
remoteResponse: "{\n \"transaction\" : {\n \"token\" : \"Xn8g3ZiTFJ1Sbd3AOlvr2aZtdaW\",\n \"succeeded\" : true,\n \"message\" : \"Succeeded!\",\n \"response\" : {\n \"success\" : true,\n \"message\" : \"Successful credit\",\n \"pending\" : false,\n \"cancelled\" : false,\n \"result_unknown\" : false,\n \"created_at\" : \"2023-07-02T09:20:28Z\",\n \"updated_at\" : \"2023-07-02T09:20:28Z\"\n },\n \"gateway_transaction_id\" : \"59\"\n }\n}"
- id: e7d19c09-322b-4596-9206-4b45a532bff1
createdDate: '2023-07-02T09:20:38.441Z'
type: REFUND
successful: true
amount:
amount: 2
currency: EUR
summary: Succeeded!
remoteRequest: "{\n \"amount\" : 200,\n \"currency_code\" : \"EUR\"\n}"
remoteResponse: "{\n \"transaction\" : {\n \"token\" : \"CfcdzCUsXFlkNYNrnQsYoAquNAn\",\n \"succeeded\" : true,\n \"message\" : \"Succeeded!\",\n \"response\" : {\n \"success\" : true,\n \"message\" : \"Successful credit\",\n \"pending\" : false,\n \"cancelled\" : false,\n \"result_unknown\" : false,\n \"created_at\" : \"2023-07-02T09:20:38Z\",\n \"updated_at\" : \"2023-07-02T09:20:38Z\"\n },\n \"gateway_transaction_id\" : \"68\"\n }\n}"
headers:
X-Total-Count:
description: '''The total number of entities in the database matching the specified query criteria.
Returned if request X-Total-Count header has been set to true.'''
schema:
type: number
example: 100
common_response_Forbidden_403:
description: Access forbidden. The caller is not allowed to access this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/coreErrorMessage'
examples:
Forbidden:
value:
status: 403
type: Forbidden
message: The access to the requested resource has been forbidden by the server.
details:
- message: Missing required scopes '[payment-gateway.authorize_manage]'
common_response_InternalServerError_500:
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/coreErrorMessage'
examples:
Internal Server Error:
value:
code: 500
timestamp: '2023-10-03T12:23:31.485306Z'
message: Problem encountered while trying to connect to the database.
common_response_NotFound_404:
description: Not found. The resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/coreErrorMessage'
examples:
NotFound:
value:
code: 404
timestamp: '2023-10-03T12:23:31.485306Z'
message: The resource does not exist.
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.emporix.io/oauth/token
scopes:
payment-gateway.paymentmodes_read: Needed for reading payment modes by a tenant employee.
payment-gateway.paymentmodes_manage: Needed to manage payment modes by a tenant employee.
payment-gateway.authorize_manage: Needed to perform a payment authorization flow by a tenant employee.
payment-gateway.capture_manage: Needed to perform a payment capture flow by a tenant employee.
payment-gateway.refund_manage: Needed to perform a payment refund flow by a tenant employee.
payment-gateway.cancel_manage: Needed to perform a payment cancel flow by a tenant employee.
payment-gateway.paymenttransactions_read: Needed to read all transaction details by a tenant employee.
x-refined-from:
- emporix-payment-gateway-openapi.yml
- emporix-payment-gateway-openapi.yml