# Pagos
## Create a new customer-initiated payment
> 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.
```json
{"openapi":"3.1.0","info":{"title":"E-commerce Gateway API","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.ecomm.api.tietoevry.com"}],"security":[{"OAuth2ClientAuthentication":[]}],"components":{"securitySchemes":{"OAuth2ClientAuthentication":{"type":"openIdConnect","description":"This API uses OAuth 2 with the client credentials flow. [More info](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)","openIdConnectUrl":"https://ecomm.api.tietoevry.com/auth/realms/participants-tietoevry/protocol/openid-connect/token"}},"schemas":{"InitiateCitPaymentRequest":{"type":"object","properties":{"basket":{"$ref":"#/components/schemas/BasketDto"},"billingAddress":{"$ref":"#/components/schemas/AddressDto","description":"Billing address, used for fraud prevention and 3D Secure"},"channel":{"type":"string","description":"Identifies the method or channel through which a payment was initiated:\n\n* BROWSER - payment initiated when the customer makes a regular online purchase via a website (e-shop)\n","enum":["BROWSER"]},"customer":{"$ref":"#/components/schemas/CustomerDto","description":"Customer details, used for fraud prevention and 3D Secure"},"description":{"type":"string","description":"Description of the payment","maxLength":255,"minLength":0},"instructedAmount":{"$ref":"#/components/schemas/Amount","description":"Payment amount"},"merchantReference":{"type":"string","description":"Merchant's payment reference","maxLength":255,"minLength":0},"orderNumber":{"type":"string","description":"Merchant's order number","maxLength":255,"minLength":0,"pattern":"^[a-zA-Z0-9/-?:().,'+\\-]*$"},"participantId":{"type":"string","description":"Unique ID of the participant","maxLength":64},"preferredCountry":{"type":"string","description":"Default country for bank selection in the gateway hosted checkout page"},"preferredLocale":{"type":"string","description":"Default locale for the gateway hosted checkout page","enum":["cz","da","nl","en","et","fi","fr","de","hu","it","lv","lt","no","pl","pt","ru","sk","es","sv","ua"]},"setupToken":{"$ref":"#/components/schemas/SetupToken","description":"Indicates the type of token that will be set up during this payment"},"shippingAddress":{"$ref":"#/components/schemas/AddressDto","description":"Shipping address, used for fraud prevention and 3D Secure"},"shopAgreementId":{"type":"string","description":"Unique ID of the shop","maxLength":64},"shopRedirectUrl":{"type":"string","minLength":1}},"required":["channel","instructedAmount","orderNumber","participantId","shopAgreementId","shopRedirectUrl"],"title":"Payment Initiation Request"},"BasketDto":{"type":"object","description":"Basket containing detailed information about items to be purchased","properties":{"items":{"type":"array","description":"List of items to be purchased","items":{"$ref":"#/components/schemas/Item"},"minItems":1},"salesTaxAmount":{"$ref":"#/components/schemas/Amount","description":"Total amount for sales taxes (excluding shipping)"},"shippingAmount":{"$ref":"#/components/schemas/Amount","description":"Total amount for shipping"},"subtotalAmount":{"$ref":"#/components/schemas/Amount","description":"Subtotal amount, excluding sales taxes and shipping (calculated, if missing)"}},"required":["items"]},"Item":{"type":"object","description":"Detailed information about the item in the basket","properties":{"description":{"type":"string","description":"Description of the item","maxLength":512,"minLength":0},"imageUrl":{"type":"string","description":"URL to the image of the item, to be displayed in the gateway hosted checkout page"},"name":{"type":"string","description":"Name of the item","minLength":1},"price":{"$ref":"#/components/schemas/Amount","description":"Individual price of the item (including taxes)"},"quantity":{"type":"integer","format":"int32","description":"Quantity of the item","minimum":1},"sku":{"type":"string","description":"The SKU (Stock Keeping Unit) that identifies the item in the merchant's inventory system","maxLength":64,"minLength":0},"taxRate":{"type":"number"},"totalPrice":{"$ref":"#/components/schemas/Amount","description":"Total price of all items (calculated, if missing)"}},"required":["name","price","quantity"]},"Amount":{"type":"object","properties":{"amount":{"type":"string","description":"The amount given with fractional digits, where fractions must be compliant to the currency definition.\nUp to 14 significant figures. The decimal separator is a dot.\nCan be 0 for account verification (save payment method for future usage without initial payment).\n\n**Example:**\nValid representations for EUR with up to two decimals are:\n * 1056\n * 5768.2\n * 1.50\n * 5877.78\n"},"currency":{"type":"object","description":"ISO 4217 alpha-3 currency code","properties":{"currencyCode":{"type":"string"},"defaultFractionDigits":{"type":"integer","format":"int32"},"displayName":{"type":"string"},"numericCode":{"type":"integer","format":"int32"},"numericCodeAsString":{"type":"string"},"symbol":{"type":"string"}}}},"required":["amount","currency"]},"AddressDto":{"type":"object","properties":{"addressLine1":{"type":"string","maxLength":255,"minLength":0},"addressLine2":{"type":"string","maxLength":255,"minLength":0},"city":{"type":"string","maxLength":255,"minLength":0},"country":{"type":"string","description":"Country code in ISO 3166-1 alpha-2 format"},"postalCode":{"type":"string","maxLength":255,"minLength":0},"state":{"type":"string","maxLength":255,"minLength":0}}},"CustomerDto":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The customer's email address","maxLength":255,"minLength":0},"name":{"type":"string","description":"The customer's full name or business name","maxLength":255,"minLength":0},"phone":{"type":"string","description":"The customer's mobile phone number in international format (with '+' and country code)"}}},"SetupToken":{"type":"object","properties":{"purposes":{"type":"array","description":"The purpose for which the token will be used in subsequent payments:\n* CIT - cardholder-initiated ad-hoc payments with variable amount and undefined frequency\n* UNSCHEDULED - merchant-initiated ad-hoc payments with variable amount and undefined frequency\n* SUBSCRIPTION - merchant-initiated recurring payments with fixed amount and frequency\n* STANDING_ORDER - merchant-initiated recurring payments with variable amount, but fixed frequency\n","items":{"type":"string","enum":["CIT","UNSCHEDULED","SUBSCRIPTION","STANDING_ORDER"]},"minItems":1,"uniqueItems":true},"required":{"type":"boolean","description":"Indicates whether setting up a token during the payment is required or optional.\n\nWhen `true` (default), setting up a token is mandatory.\nIn this case, only payment methods that support tokenization can be used to complete the payment.\nThis would commonly be used for scenarios like subscriptions, where saving payment method details is essential.\n\nWhen `false`, setting up a token is optional, allowing the customer to decide whether to save their payment method details for future use when the selected payment method supports tokenization.\nTypically this would be used to offer customers the option to save their payment method details for faster checkout in future cardholder-initiated payments.\n"}},"required":["purposes"]},"InitiatePaymentResponse":{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/InitiatePaymentResponse.Links"},"availablePaymentMethods":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ApplePayPaymentMethod"},{"$ref":"#/components/schemas/CardPaymentMethod"},{"$ref":"#/components/schemas/ClickToPayPaymentMethod"},{"$ref":"#/components/schemas/GooglePayPaymentMethod"},{"$ref":"#/components/schemas/OpenBankingPaymentMethod"},{"$ref":"#/components/schemas/PayPalPaymentMethod"}]}},"basket":{"$ref":"#/components/schemas/BasketDto"},"createdAt":{"type":"string","format":"date-time"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"instructedAmount":{"$ref":"#/components/schemas/Amount"},"orderNumber":{"type":"string"},"participantId":{"type":"string","description":"Unique ID of the participant","maxLength":64},"paymentId":{"type":"string","description":"Unique ID of the payment","maxLength":64},"paymentStatus":{"type":"string","enum":["INITIALIZED","SENT_FOR_PROCESSING","ABANDONED","AUTHORIZED","CAPTURED","CANCELLED","SETTLED","FAILED","REFUNDED"]},"shop":{"$ref":"#/components/schemas/ShopDto"}}},"InitiatePaymentResponse.Links":{"type":"object","properties":{"checkoutRedirect":{"$ref":"#/components/schemas/Link"}}},"Link":{"type":"object","properties":{"href":{"type":"string"}}},"ApplePayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["APPLE_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"AvailablePaymentMethodDto":{"discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"required":["type"]},"ShopPaymentMethodDto":{"discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"required":["type"]},"CardPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"type":{"type":"string","enum":["CARD"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"type":{"type":"string","enum":["CARD"]}}}]},"PaymentMethodDto.Links":{"type":"object","properties":{"checkoutRedirect":{"$ref":"#/components/schemas/Link"}}},"ClickToPayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nThis field is only included in responses when using the sandbox environment.\n"},"srcDpaId":{"type":"string"},"type":{"type":"string","enum":["CLICK_TO_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"srcDpaId":{"type":"string"},"type":{"type":"string","enum":["CLICK_TO_PAY"]}}}]},"GooglePayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["GOOGLE_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"OpenBankingPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"banks":{"type":"array","items":{"$ref":"#/components/schemas/BankDto"}},"type":{"type":"string","enum":["OPEN_BANKING"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"banks":{"type":"array","items":{"$ref":"#/components/schemas/BankDto"}},"type":{"type":"string","enum":["OPEN_BANKING"]}}}]},"BankDto":{"type":"object","properties":{"bankId":{"type":"string"},"color":{"type":"string"},"country":{"type":"string"},"logo":{"type":"string"},"name":{"type":"string"},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this bank is available in the sandbox environment.\nThis field is only included in responses when using the sandbox environment.\n"}}},"PayPalPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["PAYPAL"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"ShopDto":{"type":"object","properties":{"agreementId":{"type":"string","description":"Unique ID of the shop","maxLength":64},"country":{"type":"string"},"name":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"apiClientMessages":{"type":"array","items":{"$ref":"#/components/schemas/ApiClientMessage"}}}},"ApiClientMessage":{"type":"object","properties":{"category":{"type":"string","enum":["ERROR"]},"code":{"type":"string"},"text":{"type":"string"}}}}},"paths":{"/egw/{version}/payments/cit":{"post":{"description":"Creates a new customer-initiated payment.\n\nAfter a payment is created a payment method (card, bank, saved token) must be added to it.\nThe user can attempt adding payment method multiple times until ultimately one is successful.\nThe checkout process is continued by either\nredirecting the user to the gateway hosted checkout page or integrating directly with EGW APIs.\n\nAdditionally, the `setupToken` fields can be used to save the used payment method for future payments.\n","operationId":"initiateCitPayment","parameters":[{"description":"ID of the request, unique to the call, as determined by the initiating party","in":"header","name":"X-Request-Id","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the request, unique to the call, as determined by the initiating party"}},{"in":"path","name":"version","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateCitPaymentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiatePaymentResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Conflict"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"}},"summary":"Create a new customer-initiated payment","tags":["Payment API"]}}}}
```
## Create a new merchant-initiated payment
> 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.
```json
{"openapi":"3.1.0","info":{"title":"E-commerce Gateway API","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.ecomm.api.tietoevry.com"}],"security":[{"OAuth2ClientAuthentication":[]}],"components":{"securitySchemes":{"OAuth2ClientAuthentication":{"type":"openIdConnect","description":"This API uses OAuth 2 with the client credentials flow. [More info](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)","openIdConnectUrl":"https://ecomm.api.tietoevry.com/auth/realms/participants-tietoevry/protocol/openid-connect/token"}},"schemas":{"InitiateMitPaymentRequest":{"type":"object","properties":{"basket":{"$ref":"#/components/schemas/BasketDto"},"billingAddress":{"$ref":"#/components/schemas/AddressDto","description":"Billing address, used for fraud prevention and 3D Secure"},"channel":{"type":"string","description":"Identifies the method or channel through which a payment was initiated:\n\n* 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)\n* 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)\n","enum":["RECURRING","MERCHANT"]},"customer":{"$ref":"#/components/schemas/CustomerDto","description":"Customer details, used for fraud prevention and 3D Secure"},"description":{"type":"string","description":"Description of the payment","maxLength":255,"minLength":0},"instructedAmount":{"$ref":"#/components/schemas/Amount","description":"Payment amount"},"merchantReference":{"type":"string","description":"Merchant's payment reference","maxLength":255,"minLength":0},"orderNumber":{"type":"string","description":"Merchant's order number","maxLength":255,"minLength":0,"pattern":"^[a-zA-Z0-9/-?:().,'+\\-]*$"},"participantId":{"type":"string","description":"Unique ID of the participant","maxLength":64},"shippingAddress":{"$ref":"#/components/schemas/AddressDto","description":"Shipping address, used for fraud prevention and 3D Secure"},"shopAgreementId":{"type":"string","description":"Unique ID of the shop","maxLength":64}},"required":["channel","instructedAmount","orderNumber","participantId","shopAgreementId"],"title":"Payment Initiation Request"},"BasketDto":{"type":"object","description":"Basket containing detailed information about items to be purchased","properties":{"items":{"type":"array","description":"List of items to be purchased","items":{"$ref":"#/components/schemas/Item"},"minItems":1},"salesTaxAmount":{"$ref":"#/components/schemas/Amount","description":"Total amount for sales taxes (excluding shipping)"},"shippingAmount":{"$ref":"#/components/schemas/Amount","description":"Total amount for shipping"},"subtotalAmount":{"$ref":"#/components/schemas/Amount","description":"Subtotal amount, excluding sales taxes and shipping (calculated, if missing)"}},"required":["items"]},"Item":{"type":"object","description":"Detailed information about the item in the basket","properties":{"description":{"type":"string","description":"Description of the item","maxLength":512,"minLength":0},"imageUrl":{"type":"string","description":"URL to the image of the item, to be displayed in the gateway hosted checkout page"},"name":{"type":"string","description":"Name of the item","minLength":1},"price":{"$ref":"#/components/schemas/Amount","description":"Individual price of the item (including taxes)"},"quantity":{"type":"integer","format":"int32","description":"Quantity of the item","minimum":1},"sku":{"type":"string","description":"The SKU (Stock Keeping Unit) that identifies the item in the merchant's inventory system","maxLength":64,"minLength":0},"taxRate":{"type":"number"},"totalPrice":{"$ref":"#/components/schemas/Amount","description":"Total price of all items (calculated, if missing)"}},"required":["name","price","quantity"]},"Amount":{"type":"object","properties":{"amount":{"type":"string","description":"The amount given with fractional digits, where fractions must be compliant to the currency definition.\nUp to 14 significant figures. The decimal separator is a dot.\nCan be 0 for account verification (save payment method for future usage without initial payment).\n\n**Example:**\nValid representations for EUR with up to two decimals are:\n * 1056\n * 5768.2\n * 1.50\n * 5877.78\n"},"currency":{"type":"object","description":"ISO 4217 alpha-3 currency code","properties":{"currencyCode":{"type":"string"},"defaultFractionDigits":{"type":"integer","format":"int32"},"displayName":{"type":"string"},"numericCode":{"type":"integer","format":"int32"},"numericCodeAsString":{"type":"string"},"symbol":{"type":"string"}}}},"required":["amount","currency"]},"AddressDto":{"type":"object","properties":{"addressLine1":{"type":"string","maxLength":255,"minLength":0},"addressLine2":{"type":"string","maxLength":255,"minLength":0},"city":{"type":"string","maxLength":255,"minLength":0},"country":{"type":"string","description":"Country code in ISO 3166-1 alpha-2 format"},"postalCode":{"type":"string","maxLength":255,"minLength":0},"state":{"type":"string","maxLength":255,"minLength":0}}},"CustomerDto":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The customer's email address","maxLength":255,"minLength":0},"name":{"type":"string","description":"The customer's full name or business name","maxLength":255,"minLength":0},"phone":{"type":"string","description":"The customer's mobile phone number in international format (with '+' and country code)"}}},"InitiatePaymentResponse":{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/InitiatePaymentResponse.Links"},"availablePaymentMethods":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ApplePayPaymentMethod"},{"$ref":"#/components/schemas/CardPaymentMethod"},{"$ref":"#/components/schemas/ClickToPayPaymentMethod"},{"$ref":"#/components/schemas/GooglePayPaymentMethod"},{"$ref":"#/components/schemas/OpenBankingPaymentMethod"},{"$ref":"#/components/schemas/PayPalPaymentMethod"}]}},"basket":{"$ref":"#/components/schemas/BasketDto"},"createdAt":{"type":"string","format":"date-time"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"instructedAmount":{"$ref":"#/components/schemas/Amount"},"orderNumber":{"type":"string"},"participantId":{"type":"string","description":"Unique ID of the participant","maxLength":64},"paymentId":{"type":"string","description":"Unique ID of the payment","maxLength":64},"paymentStatus":{"type":"string","enum":["INITIALIZED","SENT_FOR_PROCESSING","ABANDONED","AUTHORIZED","CAPTURED","CANCELLED","SETTLED","FAILED","REFUNDED"]},"shop":{"$ref":"#/components/schemas/ShopDto"}}},"InitiatePaymentResponse.Links":{"type":"object","properties":{"checkoutRedirect":{"$ref":"#/components/schemas/Link"}}},"Link":{"type":"object","properties":{"href":{"type":"string"}}},"ApplePayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["APPLE_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"AvailablePaymentMethodDto":{"discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"required":["type"]},"ShopPaymentMethodDto":{"discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"required":["type"]},"CardPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"type":{"type":"string","enum":["CARD"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"type":{"type":"string","enum":["CARD"]}}}]},"PaymentMethodDto.Links":{"type":"object","properties":{"checkoutRedirect":{"$ref":"#/components/schemas/Link"}}},"ClickToPayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nThis field is only included in responses when using the sandbox environment.\n"},"srcDpaId":{"type":"string"},"type":{"type":"string","enum":["CLICK_TO_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"srcDpaId":{"type":"string"},"type":{"type":"string","enum":["CLICK_TO_PAY"]}}}]},"GooglePayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["GOOGLE_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"OpenBankingPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"banks":{"type":"array","items":{"$ref":"#/components/schemas/BankDto"}},"type":{"type":"string","enum":["OPEN_BANKING"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"banks":{"type":"array","items":{"$ref":"#/components/schemas/BankDto"}},"type":{"type":"string","enum":["OPEN_BANKING"]}}}]},"BankDto":{"type":"object","properties":{"bankId":{"type":"string"},"color":{"type":"string"},"country":{"type":"string"},"logo":{"type":"string"},"name":{"type":"string"},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this bank is available in the sandbox environment.\nThis field is only included in responses when using the sandbox environment.\n"}}},"PayPalPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["PAYPAL"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"ShopDto":{"type":"object","properties":{"agreementId":{"type":"string","description":"Unique ID of the shop","maxLength":64},"country":{"type":"string"},"name":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"apiClientMessages":{"type":"array","items":{"$ref":"#/components/schemas/ApiClientMessage"}}}},"ApiClientMessage":{"type":"object","properties":{"category":{"type":"string","enum":["ERROR"]},"code":{"type":"string"},"text":{"type":"string"}}}}},"paths":{"/egw/{version}/payments/mit":{"post":{"description":"Creates a new merchant-initiated payment - payment without direct involvement of the end user (e.g. subscriptions).\n\nOnly previously saved payment method token can be used for merchant-initiated payments.\nBefore creating merchant-initiated payments it is necessary to setup a token agreement during an initial customer-initiated payment.\n","operationId":"initiateMitPayment","parameters":[{"description":"ID of the request, unique to the call, as determined by the initiating party","in":"header","name":"X-Request-Id","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the request, unique to the call, as determined by the initiating party"}},{"in":"path","name":"version","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateMitPaymentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiatePaymentResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Conflict"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"}},"summary":"Create a new merchant-initiated payment","tags":["Payment API"]}}}}
```
## Get payment information
> Returns the content of a payment object
```json
{"openapi":"3.1.0","info":{"title":"E-commerce Gateway API","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.ecomm.api.tietoevry.com"}],"security":[{"OAuth2ClientAuthentication":[]}],"components":{"securitySchemes":{"OAuth2ClientAuthentication":{"type":"openIdConnect","description":"This API uses OAuth 2 with the client credentials flow. [More info](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)","openIdConnectUrl":"https://ecomm.api.tietoevry.com/auth/realms/participants-tietoevry/protocol/openid-connect/token"}},"schemas":{"PaymentInformationQueryParams":{"type":"object","description":"Optional query parameters to include additional information","properties":{"withCheckoutBranding":{"type":"boolean","description":"Boolean flag whether to include checkout branding information"}}},"PaymentInformationResponse":{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentInformationResponse.Links"},"availablePaymentMethods":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ApplePayPaymentMethod"},{"$ref":"#/components/schemas/CardPaymentMethod"},{"$ref":"#/components/schemas/ClickToPayPaymentMethod"},{"$ref":"#/components/schemas/GooglePayPaymentMethod"},{"$ref":"#/components/schemas/OpenBankingPaymentMethod"},{"$ref":"#/components/schemas/PayPalPaymentMethod"}]}},"basket":{"$ref":"#/components/schemas/BasketDto"},"channel":{"type":"string","description":"Identifies the method or channel through which a payment was initiated:\n\n* BROWSER - payment initiated when the customer makes a regular online purchase via a website (e-shop)\n* 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)\n* 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)\n* 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)\n* QR_CODE - payment initiated when the customer scans a QR code presented by the merchant (e.g., in-store or on-screen)\n","enum":["BROWSER","RECURRING","MERCHANT","PAYMENT_LINK","QR_CODE"]},"checkoutBranding":{"$ref":"#/components/schemas/CheckoutBrandingDto"},"createdAt":{"type":"string","format":"date-time"},"customer":{"$ref":"#/components/schemas/CustomerDto"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"instructedAmount":{"$ref":"#/components/schemas/Amount"},"merchantReference":{"type":"string","description":"Merchant's payment reference"},"orderNumber":{"type":"string","description":"Merchant's order number"},"participantId":{"type":"string","description":"Unique ID of the participant","maxLength":64},"paymentId":{"type":"string","description":"Unique ID of the payment","maxLength":64},"paymentLinkId":{"type":"string","maxLength":64},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethodDto"},"paymentStatus":{"type":"string","enum":["INITIALIZED","SENT_FOR_PROCESSING","ABANDONED","AUTHORIZED","CAPTURED","CANCELLED","SETTLED","FAILED","REFUNDED"]},"preferredCountry":{"type":"string"},"refundedAmount":{"$ref":"#/components/schemas/Amount"},"shop":{"$ref":"#/components/schemas/ShopDto"}}},"PaymentInformationResponse.Links":{"type":"object","properties":{"checkoutRedirect":{"$ref":"#/components/schemas/Link"},"shopRedirect":{"$ref":"#/components/schemas/Link"}}},"Link":{"type":"object","properties":{"href":{"type":"string"}}},"ApplePayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["APPLE_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"AvailablePaymentMethodDto":{"discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"required":["type"]},"ShopPaymentMethodDto":{"discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"required":["type"]},"CardPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"type":{"type":"string","enum":["CARD"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"type":{"type":"string","enum":["CARD"]}}}]},"PaymentMethodDto.Links":{"type":"object","properties":{"checkoutRedirect":{"$ref":"#/components/schemas/Link"}}},"ClickToPayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nThis field is only included in responses when using the sandbox environment.\n"},"srcDpaId":{"type":"string"},"type":{"type":"string","enum":["CLICK_TO_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"brands":{"type":"array","items":{"type":"string","enum":["VISA","MASTERCARD"]},"uniqueItems":true},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this payment method is available in the sandbox environment.\nNote: this field is only returned in the sandbox environment.\n"},"srcDpaId":{"type":"string"},"type":{"type":"string","enum":["CLICK_TO_PAY"]}}}]},"GooglePayPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["GOOGLE_PAY"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"OpenBankingPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"_links":{"$ref":"#/components/schemas/PaymentMethodDto.Links"},"banks":{"type":"array","items":{"$ref":"#/components/schemas/BankDto"}},"type":{"type":"string","enum":["OPEN_BANKING"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"},{"type":"object","properties":{"banks":{"type":"array","items":{"$ref":"#/components/schemas/BankDto"}},"type":{"type":"string","enum":["OPEN_BANKING"]}}}]},"BankDto":{"type":"object","properties":{"bankId":{"type":"string"},"color":{"type":"string"},"country":{"type":"string"},"logo":{"type":"string"},"name":{"type":"string"},"sandboxAvailable":{"type":"boolean","description":"Indicates whether this bank is available in the sandbox environment.\nThis field is only included in responses when using the sandbox environment.\n"}}},"PayPalPaymentMethod":{"allOf":[{"$ref":"#/components/schemas/AvailablePaymentMethodDto"},{"type":"object","properties":{"type":{"type":"string","enum":["PAYPAL"]}}},{"$ref":"#/components/schemas/ShopPaymentMethodDto"}]},"BasketDto":{"type":"object","description":"Basket containing detailed information about items to be purchased","properties":{"items":{"type":"array","description":"List of items to be purchased","items":{"$ref":"#/components/schemas/Item"},"minItems":1},"salesTaxAmount":{"$ref":"#/components/schemas/Amount","description":"Total amount for sales taxes (excluding shipping)"},"shippingAmount":{"$ref":"#/components/schemas/Amount","description":"Total amount for shipping"},"subtotalAmount":{"$ref":"#/components/schemas/Amount","description":"Subtotal amount, excluding sales taxes and shipping (calculated, if missing)"}},"required":["items"]},"Item":{"type":"object","description":"Detailed information about the item in the basket","properties":{"description":{"type":"string","description":"Description of the item","maxLength":512,"minLength":0},"imageUrl":{"type":"string","description":"URL to the image of the item, to be displayed in the gateway hosted checkout page"},"name":{"type":"string","description":"Name of the item","minLength":1},"price":{"$ref":"#/components/schemas/Amount","description":"Individual price of the item (including taxes)"},"quantity":{"type":"integer","format":"int32","description":"Quantity of the item","minimum":1},"sku":{"type":"string","description":"The SKU (Stock Keeping Unit) that identifies the item in the merchant's inventory system","maxLength":64,"minLength":0},"taxRate":{"type":"number"},"totalPrice":{"$ref":"#/components/schemas/Amount","description":"Total price of all items (calculated, if missing)"}},"required":["name","price","quantity"]},"Amount":{"type":"object","properties":{"amount":{"type":"string","description":"The amount given with fractional digits, where fractions must be compliant to the currency definition.\nUp to 14 significant figures. The decimal separator is a dot.\nCan be 0 for account verification (save payment method for future usage without initial payment).\n\n**Example:**\nValid representations for EUR with up to two decimals are:\n * 1056\n * 5768.2\n * 1.50\n * 5877.78\n"},"currency":{"type":"object","description":"ISO 4217 alpha-3 currency code","properties":{"currencyCode":{"type":"string"},"defaultFractionDigits":{"type":"integer","format":"int32"},"displayName":{"type":"string"},"numericCode":{"type":"integer","format":"int32"},"numericCodeAsString":{"type":"string"},"symbol":{"type":"string"}}}},"required":["amount","currency"]},"CheckoutBrandingDto":{"type":"object","properties":{"basketItemPlaceholder":{"type":"string"},"buttonRadius":{"type":"string"},"color":{"type":"string"},"disabledOptions":{"type":"array","items":{"type":"string","enum":["CARD","OPEN_BANKING","CLICK_TO_PAY","APPLE_PAY","GOOGLE_PAY","PAYPAL"]}},"font":{"type":"string"},"groupOrder":{"type":"array","items":{"type":"string","enum":["WALLETS","PAYMENTS","ALL"]}},"groupingType":{"type":"string","enum":["NO_GROUPING","BY_TYPE","SEPARATE_FIRST","SEPARATE_USED"]},"logo":{"type":"string"},"logoPlaceholder":{"type":"string"},"paymentOptionOrder":{"type":"array","items":{"type":"string","enum":["CARD","OPEN_BANKING","CLICK_TO_PAY","APPLE_PAY","GOOGLE_PAY","PAYPAL"]}},"secondaryColor":{"type":"string"}}},"CustomerDto":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The customer's email address","maxLength":255,"minLength":0},"name":{"type":"string","description":"The customer's full name or business name","maxLength":255,"minLength":0},"phone":{"type":"string","description":"The customer's mobile phone number in international format (with '+' and country code)"}}},"PaymentMethodDto":{"type":"object","properties":{"card":{"$ref":"#/components/schemas/CardMethod"},"gatewayTokenId":{"type":"string","description":"Unique ID of the token","maxLength":64},"openBanking":{"$ref":"#/components/schemas/OpenBankingMethod"},"type":{"type":"string","enum":["CARD","OPEN_BANKING","CLICK_TO_PAY","APPLE_PAY","GOOGLE_PAY","PAYPAL"]}}},"CardMethod":{"type":"object","properties":{"brand":{"type":"string","enum":["VISA","MASTERCARD"]},"cardholderName":{"type":"string"},"expiry":{"$ref":"#/components/schemas/CardExpiry"},"lastFourDigits":{"type":"string"}}},"CardExpiry":{"type":"object","properties":{"month":{"type":"string","description":"Month of the expiry date (in format MM)","pattern":"^(0[1-9]|1[0-2])$"},"year":{"type":"string","description":"Year of the expiry date (in format YY)","pattern":"^\\d{2}$"}},"required":["month","year"]},"OpenBankingMethod":{"type":"object","properties":{"bankId":{"type":"string"},"iban":{"type":"string"}}},"ShopDto":{"type":"object","properties":{"agreementId":{"type":"string","description":"Unique ID of the shop","maxLength":64},"country":{"type":"string"},"name":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"apiClientMessages":{"type":"array","items":{"$ref":"#/components/schemas/ApiClientMessage"}}}},"ApiClientMessage":{"type":"object","properties":{"category":{"type":"string","enum":["ERROR"]},"code":{"type":"string"},"text":{"type":"string"}}}}},"paths":{"/egw/{version}/payments/{paymentId}":{"get":{"description":"Returns the content of a payment object","operationId":"getPaymentInformation","parameters":[{"description":"ID of the request, unique to the call, as determined by the initiating party","in":"header","name":"X-Request-Id","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the request, unique to the call, as determined by the initiating party"}},{"description":"Unique ID of the payment","in":"path","name":"paymentId","required":true,"schema":{"type":"string","description":"Unique ID of the payment","maxLength":64}},{"in":"query","name":"queryParams","required":true,"schema":{"$ref":"#/components/schemas/PaymentInformationQueryParams"}},{"in":"path","name":"version","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentInformationResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Conflict"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"}},"summary":"Get payment information","tags":["Payment API"]}}}}
```
## Captures an existing payment
> Capturing an authorized payment will complete (finalise) the payment, this is only used for card payments
```json
{"openapi":"3.1.0","info":{"title":"E-commerce Gateway API","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.ecomm.api.tietoevry.com"}],"security":[{"OAuth2ClientAuthentication":[]}],"components":{"securitySchemes":{"OAuth2ClientAuthentication":{"type":"openIdConnect","description":"This API uses OAuth 2 with the client credentials flow. [More info](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)","openIdConnectUrl":"https://ecomm.api.tietoevry.com/auth/realms/participants-tietoevry/protocol/openid-connect/token"}},"schemas":{"CapturePaymentRequest":{"type":"object","description":"The request for capturing an existing payment","properties":{"instructedAmount":{"$ref":"#/components/schemas/Amount","description":"Amount to be captured"}},"required":["instructedAmount"],"title":"Capture Payment Request"},"Amount":{"type":"object","properties":{"amount":{"type":"string","description":"The amount given with fractional digits, where fractions must be compliant to the currency definition.\nUp to 14 significant figures. The decimal separator is a dot.\nCan be 0 for account verification (save payment method for future usage without initial payment).\n\n**Example:**\nValid representations for EUR with up to two decimals are:\n * 1056\n * 5768.2\n * 1.50\n * 5877.78\n"},"currency":{"type":"object","description":"ISO 4217 alpha-3 currency code","properties":{"currencyCode":{"type":"string"},"defaultFractionDigits":{"type":"integer","format":"int32"},"displayName":{"type":"string"},"numericCode":{"type":"integer","format":"int32"},"numericCodeAsString":{"type":"string"},"symbol":{"type":"string"}}}},"required":["amount","currency"]},"CapturePaymentResponse":{"type":"object","description":"The response after capturing a card payment","properties":{"paymentId":{"type":"string","description":"Unique ID of the payment","maxLength":64},"paymentStatus":{"type":"string","description":"Current status of the payment","enum":["INITIALIZED","SENT_FOR_PROCESSING","ABANDONED","AUTHORIZED","CAPTURED","CANCELLED","SETTLED","FAILED","REFUNDED"]}},"title":"Capture Payment Response"},"ErrorResponse":{"type":"object","properties":{"apiClientMessages":{"type":"array","items":{"$ref":"#/components/schemas/ApiClientMessage"}}}},"ApiClientMessage":{"type":"object","properties":{"category":{"type":"string","enum":["ERROR"]},"code":{"type":"string"},"text":{"type":"string"}}}}},"paths":{"/egw/{version}/payments/{paymentId}/capture":{"patch":{"description":"Capturing an authorized payment will complete (finalise) the payment, this is only used for card payments","operationId":"capturePayment","parameters":[{"description":"ID of the request, unique to the call, as determined by the initiating party","in":"header","name":"X-Request-Id","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the request, unique to the call, as determined by the initiating party"}},{"description":"Unique ID of the payment","in":"path","name":"paymentId","required":true,"schema":{"type":"string","description":"Unique ID of the payment","maxLength":64}},{"in":"path","name":"version","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapturePaymentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapturePaymentResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Conflict"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"}},"summary":"Captures an existing payment","tags":["Payment API"]}}}}
```
## Cancels a payment
> A payment can be cancelled when it is initialized or authorized
```json
{"openapi":"3.1.0","info":{"title":"E-commerce Gateway API","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.ecomm.api.tietoevry.com"}],"security":[{"OAuth2ClientAuthentication":[]}],"components":{"securitySchemes":{"OAuth2ClientAuthentication":{"type":"openIdConnect","description":"This API uses OAuth 2 with the client credentials flow. [More info](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)","openIdConnectUrl":"https://ecomm.api.tietoevry.com/auth/realms/participants-tietoevry/protocol/openid-connect/token"}},"schemas":{"CancelPaymentRequest":{"type":"object","description":"The request for cancelling a payment","properties":{"reason":{"type":"string","description":"Reason to cancel the payment","enum":["SUSPECTED_FRAUD","ABANDONED","CUSTOMER_CANCELLED"]}},"title":"Cancel Payment Request"},"CancelPaymentResponse":{"type":"object","description":"The response after cancelling a payment","properties":{"paymentId":{"type":"string","description":"Unique ID of the payment","maxLength":64},"paymentStatus":{"type":"string","description":"Current status of the payment","enum":["INITIALIZED","SENT_FOR_PROCESSING","ABANDONED","AUTHORIZED","CAPTURED","CANCELLED","SETTLED","FAILED","REFUNDED"]}},"title":"Cancel Payment Response"},"ErrorResponse":{"type":"object","properties":{"apiClientMessages":{"type":"array","items":{"$ref":"#/components/schemas/ApiClientMessage"}}}},"ApiClientMessage":{"type":"object","properties":{"category":{"type":"string","enum":["ERROR"]},"code":{"type":"string"},"text":{"type":"string"}}}}},"paths":{"/egw/{version}/payments/{paymentId}/cancel":{"patch":{"description":"A payment can be cancelled when it is initialized or authorized","operationId":"cancelPayment","parameters":[{"description":"ID of the request, unique to the call, as determined by the initiating party","in":"header","name":"X-Request-Id","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the request, unique to the call, as determined by the initiating party"}},{"description":"Unique ID of the payment","in":"path","name":"paymentId","required":true,"schema":{"type":"string","description":"Unique ID of the payment","maxLength":64}},{"in":"path","name":"version","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPaymentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPaymentResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Conflict"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"}},"summary":"Cancels a payment","tags":["Payment API"]}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://doc.ecomm.api.tietoevry.com/documentation-es/referencias-de-la-api/api-para-comerciantes/pagos.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.