# Payment
## Authorizing a payment
> Authorizes a given payment.
```json
{"openapi":"3.0.0","info":{"title":"Payment-Gateway Service","version":"0.0.1"},"tags":[{"name":"Payment"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["payment-gateway.authorize_manage"]}],"components":{"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."}}}}},"responses":{"paymentAuthorizeResponse":{"description":"Payment authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/authorizePaymentResponse"}}}},"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"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_Unprocessable_Entity_422":{"description":"Unprocessable Entity. The payment action is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_InternalServerError_500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"schemas":{"authorizePaymentResponse":{"title":"authorizePaymentResponse","allOf":[{"$ref":"#/components/schemas/initializePaymentResponse"},{"type":"object","properties":{"requiresExternalPayment":{"type":"boolean","description":"Indicates if a redirect to an external site is required in order to finish the authorization flow."}}}]},"initializePaymentResponse":{"title":"initializePaymentResponse","type":"object","properties":{"successful":{"type":"boolean","description":"Indicates if the authorization process finished with success."},"paymentTransactionId":{"type":"string","description":"Unique payment transaction identifier. "},"authorizationToken":{"type":"string","description":"Authorization token"},"externalPaymentRedirectURL":{"type":"string","description":"Indicates a URL address where a user should be redirected in order to finish the authorization process."},"externalPaymentHttpMethod":{"type":"string","description":"Indicates a HTTP Method which should be used in order to finish the authorization process."},"externalPaymentParameters":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of additional parameters that may be needed in order to complete the authorization flow. "}}},"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."}}}}}}]},"authorizePaymentRequest":{"title":"authorizePaymentRequest","allOf":[{"$ref":"#/components/schemas/authorizeFrontendPaymentRequest"},{"type":"object","properties":{"amountToAuthorize":{"type":"number","description":"Amount that should be authorized."},"currency":{"type":"string","description":"Currency for the amount that should be authorized."}}}]},"authorizeFrontendPaymentRequest":{"title":"authorizeFrontendPaymentRequest","allOf":[{"$ref":"#/components/schemas/initializePaymentRequest"},{"type":"object","properties":{"threeDSToken":{"type":"string","description":"Contains a token generated during the 3DS authentication process."},"browserInfo":{"type":"string","description":"Holds information related to the user's web browser."},"clientIP":{"type":"string","description":"Stores the IP address of the client or user making the request."}}}]},"initializePaymentRequest":{"title":"initializePaymentRequest","type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of an order for which the payment should be authorized."}}},"paymentModeId":{"type":"string","description":"Identifier of a payment mode configured in the payment-gateway service for a given tenant."},"creditCardToken":{"type":"string","description":"Indicates a payment method token, usually generated on a frontend site, when an user provides a credit card information."}}}}},"paths":{"/payment-gateway/{tenant}/payment/authorize":{"post":{"summary":"Authorizing a payment","operationId":"POST-payment-gateway-authorize-payment","responses":{"200":{"$ref":"#/components/responses/paymentAuthorizeResponse"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"},"422":{"$ref":"#/components/responses/common_response_Unprocessable_Entity_422"},"500":{"$ref":"#/components/responses/common_response_InternalServerError_500"}},"tags":["Payment"],"description":"Authorizes a given payment. \n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/authorizePaymentRequest"}}}}}}}}
```
## Capturing a payment
> Creates a flow to capture a given payment transaction. The capture operation requires transactionId, thus it can be invoked only if the payment had been previously authorized.
```json
{"openapi":"3.0.0","info":{"title":"Payment-Gateway Service","version":"0.0.1"},"tags":[{"name":"Payment"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["payment-gateway.capture_manage"]}],"components":{"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."}}}}},"responses":{"paymentCaptureResponse":{"description":"Payment capture response","content":{"application/json":{"schema":{"type":"object","properties":{"successful":{"type":"boolean","description":"Indicates if the operation finished with success or not.\n"},"message":{"type":"string","description":"In case of failed operation, the field provides error details.\n"},"captureId":{"type":"string","description":"Identifier of a capture operation that is returned by a payment provider."}}}}}},"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"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_NotFound_404":{"description":"Not found. The resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_Unprocessable_Entity_422":{"description":"Unprocessable Entity. The payment action is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_InternalServerError_500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"schemas":{"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."}}}}}}]},"captureRequest":{"title":"captureRequest","type":"object","properties":{"amount":{"type":"number","description":"Amount that should be captured. The amount should not be greater than amount that was authorized."},"currency":{"type":"string","description":"Currency for the amount that should be captured."}}}}},"paths":{"/payment-gateway/{tenant}/payment/{transactionId}/capture":{"post":{"summary":"Capturing a payment","operationId":"POST-payment-gateway-capture-payment","responses":{"200":{"$ref":"#/components/responses/paymentCaptureResponse"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/common_response_NotFound_404"},"422":{"$ref":"#/components/responses/common_response_Unprocessable_Entity_422"},"500":{"$ref":"#/components/responses/common_response_InternalServerError_500"}},"tags":["Payment"],"description":"Creates a flow to capture a given payment transaction. The capture operation requires transactionId, thus it can be invoked only if the payment had been previously authorized. \n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/captureRequest"}}}}}}}}
```
## Refunding a payment
> Creates a flow to return a given payment. The refund operation requires transactionId, thus it can be invoked only if the payment has been authorized and captured previously.
```json
{"openapi":"3.0.0","info":{"title":"Payment-Gateway Service","version":"0.0.1"},"tags":[{"name":"Payment"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["payment-gateway.refund_manage"]}],"components":{"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."}}}}},"responses":{"commonPaymentResponse":{"description":"Payment transaction response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commonPaymentResponse"}}}},"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"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_NotFound_404":{"description":"Not found. The resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_Unprocessable_Entity_422":{"description":"Unprocessable Entity. The payment action is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_InternalServerError_500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"schemas":{"commonPaymentResponse":{"title":"commonPaymentResponse","type":"object","properties":{"successful":{"type":"boolean","description":"Indicates if the operation finished with success or not."},"message":{"type":"string","description":"In case of failed operation, the field provides error details."}}},"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."}}}}}}]},"refundRequest":{"title":"refundRequest","type":"object","properties":{"amount":{"type":"number","description":"Amount that should be refunded. The amount should not be greater than amount that was captured."},"currency":{"type":"string","description":"Currency for the amount that should be refunded."},"captureId":{"type":"string","description":"Capture identifier. The value is mandatory only if there were more captures for a payment and the refund should be related to a specific capture. In another case the value can be skipped and the capture related to the payment will be chosen automatically."}}}}},"paths":{"/payment-gateway/{tenant}/payment/{transactionId}/refund":{"post":{"summary":"Refunding a payment","operationId":"POST-payment-gateway-refund-payment","responses":{"200":{"$ref":"#/components/responses/commonPaymentResponse"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/common_response_NotFound_404"},"422":{"$ref":"#/components/responses/common_response_Unprocessable_Entity_422"},"500":{"$ref":"#/components/responses/common_response_InternalServerError_500"}},"tags":["Payment"],"description":"Creates a flow to return a given payment. The refund operation requires transactionId, thus it can be invoked only if the payment has been authorized and captured previously. \n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/refundRequest"}}}}}}}}
```
## Cancelling a payment
> Creates a flow to cancel a given payment transaction. The cancel operation requires transactionId, thus it can be invoked only if the payment has been authorized previously.
```json
{"openapi":"3.0.0","info":{"title":"Payment-Gateway Service","version":"0.0.1"},"tags":[{"name":"Payment"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["payment-gateway.cancel_manage"]}],"components":{"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."}}}}},"responses":{"commonPaymentResponse":{"description":"Payment transaction response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commonPaymentResponse"}}}},"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"}}}}}}}}}},"common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_NotFound_404":{"description":"Not found. The resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_Unprocessable_Entity_422":{"description":"Unprocessable Entity. The payment action is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}},"common_response_InternalServerError_500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/coreErrorMessage"}}}}},"schemas":{"commonPaymentResponse":{"title":"commonPaymentResponse","type":"object","properties":{"successful":{"type":"boolean","description":"Indicates if the operation finished with success or not."},"message":{"type":"string","description":"In case of failed operation, the field provides error details."}}},"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."}}}}}}]}}},"paths":{"/payment-gateway/{tenant}/payment/{transactionId}/cancel":{"post":{"summary":"Cancelling a payment","operationId":"POST-payment-gateway-cancel-payment","responses":{"200":{"$ref":"#/components/responses/commonPaymentResponse"},"401":{"$ref":"#/components/responses/common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/common_response_NotFound_404"},"422":{"$ref":"#/components/responses/common_response_Unprocessable_Entity_422"},"500":{"$ref":"#/components/responses/common_response_InternalServerError_500"}},"tags":["Payment"],"description":"Creates a flow to cancel a given payment transaction. The cancel operation requires transactionId, thus it can be invoked only if the payment has been authorized previously. \n"}}}}
```
---
# 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://developer.emporix.io/api-references-1/readme/api-reference-24/payment.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.