Payments | Tietoevry Documentation

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 setupAgreement fields can be used to save the used payment method for future payments.

Path parameters

versionstringRequired

Header parameters

X-Request-Idstring · uuidRequired

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

Body

orderIdstring · max: 255Required

Merchant's order ID

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

shopRedirectUrlstring · min: 1Required

preferredLocalestring · enumOptional

Default locale for the gateway hosted checkout page

Possible values:

preferredCountrystringOptional

Default country for bank selection in the gateway hosted checkout page

descriptionstring · max: 255Optional

Description of the payment

Responses

200

OK

application/json

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

post

POST /egw/{version}/payments/cit HTTP/1.1
Host: hostname
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 832

{
  "orderId": "text",
  "instructedAmount": {
    "currency": "EUR",
    "amount": 5877.78
  },
  "customer": {
    "name": "text",
    "email": "text",
    "phone": {
      "cc": "text",
      "subscriber": "text"
    }
  },
  "shippingAddress": {
    "city": "text",
    "country": "text",
    "postalCode": "text",
    "state": "text",
    "addressLine1": "text",
    "addressLine2": "text"
  },
  "billingAddress": {
    "city": "text",
    "country": "text",
    "postalCode": "text",
    "state": "text",
    "addressLine1": "text",
    "addressLine2": "text"
  },
  "shopRedirectUrl": "text",
  "preferredLocale": "cz",
  "preferredCountry": "text",
  "setupToken": {
    "required": true,
    "purposes": [
      "CIT"
    ]
  },
  "description": "text",
  "basket": {
    "subtotalAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "salesTaxAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "shippingAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "items": [
      {
        "name": "text",
        "quantity": 1,
        "price": {
          "currency": "EUR",
          "amount": 5877.78
        },
        "imageUrl": "text"
      }
    ]
  }
}

{
  "paymentId": "text",
  "orderId": "text",
  "paymentStatus": "INITIALIZED",
  "instructedAmount": {
    "currency": "EUR",
    "amount": 5877.78
  },
  "shop": {
    "name": "text",
    "agreementId": "text",
    "country": "text"
  },
  "availablePaymentMethods": [
    {
      "type": "CARD",
      "brands": [
        "VISA"
      ],
      "_links": {
        "checkoutRedirect": {
          "href": "text"
        }
      }
    }
  ],
  "createdAt": "2025-07-07T02:35:17.825Z",
  "basket": {
    "subtotalAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "salesTaxAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "shippingAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "items": [
      {
        "name": "text",
        "quantity": 1,
        "price": {
          "currency": "EUR",
          "amount": 5877.78
        },
        "imageUrl": "text"
      }
    ]
  },
  "_links": {
    "checkoutRedirect": {
      "href": "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.

Path parameters

versionstringRequired

Header parameters

X-Request-Idstring · uuidRequired

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

Body

orderIdstring · max: 255Required

Merchant's order ID

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

purposestring · enumRequired

Indicates the purpose of the payment:

UNSCHEDULED - merchant-initiated ad-hoc payments with variable amount and undefined frequency
SUBSCRIPTION - merchant-initiated recurring payments with fixed amount and frequency
STANDING_ORDER - merchant-initiated recurring payments with variable amount, but fixed frequency

Possible values:

descriptionstring · max: 255Optional

Description of the payment

Responses

200

OK

application/json

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

post

POST /egw/{version}/payments/mit HTTP/1.1
Host: hostname
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 732

{
  "orderId": "text",
  "instructedAmount": {
    "currency": "EUR",
    "amount": 5877.78
  },
  "customer": {
    "name": "text",
    "email": "text",
    "phone": {
      "cc": "text",
      "subscriber": "text"
    }
  },
  "shippingAddress": {
    "city": "text",
    "country": "text",
    "postalCode": "text",
    "state": "text",
    "addressLine1": "text",
    "addressLine2": "text"
  },
  "billingAddress": {
    "city": "text",
    "country": "text",
    "postalCode": "text",
    "state": "text",
    "addressLine1": "text",
    "addressLine2": "text"
  },
  "purpose": "UNSCHEDULED",
  "description": "text",
  "basket": {
    "subtotalAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "salesTaxAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "shippingAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "items": [
      {
        "name": "text",
        "quantity": 1,
        "price": {
          "currency": "EUR",
          "amount": 5877.78
        },
        "imageUrl": "text"
      }
    ]
  }
}

{
  "paymentId": "text",
  "orderId": "text",
  "paymentStatus": "INITIALIZED",
  "instructedAmount": {
    "currency": "EUR",
    "amount": 5877.78
  },
  "shop": {
    "name": "text",
    "agreementId": "text",
    "country": "text"
  },
  "availablePaymentMethods": [
    {
      "type": "CARD",
      "brands": [
        "VISA"
      ],
      "_links": {
        "checkoutRedirect": {
          "href": "text"
        }
      }
    }
  ],
  "createdAt": "2025-07-07T02:35:17.825Z",
  "basket": {
    "subtotalAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "salesTaxAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "shippingAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "items": [
      {
        "name": "text",
        "quantity": 1,
        "price": {
          "currency": "EUR",
          "amount": 5877.78
        },
        "imageUrl": "text"
      }
    ]
  },
  "_links": {
    "checkoutRedirect": {
      "href": "text"
    }
  }
}

