> For the complete documentation index, see [llms.txt](https://docs.ecommerce.seb.ee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecommerce.seb.ee/guides/sandbox/test-scenarios/payment-operations.md). # Payment Operations Validate post-payment and authorization operations that the merchant actually intends to use. ## Authorization This section applies to payment methods supporting separate authorization and capture operations. Authorization reserves customer funds without completing the payment. The merchant can capture, partially capture, or cancel it later. Typical use cases include: * Fulfilment after a later date. * Shipping after stock confirmation. * Hotel, travel, pre-order, and reservation bookings. ### Authorization lifecycle Capture completes an authorized payment: ``` Create payment ↓ Customer completes payment ↓ Authorized ↓ Capture ↓ Captured ``` Cancellation releases the authorization: ``` Create payment ↓ Customer completes payment ↓ Authorized ↓ Cancel authorization ↓ Cancelled ``` ### Successful authorization The customer completes payment and the gateway authorizes the amount. #### Validation 1. Create a payment configured for authorization. 2. Complete the customer payment journey. 3. Verify that a callback notification is received. 4. Retrieve the payment details. ```http GET /egw/v1/payments/{paymentId} ``` 5. Verify the payment status. #### Expected result * The payment is authorized successfully. * The payment status is `AUTHORIZED`. * A payment ID is generated. * A callback notification is received. * The authorized amount matches the requested amount. * The payment can be captured or cancelled. Example response: ```json { "paymentId": "019fffc4-17c4-7922-8be4-23cc21348aa1", "paymentStatus": "AUTHORIZED" } ``` ### Authorization verification Verify the latest payment status before each payment operation. #### Validation 1. Retrieve the latest payment details. ```http GET /egw/v1/payments/{paymentId} ``` 2. Review the payment response. #### Expected result * The payment status is returned successfully. * The authorized amount is available. * The payment links to the corresponding order. * The merchant can determine if capture or cancellation is allowed. ### Capture authorized payment Capture converts an authorized payment into a completed payment. #### Validation 1. Retrieve an authorized payment. 2. Capture the payment. ```http PATCH /egw/v1/payments/{paymentId}/capture ``` 3. Retrieve the payment details. #### Expected result * The capture request succeeds. * The payment status changes from `AUTHORIZED` to `CAPTURED`. * The captured amount matches the requested amount. * The payment is completed. ### Partial capture Partial capture completes only part of the authorized amount. #### Validation 1. Retrieve an authorized payment. 2. Submit a partial capture request. 3. Review the payment details. #### Expected result * The partial capture request succeeds. * The captured amount matches the requested amount. * The remaining authorized balance updates according to platform behaviour. * Capture history remains available for audit purposes. ### Cancel authorization Cancel an authorization to release reserved funds without completing the payment. #### Validation 1. Retrieve an authorized payment. 2. Cancel the authorization. ```http PATCH /egw/v1/payments/{paymentId}/cancel ``` 3. Retrieve the payment details. #### Expected result * The authorization is cancelled successfully. * The payment status changes to `CANCELLED`. * Reserved funds are released under issuer and scheme rules. * The payment can no longer be captured. ### Authorization not eligible for refund Refunds cannot be created for authorized payments. Capture the payment before initiating a refund. #### Validation 1. Create an authorized payment. 2. Attempt to create a refund. ```http POST /egw/v1/refunds ``` #### Expected result * The refund request is rejected. * The payment remains in `AUTHORIZED` status. * The API returns a validation error. Example response: ```json { "apiClientMessages": [ { "category": "ERROR", "code": "STATUS_INVALID", "text": "Cannot refund payment when it is in status AUTHORIZED" } ] } ``` #### Required merchant action ``` Authorized ↓ Capture payment ↓ Captured ↓ Create refund ``` ### Merchant validation checklist Verify that: * Authorization completes successfully. * The payment reaches `AUTHORIZED` status. * Payment IDs and authorized amounts are stored. * Callback notifications are processed correctly. * Authorized payments can be captured or cancelled. * Authorized payments cannot be refunded directly. * The Payment API verifies status before each operation. * Audit logs record payment operations. ## Refund Use Sandbox payments to verify that your integration handles refund operations correctly. Refunds return funds from a completed payment. Link each refund to the original payment. Store refund details and maintain an audit trail. This supports reconciliation, customer support, and financial reporting. ### Refund eligibility Verify the current payment status before creating a refund. ```http GET /egw/v1/payments/{paymentId} ``` | Payment status | Refund allowed | | -------------- | -------------- | | `Initialized` | No | | `Authorized` | No | | `Captured` | Yes | | `Settled` | Yes | | `Failed` | No | | `Cancelled` | No | | `Abandoned` | No | Refund eligibility also depends on the payment method and merchant configuration. For Pay by Bank, verify the following: * The payment settled to the merchant's SEB settlement account. * The refund is within 180 days of the original payment. * The refund returns funds to the original payer. * The amount does not exceed the remaining refundable balance. The gateway rejects refunds for ineligible payments. ### Full refund A full refund returns the entire payment amount. #### Validation 1. Complete a successful payment. 2. Verify that the payment has a refundable status. 3. Retrieve and store the payment ID. 4. Initiate a refund for the full payment amount. ```http POST /egw/v1/refunds ``` 5. Verify the refund response and subsequent payment status. #### Expected result * The refund is created successfully. * The full payment amount is refunded. * The refund links to the original payment. * Merchant reporting and audit logs record the refund. ### Partial refund A partial refund returns part of the original payment amount. #### Validation 1. Complete a successful payment. 2. Retrieve and store the payment ID. 3. Create a partial refund. 4. Review the refund response. #### Expected result * The partial refund is processed successfully. * The refunded amount matches the requested amount. * The refund links to the original payment. * The remaining refundable balance is reduced. ### Multiple partial refunds Multiple refunds can be created against the same payment. #### Validation 1. Complete a successful payment. 2. Create a partial refund. 3. Create one or more additional partial refunds. 4. Review the refund history and remaining balance. #### Expected result * Each refund is processed separately. * Refund history remains traceable. * The total refunded amount is calculated correctly. * The remaining refundable balance updates after each refund. ### Refund response and lifecycle verification Refunds have their own lifecycle. A successful submission may return `PROCESSING` before reaching `COMPLETED`. Example completed refund response: ```json { "refundId": "01a019ba-da32-75ed-93e9-eb626c72a7b4", "paymentId": "01a019b8-69bc-7f60-8ccf-ea1fde4e2978", "refundStatus": "COMPLETED", "instructedAmount": { "currency": "EUR", "amount": "0.01" } } ``` #### Expected result * A refund ID is generated. * The refund links to the correct payment ID. * The refund status progresses to `COMPLETED`. * The refund amount and currency match the request. * The payment status changes to `Refunded`. * A refund callback notification is received and processed idempotently. ### Refund amount validation Refund requests must not exceed the remaining refundable balance. #### Validation 1. Complete a successful payment. 2. Create one or more refunds. 3. Attempt to refund more than the remaining balance. #### Expected result * The refund request is rejected. * No additional refund is created. * Existing refund records remain unchanged. Example response: ```json { "apiClientMessages": [ { "category": "ERROR", "code": "AMOUNT_EXCEEDED", "text": "Refund amount exceeded, available amount is 0.17" } ] } ``` ### Concurrent refund validation The gateway can reject a refund while another refund request is processing. #### Validation 1. Create a refund that remains in `PROCESSING`. 2. Submit another refund for the same payment. 3. Review the response and refund history. #### Expected result * The conflicting request is rejected. * The original refund remains traceable. * No duplicate refund is created. ### Refund on an initialized payment This scenario attempts to refund a payment that has not completed checkout. #### Expected result * The refund request is rejected. * No refund is created. * The payment remains unchanged. ### Refund on an authorized payment This scenario attempts to refund an authorized, uncaptured payment. #### Expected result * The refund request is rejected. * No refund is created. * The payment remains `Authorized`. #### Merchant action Capture authorized payments before creating refunds. Use an authorization reversal when funds remain reserved. ``` Authorized ↓ Capture payment ↓ Captured ↓ Create refund ``` ```http PATCH /egw/v1/payments/{paymentId}/capture ``` ### Refund reversal Refund reversals are supported only for Account-to-Account (A2A) payments. They are not supported for card payments or wallet payment methods. This includes Google Pay, Apple Pay, and Click to Pay. ```http PATCH /egw/v1/refunds/{refundId}/revert ``` #### Validation 1. Create a refund. 2. Store the refund ID. 3. Attempt to revert the refund. 4. Review the API response and payment status. #### Expected result * The reversal succeeds for eligible A2A payments. * Refund history remains traceable. * Audit logs record reversal activity. * The refund status becomes Reverted when reversal succeeds. ### Refund reversal restrictions Refund reversals are rejected for card payments, Google Pay, Apple Pay, and Click to Pay. #### Expected result * The reversal request is rejected. * The original refund remains unchanged. * No additional transaction is created. * The merchant receives a clear validation error. ### Merchant validation checklist Verify that: * Refunds use eligible payment statuses only. * Pay by Bank refund conditions are validated. * Refund IDs and payment IDs are stored. * Refund amounts do not exceed the refundable balance. * Refunds link to their original payments. * Refund callbacks are processed idempotently. * Refund history remains traceable. * Rejected refunds and reversals are handled correctly. * Reconciliation and reporting include refund operations. ### Related APIs #### Get payment ```http GET /egw/v1/payments/{paymentId} ``` Retrieve payment details and verify refund eligibility. #### Initiate refund ```http POST /egw/v1/refunds ``` Create a full or partial refund. #### Revert refund ```http PATCH /egw/v1/refunds/{refundId}/revert ``` #### Capture payment ```http PATCH /egw/v1/payments/{paymentId}/capture ``` Capture an authorized payment. #### Cancel payment ```http PATCH /egw/v1/payments/{paymentId}/cancel ``` Cancel an authorized payment. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ecommerce.seb.ee/guides/sandbox/test-scenarios/payment-operations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.