Payments

Create a new customer-initiated payment

post

Creates a new customer-initiated payment.

After a payment is created a payment method (card, bank, saved token) must be added to it. The user can attempt adding payment method multiple times until ultimately one is successful. The checkout process is continued by either redirecting the user to the gateway hosted checkout page or integrating directly with EGW APIs.

Additionally, the setupToken fields can be used to save the used payment method for future payments.

Authorizations

OAuth2ClientAuthentication

OpenID ConnectRequired

This API uses OAuth 2 with the client credentials flow. More info

Path parameters

versionstringRequired

Header parameters

X-Request-Idstring · uuidRequired

ID of the request, unique to the call, as determined by the initiating party

Body

application/json

channelstring · enumRequired

Identifies the method or channel through which a payment was initiated:

• BROWSER - payment initiated when the customer makes a regular online purchase via a website (e-shop)

Possible values:

descriptionstring · max: 255Optional

Description of the payment

merchantReferencestring · max: 255Optional

Merchant's payment reference

orderNumberstring · max: 255Required

Merchant's order number

Pattern: ^[a-zA-Z0-9/-?:().,'+\-]*$

participantIdstring · max: 64Required

Unique ID of the participant

preferredCountrystringOptional

Default country for bank selection in the gateway hosted checkout page

preferredLocalestring · enumOptional

Default locale for the gateway hosted checkout page

Possible values:

shopAgreementIdstring · max: 64Required

Unique ID of the shop

shopRedirectUrlstring · min: 1Required

Responses

200

OK

application/json

createdAtstring · date-timeOptional

environmentstring · enumOptionalPossible values:

orderNumberstringOptional

participantIdstring · max: 64Optional

Unique ID of the participant

paymentIdstring · max: 64Optional

Unique ID of the payment

paymentStatusstring · enumOptionalPossible values:

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

post

/egw/{version}/payments/cit

HTTPcURLJavaScriptPython

POST /egw/{version}/payments/cit HTTP/1.1
Host: sandbox-api.ecomm.api.tietoevry.com
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 1009

{
  "basket": {
    "items": [
      {
        "description": "text",
        "imageUrl": "text",
        "name": "text",
        "price": {
          "amount": 5877.78,
          "currency": "EUR"
        },
        "quantity": 1,
        "sku": "text",
        "taxRate": 1,
        "totalPrice": {
          "amount": 5877.78,
          "currency": "EUR"
        }
      }
    ],
    "salesTaxAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "shippingAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "subtotalAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    }
  },
  "billingAddress": {
    "addressLine1": "text",
    "addressLine2": "text",
    "city": "text",
    "country": "text",
    "postalCode": "text",
    "state": "text"
  },
  "channel": "BROWSER",
  "customer": {
    "email": "[email protected]",
    "name": "text",
    "phone": "text"
  },
  "description": "text",
  "instructedAmount": {
    "amount": 5877.78,
    "currency": "EUR"
  },
  "merchantReference": "text",
  "orderNumber": "text",
  "participantId": "text",
  "preferredCountry": "text",
  "preferredLocale": "cz",
  "setupToken": {
    "purposes": [
      "CIT"
    ],
    "required": true
  },
  "shippingAddress": {
    "addressLine1": "text",
    "addressLine2": "text",
    "city": "text",
    "country": "text",
    "postalCode": "text",
    "state": "text"
  },
  "shopAgreementId": "text",
  "shopRedirectUrl": "text"
}

{
  "_links": {
    "checkoutRedirect": {
      "href": "text"
    }
  },
  "availablePaymentMethods": [
    {
      "type": "text"
    }
  ],
  "basket": {
    "items": [
      {
        "description": "text",
        "imageUrl": "text",
        "name": "text",
        "price": {
          "amount": 5877.78,
          "currency": "EUR"
        },
        "quantity": 1,
        "sku": "text",
        "taxRate": 1,
        "totalPrice": {
          "amount": 5877.78,
          "currency": "EUR"
        }
      }
    ],
    "salesTaxAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "shippingAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "subtotalAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    }
  },
  "createdAt": "2026-03-31T12:04:03.004Z",
  "environment": "SANDBOX",
  "instructedAmount": {
    "amount": 5877.78,
    "currency": "EUR"
  },
  "orderNumber": "text",
  "participantId": "text",
  "paymentId": "text",
  "paymentStatus": "INITIALIZED",
  "shop": {
    "agreementId": "text",
    "country": "text",
    "name": "text"
  }
}

Create a new merchant-initiated payment

post

Creates a new merchant-initiated payment - payment without direct involvement of the end user (e.g. subscriptions).

Only previously saved payment method token can be used for merchant-initiated payments. Before creating merchant-initiated payments it is necessary to setup a token agreement during an initial customer-initiated payment.

Authorizations

OAuth2ClientAuthentication

OpenID ConnectRequired

This API uses OAuth 2 with the client credentials flow. More info

Path parameters

versionstringRequired

Header parameters

X-Request-Idstring · uuidRequired

ID of the request, unique to the call, as determined by the initiating party

Body

application/json

channelstring · enumRequired

Identifies the method or channel through which a payment was initiated:

• RECURRING - payment initiated by the merchant or backend system without customer presence, on a predefined schedule with a fixed or variable amount (e.g., monthly subscription, utility bill)
• MERCHANT - payment initiated by the merchant or backend system without customer presence, on an ad-hoc basis with a variable amount and undefined frequency (e.g., automatic top-up, partial shipments, no-show fees, or other post-service charges)

Possible values:

descriptionstring · max: 255Optional

Description of the payment

merchantReferencestring · max: 255Optional

Merchant's payment reference

orderNumberstring · max: 255Required

Merchant's order number

Pattern: ^[a-zA-Z0-9/-?:().,'+\-]*$

participantIdstring · max: 64Required

Unique ID of the participant

shopAgreementIdstring · max: 64Required

Unique ID of the shop

Responses

200

OK

application/json

createdAtstring · date-timeOptional

environmentstring · enumOptionalPossible values:

orderNumberstringOptional

participantIdstring · max: 64Optional

Unique ID of the participant

paymentIdstring · max: 64Optional

Unique ID of the payment

paymentStatusstring · enumOptionalPossible values:

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

post

/egw/{version}/payments/mit

HTTPcURLJavaScriptPython

POST /egw/{version}/payments/mit HTTP/1.1
Host: sandbox-api.ecomm.api.tietoevry.com
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 887

{
  "basket": {
    "items": [
      {
        "description": "text",
        "imageUrl": "text",
        "name": "text",
        "price": {
          "amount": 5877.78,
          "currency": "EUR"
        },
        "quantity": 1,
        "sku": "text",
        "taxRate": 1,
        "totalPrice": {
          "amount": 5877.78,
          "currency": "EUR"
        }
      }
    ],
    "salesTaxAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "shippingAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "subtotalAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    }
  },
  "billingAddress": {
    "addressLine1": "text",
    "addressLine2": "text",
    "city": "text",
    "country": "text",
    "postalCode": "text",
    "state": "text"
  },
  "channel": "RECURRING",
  "customer": {
    "email": "[email protected]",
    "name": "text",
    "phone": "text"
  },
  "description": "text",
  "instructedAmount": {
    "amount": 5877.78,
    "currency": "EUR"
  },
  "merchantReference": "text",
  "orderNumber": "text",
  "participantId": "text",
  "shippingAddress": {
    "addressLine1": "text",
    "addressLine2": "text",
    "city": "text",
    "country": "text",
    "postalCode": "text",
    "state": "text"
  },
  "shopAgreementId": "text"
}

{
  "_links": {
    "checkoutRedirect": {
      "href": "text"
    }
  },
  "availablePaymentMethods": [
    {
      "type": "text"
    }
  ],
  "basket": {
    "items": [
      {
        "description": "text",
        "imageUrl": "text",
        "name": "text",
        "price": {
          "amount": 5877.78,
          "currency": "EUR"
        },
        "quantity": 1,
        "sku": "text",
        "taxRate": 1,
        "totalPrice": {
          "amount": 5877.78,
          "currency": "EUR"
        }
      }
    ],
    "salesTaxAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "shippingAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "subtotalAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    }
  },
  "createdAt": "2026-03-31T12:04:03.004Z",
  "environment": "SANDBOX",
  "instructedAmount": {
    "amount": 5877.78,
    "currency": "EUR"
  },
  "orderNumber": "text",
  "participantId": "text",
  "paymentId": "text",
  "paymentStatus": "INITIALIZED",
  "shop": {
    "agreementId": "text",
    "country": "text",
    "name": "text"
  }
}

Get payment information

get

Returns the content of a payment object

Authorizations

OAuth2ClientAuthentication

OpenID ConnectRequired

This API uses OAuth 2 with the client credentials flow. More info

Path parameters

paymentIdstring · max: 64Required

Unique ID of the payment

versionstringRequired

Query parameters

Header parameters

X-Request-Idstring · uuidRequired

ID of the request, unique to the call, as determined by the initiating party

Responses

200

OK

application/json

channelstring · enumOptional

Identifies the method or channel through which a payment was initiated:

• BROWSER - payment initiated when the customer makes a regular online purchase via a website (e-shop)
• RECURRING - payment initiated by the merchant or backend system without customer presence, on a predefined schedule with a fixed or variable amount (e.g., monthly subscription, utility bill)
• MERCHANT - payment initiated by the merchant or backend system without customer presence, on an ad-hoc basis with a variable amount and undefined frequency (e.g., automatic top-up, partial shipments, no-show fees, or other post-service charges)
• PAYMENT_LINK - payment initiated when the customer clicks a link provided by the merchant (e.g., via a button in an app or website, a link sent via SMS, chat or other messaging channel)
• QR_CODE - payment initiated when the customer scans a QR code presented by the merchant (e.g., in-store or on-screen)

Possible values:

createdAtstring · date-timeOptional

environmentstring · enumOptionalPossible values:

merchantReferencestringOptional

Merchant's payment reference

orderNumberstringOptional

Merchant's order number

participantIdstring · max: 64Optional

Unique ID of the participant

paymentIdstring · max: 64Optional

Unique ID of the payment

paymentLinkIdstring · max: 64Optional

paymentStatusstring · enumOptionalPossible values:

preferredCountrystringOptional

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

get

/egw/{version}/payments/{paymentId}

HTTPcURLJavaScriptPython

GET /egw/{version}/payments/{paymentId}?queryParams=[object+Object] HTTP/1.1
Host: sandbox-api.ecomm.api.tietoevry.com
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "_links": {
    "checkoutRedirect": {
      "href": "text"
    },
    "shopRedirect": {
      "href": "text"
    }
  },
  "availablePaymentMethods": [
    {
      "type": "text"
    }
  ],
  "basket": {
    "items": [
      {
        "description": "text",
        "imageUrl": "text",
        "name": "text",
        "price": {
          "amount": 5877.78,
          "currency": "EUR"
        },
        "quantity": 1,
        "sku": "text",
        "taxRate": 1,
        "totalPrice": {
          "amount": 5877.78,
          "currency": "EUR"
        }
      }
    ],
    "salesTaxAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "shippingAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    },
    "subtotalAmount": {
      "amount": 5877.78,
      "currency": "EUR"
    }
  },
  "channel": "BROWSER",
  "checkoutBranding": {
    "basketItemPlaceholder": "text",
    "buttonRadius": "text",
    "color": "text",
    "disabledOptions": [
      "CARD"
    ],
    "font": "text",
    "groupOrder": [
      "WALLETS"
    ],
    "groupingType": "NO_GROUPING",
    "logo": "text",
    "logoPlaceholder": "text",
    "paymentOptionOrder": [
      "CARD"
    ],
    "secondaryColor": "text"
  },
  "createdAt": "2026-03-31T12:04:03.004Z",
  "customer": {
    "email": "[email protected]",
    "name": "text",
    "phone": "text"
  },
  "environment": "SANDBOX",
  "instructedAmount": {
    "amount": 5877.78,
    "currency": "EUR"
  },
  "merchantReference": "text",
  "orderNumber": "text",
  "participantId": "text",
  "paymentId": "text",
  "paymentLinkId": "text",
  "paymentMethod": {
    "card": {
      "brand": "VISA",
      "cardholderName": "text",
      "expiry": {
        "month": "text",
        "year": "text"
      },
      "lastFourDigits": "text"
    },
    "gatewayTokenId": "text",
    "openBanking": {
      "bankId": "text",
      "iban": "text"
    },
    "type": "CARD"
  },
  "paymentStatus": "INITIALIZED",
  "preferredCountry": "text",
  "refundedAmount": {
    "amount": 5877.78,
    "currency": "EUR"
  },
  "shop": {
    "agreementId": "text",
    "country": "text",
    "name": "text"
  }
}