Get payment information

get

Returns the content of a payment object

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

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

get

GET /egw/{version}/payments/{paymentId} HTTP/1.1
Host: hostname
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "paymentId": "text",
  "orderId": "text",
  "merchantId": "text",
  "paymentStatus": "INITIALIZED",
  "initiator": "CUSTOMER",
  "instructedAmount": {
    "currency": "EUR",
    "amount": 5877.78
  },
  "returnedAmount": {
    "currency": "EUR",
    "amount": 5877.78
  },
  "shop": {
    "name": "text",
    "agreementId": "text",
    "country": "text"
  },
  "checkoutBranding": {
    "logoPlaceholder": "text",
    "logo": "text",
    "font": "text",
    "color": "text",
    "buttonRadius": "text",
    "basketItemPlaceholder": "text"
  },
  "availablePaymentMethods": [
    {
      "type": "CARD",
      "brands": [
        "VISA"
      ],
      "_links": {
        "checkoutRedirect": {
          "href": "text"
        }
      }
    }
  ],
  "paymentMethod": {
    "type": "CARD",
    "tokenId": "text",
    "card": {
      "cardholderName": "text",
      "lastFourDigits": "text",
      "brand": "VISA",
      "expiry": {
        "month": "text",
        "year": "text"
      }
    },
    "openBanking": {
      "iban": "text",
      "bankId": "text"
    }
  },
  "preferredCountry": "text",
  "createdAt": "2025-07-07T02:35:17.825Z",
  "basket": {
    "subtotalAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "salesTaxAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "shippingAmount": {
      "currency": "EUR",
      "amount": 5877.78
    },
    "items": [
      {
        "name": "text",
        "quantity": 1,
        "price": {
          "currency": "EUR",
          "amount": 5877.78
        },
        "imageUrl": "text"
      }
    ]
  },
  "_links": {
    "checkoutRedirect": {
      "href": "text"
    },
    "shopRedirect": {
      "href": "text"
    }
  }
}

Captures an existing payment

patch

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

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

The request for capturing an existing payment

Responses

200

OK

application/json

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

patch

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

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

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

Cancels a payment

patch

A payment can be cancelled when it is initialized or authorized

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

The request for cancelling a payment

reasonstring · enumOptional

Reason to cancel the payment

Possible values:

Responses

200

OK

application/json

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

503

Service Unavailable

application/json

patch

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

{
  "reason": "SUSPECTED_FRAUD"
}

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