Captures an existing payment

patch

Capturing an authorized payment will complete (finalise) the payment, this is only used for card payments

Authorizations

OAuth2ClientAuthentication

OpenID ConnectRequired

This API uses OAuth 2 with the client credentials flow. More info

Path parameters

paymentIdstring · max: 64Required

Unique ID of the payment

versionstringRequired

Header parameters

X-Request-Idstring · uuidRequired

ID of the request, unique to the call, as determined by the initiating party

Body

application/json

The request for capturing an existing payment

Responses

200

OK

application/json

The response after capturing a card payment

paymentIdstring · max: 64Optional

Unique ID of the payment

paymentStatusstring · enumOptional

Current status of the payment

Possible values:

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

patch

/egw/{version}/payments/{paymentId}/capture

HTTPcURLJavaScriptPython

PATCH /egw/{version}/payments/{paymentId}/capture HTTP/1.1
Host: sandbox-api.ecomm.api.tietoevry.com
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "instructedAmount": {
    "amount": 5877.78,
    "currency": "EUR"
  }
}

{
  "paymentId": "text",
  "paymentStatus": "INITIALIZED"
}

Cancels a payment

patch

A payment can be cancelled when it is initialized or authorized

Authorizations

OAuth2ClientAuthentication

OpenID ConnectRequired

This API uses OAuth 2 with the client credentials flow. More info

Path parameters

paymentIdstring · max: 64Required

Unique ID of the payment

versionstringRequired

Header parameters

X-Request-Idstring · uuidRequired

ID of the request, unique to the call, as determined by the initiating party

Body

application/json

The request for cancelling a payment

reasonstring · enumOptional

Reason to cancel the payment

Possible values:

Responses

200

OK

application/json

The response after cancelling a payment

paymentIdstring · max: 64Optional

Unique ID of the payment

paymentStatusstring · enumOptional

Current status of the payment

Possible values:

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

patch

/egw/{version}/payments/{paymentId}/cancel

HTTPcURLJavaScriptPython

PATCH /egw/{version}/payments/{paymentId}/cancel HTTP/1.1
Host: sandbox-api.ecomm.api.tietoevry.com
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "reason": "SUSPECTED_FRAUD"
}

{
  "paymentId": "text",
  "paymentStatus": "INITIALIZED"
}