Skip to content

SOL-478 Refund support. #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
limeeugenia wants to merge 3 commits into
base: main
Choose a base branch
from
Open

SOL-478 Refund support. #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fff0d38
SOL-478 Refund support.
limeeugenia Mar 17, 2026
ed45904
SOL-478 Cleanups.
limeeugenia Mar 17, 2026
e29c545
SOL-478 add refundable period.
limeeugenia Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions config/Zed/oms/PaymentTemplateCreditCard01.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,9 @@
<state name="authorized" display="oms.state.authorized"/>
<state name="capture pending" display="oms.state.capture-pending"/>
<state name="captured" display="oms.state.captured"/>
<state name="refund pending" display="oms.state.refund-pending"/>
<state name="refunded" display="oms.state.refunded"/>
<state name="closed for refund" display="oms.state.closed-for-refund"/>
<state name="canceled" display="oms.state.canceled"/>
</states>

Expand Down Expand Up @@ -63,6 +66,24 @@
<target>captured</target>
</transition>

<!-- Refund -->
<transition happy="true">
<source>captured</source>
<target>refund pending</target>
<event>refund</event>
</transition>

<transition happy="true" condition="PaymentTemplate/IsRefunded">
Copy link
Copy Markdown

@feversocial feversocial Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would not do that as OOTB suggestion; That process means that condition checks every time if refund happened or not, which is a lot of useless calls. Instead, I would assume that transition to the refund process is triggered manually. Happy case does not go through the refund. It goes from captured to closed automatically after 30 days; In between, manual transition to refund is possible

Copy link
Copy Markdown
Collaborator Author

@limeeugenia limeeugenia Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not quite get why this will be checked every minute. It'll only happen if someone manually clicked the REFUND button first, so this one is waiting for a callback from that trigger. In most cases these should be fast.
Even if not fast this check is supposed to be checking the notification in the DB, not actually pinging the PSP.

Or do you have an issue with the "happy" attribute? It makes sense to remove that as refund is not a happy process to a ecom :)

<source>refund pending</source>
<target>refunded</target>
</transition>

<transition happy="true">
<source>captured</source>
<target>closed for refund</target>
<event>close for refund</event>
</transition>

<!-- Cancel -->
<transition>
<source>authorized</source>
Expand All @@ -79,6 +100,8 @@
<event name="wait" timeout="1 second"/>
<event name="authorize" manual="true" onEnter="true" command="PaymentTemplate/Authorize"/>
<event name="capture" manual="true" onEnter="true" command="PaymentTemplate/Capture"/>
<event name="refund" manual="true" command="PaymentTemplate/Refund"/>
<event name="close for refund" timeout="30 days"/>
<event name="cancel" manual="true" command="PaymentTemplate/Cancel"/>
</events>

Expand Down
23 changes: 23 additions & 0 deletions config/Zed/oms/PaymentTemplateInvoice01.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,9 @@
<state name="authorized" display="oms.state.authorized"/>
<state name="capture pending" display="oms.state.capture-pending"/>
<state name="captured" display="oms.state.captured"/>
<state name="refund pending" display="oms.state.refund-pending"/>
<state name="refunded" display="oms.state.refunded"/>
<state name="closed for refund" display="oms.state.closed-for-refund"/>
<state name="canceled" display="oms.state.canceled"/>
</states>

Expand Down Expand Up @@ -63,6 +66,24 @@
<target>captured</target>
</transition>

<!-- Refund -->
<transition happy="true">
<source>captured</source>
<target>refund pending</target>
<event>refund</event>
</transition>

<transition happy="true" condition="PaymentTemplate/IsRefunded">
<source>refund pending</source>
<target>refunded</target>
</transition>

<transition happy="true">
<source>captured</source>
<target>closed for refund</target>
<event>close for refund</event>
</transition>

<!-- Cancel -->
<transition>
<source>authorized</source>
Expand All @@ -79,6 +100,8 @@
<event name="wait" timeout="1 second"/>
<event name="authorize" manual="true" onEnter="true" command="PaymentTemplate/Authorize"/>
<event name="capture" manual="true" onEnter="true" command="PaymentTemplate/Capture"/>
<event name="refund" manual="true" command="PaymentTemplate/Refund"/>
<event name="close for refund" timeout="30 days"/>
<event name="cancel" manual="true" command="PaymentTemplate/Cancel"/>
</events>

Expand Down
3 changes: 3 additions & 0 deletions data/import/glossary.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,6 @@ oms.state.authorization-failed,Authorization Failed,en_US
oms.state.authorized,Authorized,en_US
oms.state.capture-pending,Capture Pending,en_US
oms.state.captured,Captured,en_US
oms.state.refund-pending,Refund Pending,en_US
oms.state.refunded,Refunded,en_US
oms.state.closed-for-refund,Refunded,en_US
67 changes: 67 additions & 0 deletions src/Spryker/Client/PaymentTemplate/Api/Refund/RefundApiRequest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
<?php

/**
* MIT License
* For full license information, please view the LICENSE file that was distributed with this source code.
*/

namespace Spryker\Client\PaymentTemplate\Api\Refund;

use Generated\Shared\Transfer\PaymentTemplateRefundRequestTransfer;
use Generated\Shared\Transfer\PaymentTemplateRefundResponseTransfer;
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\RequestOptions;
use Psr\Http\Message\ResponseInterface;
use Spryker\Client\PaymentTemplate\Api\ApiLogger;
use Spryker\Client\PaymentTemplate\PaymentTemplateConfig;

class RefundApiRequest
{
public function __construct(
protected PaymentTemplateConfig $paymentTemplateConfig,
protected ApiLogger $apiLogger,
protected Client $guzzleClient,
protected RefundMapper $refundMapper,
) {
}

public function request(PaymentTemplateRefundRequestTransfer $paymentTemplateRefundRequestTransfer): PaymentTemplateRefundResponseTransfer
{
try {
$this->apiLogger->logRequest($this->getUrl(), $paymentTemplateRefundRequestTransfer);

$requestBody = $this->refundMapper->mapRequest($paymentTemplateRefundRequestTransfer);
$httpResponse = $this->sendRequest($requestBody);

$paymentTemplateApiResponseTransfer = $this->refundMapper->mapResponse($httpResponse);
$this->apiLogger->logResponse($httpResponse, $paymentTemplateApiResponseTransfer);

return $paymentTemplateApiResponseTransfer;
} catch (RequestException $exception) {
$this->apiLogger->logErrorRequest($exception, $exception->hasResponse() ? $exception->getResponse() : null);

return $this->refundMapper->mapErrorResponse($exception);
}
}

protected function sendRequest(string $requestBody): ResponseInterface
{
$requestOptions = [
RequestOptions::HEADERS => $this->paymentTemplateConfig->getDefaultHeaders(),
RequestOptions::TIMEOUT => $this->paymentTemplateConfig->getApiTimeout(),
RequestOptions::BODY => $requestBody,
];

return $this->guzzleClient->request(
'POST',
$this->getUrl(),
$requestOptions,
);
}

protected function getUrl(): string
{
return $this->paymentTemplateConfig->getRefundUrl();
}
}
46 changes: 46 additions & 0 deletions src/Spryker/Client/PaymentTemplate/Api/Refund/RefundMapper.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
<?php

/**
* MIT License
* For full license information, please view the LICENSE file that was distributed with this source code.
*/

namespace Spryker\Client\PaymentTemplate\Api\Refund;

use Generated\Shared\Transfer\PaymentTemplateApiErrorResponseTransfer;
use Generated\Shared\Transfer\PaymentTemplateRefundRequestTransfer;
use Generated\Shared\Transfer\PaymentTemplateRefundResponseTransfer;
use GuzzleHttp\Exception\RequestException;
use Psr\Http\Message\ResponseInterface;

class RefundMapper
{
public function mapRequest(PaymentTemplateRefundRequestTransfer $requestTransfer): string
{
return json_encode($requestTransfer->toArray());
}

public function mapResponse(ResponseInterface $httpResponse): PaymentTemplateRefundResponseTransfer
{
$responseBody = json_decode($httpResponse->getBody()->getContents(), true);

return (new PaymentTemplateRefundResponseTransfer())->fromArray($responseBody);
}

public function mapErrorResponse(RequestException $exception): PaymentTemplateRefundResponseTransfer
{
$errorResponseTransfer = (new PaymentTemplateApiErrorResponseTransfer())
->setMessage($exception->getMessage())
->setStatusCode($exception->getCode());

if ($exception->hasResponse()) {
$errorResponseTransfer
->setStatusCode($exception->getResponse()->getStatusCode())
->setBody($exception->getResponse()->getBody()->getContents());
}

return (new PaymentTemplateRefundResponseTransfer())
->setIsSuccess(false)
->setErrorResponse($errorResponseTransfer);
}
}
11 changes: 9 additions & 2 deletions src/Spryker/Client/PaymentTemplate/PaymentTemplateClient.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@
use Generated\Shared\Transfer\PaymentTemplateCaptureResponseTransfer;
use Generated\Shared\Transfer\PaymentTemplatePaymentMethodsRequestTransfer;
use Generated\Shared\Transfer\PaymentTemplatePaymentMethodsResponseTransfer;
use Generated\Shared\Transfer\PaymentTemplateRefundRequestTransfer;
use Generated\Shared\Transfer\PaymentTemplateRefundResponseTransfer;
use Generated\Shared\Transfer\PaymentTemplateWebhookPayloadTransfer;
use Generated\Shared\Transfer\PaymentTemplateWebhookProcessResponseTransfer;
use Spryker\Client\Kernel\AbstractClient;
Expand All @@ -33,9 +35,14 @@ public function authorize(PaymentTemplateAuthorizeRequestTransfer $paymentTempla
return $this->getFactory()->createAuthorizeRequest()->request($paymentTemplateAuthorizeRequestTransfer);
}

public function capture(PaymentTemplateCaptureRequestTransfer $paymentTemplateAuthorizeResponseTransfer): PaymentTemplateCaptureResponseTransfer
public function capture(PaymentTemplateCaptureRequestTransfer $paymentTemplateCaptureRequestTransfer): PaymentTemplateCaptureResponseTransfer
{
return $this->getFactory()->createCaptureRequest()->request($paymentTemplateAuthorizeResponseTransfer);
return $this->getFactory()->createCaptureRequest()->request($paymentTemplateCaptureRequestTransfer);
}

public function refund(PaymentTemplateRefundRequestTransfer $paymentTemplateRefundRequestTransfer): PaymentTemplateRefundResponseTransfer
{
return $this->getFactory()->createRefundRequest()->request($paymentTemplateRefundRequestTransfer);
}

public function cancel(PaymentTemplateCancelRequestTransfer $paymentTemplateCancelRequestTransfer): PaymentTemplateCancelResponseTransfer
Expand Down
21 changes: 19 additions & 2 deletions src/Spryker/Client/PaymentTemplate/PaymentTemplateClientInterface.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@
use Generated\Shared\Transfer\PaymentTemplateCaptureResponseTransfer;
use Generated\Shared\Transfer\PaymentTemplatePaymentMethodsRequestTransfer;
use Generated\Shared\Transfer\PaymentTemplatePaymentMethodsResponseTransfer;
use Generated\Shared\Transfer\PaymentTemplateRefundRequestTransfer;
use Generated\Shared\Transfer\PaymentTemplateRefundResponseTransfer;
use Generated\Shared\Transfer\PaymentTemplateWebhookPayloadTransfer;
use Generated\Shared\Transfer\PaymentTemplateWebhookProcessResponseTransfer;

Expand Down Expand Up @@ -44,11 +46,26 @@ public function authorize(PaymentTemplateAuthorizeRequestTransfer $paymentTempla
*
* @api
*
* @param \Generated\Shared\Transfer\PaymentTemplateCaptureRequestTransfer $paymentTemplateAuthorizeResponseTransfer
* @param \Generated\Shared\Transfer\PaymentTemplateCaptureRequestTransfer $paymentTemplateCaptureRequestTransfer
*
* @return \Generated\Shared\Transfer\PaymentTemplateCaptureResponseTransfer
*/
public function capture(PaymentTemplateCaptureRequestTransfer $paymentTemplateAuthorizeResponseTransfer): PaymentTemplateCaptureResponseTransfer;
public function capture(PaymentTemplateCaptureRequestTransfer $paymentTemplateCaptureRequestTransfer): PaymentTemplateCaptureResponseTransfer;

/**
* Specification:
* - Sends capture request to payment provider to capture authorized amount.
* - Maps request data to provider-specific format.
* - Returns capture response.
* - Logs the request, response and error.
*
* @api
*
* @param \Generated\Shared\Transfer\PaymentTemplateRefundRequestTransfer $paymentTemplateRefundRequestTransfer
*
* @return \Generated\Shared\Transfer\PaymentTemplateRefundResponseTransfer
*/
public function refund(PaymentTemplateRefundRequestTransfer $paymentTemplateRefundRequestTransfer): PaymentTemplateRefundResponseTransfer;

/**
* Specification:
Expand Down
5 changes: 5 additions & 0 deletions src/Spryker/Client/PaymentTemplate/PaymentTemplateConfig.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,11 @@ public function getCaptureUrl(): string
return $this->getApiBaseUrl() . $this->getSharedConfig()->getCapturePath();
}

public function getRefundUrl(): string
{
return $this->getApiBaseUrl() . $this->getSharedConfig()->getRefundPath();
}

/**
* @api
*
Expand Down
17 changes: 17 additions & 0 deletions src/Spryker/Client/PaymentTemplate/PaymentTemplateFactory.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@

use GuzzleHttp\Client;
use Spryker\Client\Kernel\AbstractFactory;
use Spryker\Client\PaymentTemplate\Api\Refund\RefundApiRequest;
use Spryker\Client\PaymentTemplate\Api\Refund\RefundMapper;
use Spryker\Client\ZedRequest\ZedRequestClientInterface;
use Spryker\Client\PaymentTemplate\Api\ApiLogger;
use Spryker\Client\PaymentTemplate\Api\Authorization\AuthorizationApiRequest;
Expand Down Expand Up @@ -72,6 +74,21 @@ public function createCaptureMapper(): CaptureMapper
return new CaptureMapper();
}

public function createRefundRequest(): RefundApiRequest
{
return new RefundApiRequest(
$this->getConfig(),
$this->createApiLogger(),
$this->createGuzzleClient(),
$this->createRefundMapper(),
);
}

public function createRefundMapper(): RefundMapper
{
return new RefundMapper();
}

public function createCancelRequest(): CancelApiRequest
{
return new CancelApiRequest(
Expand Down
5 changes: 5 additions & 0 deletions src/Spryker/Shared/PaymentTemplate/PaymentTemplateConfig.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,11 @@ public function getCapturePath(): string
return $this->get(PaymentTemplateConstants::API_CAPTURE_PATH, '/api/v1/capture');
}

public function getRefundPath(): string
{
return $this->get(PaymentTemplateConstants::API_REFUND_PATH, '/api/v1/refund');
}

public function getCancelPath(): string
{
return $this->get(PaymentTemplateConstants::API_CANCEL_PATH, '/api/v1/cancel');
Expand Down
2 changes: 2 additions & 0 deletions src/Spryker/Shared/PaymentTemplate/PaymentTemplateConstants.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ interface PaymentTemplateConstants

public const string API_CAPTURE_PATH = 'PAYMENT_TEMPLATE:API_CAPTURE_PATH';

public const string API_REFUND_PATH = 'PAYMENT_TEMPLATE:API_REFUND_PATH';

public const string API_CANCEL_PATH = 'PAYMENT_TEMPLATE:API_CANCEL_PATH';

public const string API_PAYMENT_METHODS_PATH = 'PAYMENT_TEMPLATE:API_PAYMENT_METHODS_PATH';
Expand Down
12 changes: 12 additions & 0 deletions src/Spryker/Shared/PaymentTemplate/Transfer/payment_template.transfer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,18 @@
<property name="errorResponse" type="PaymentTemplateApiErrorResponse"/>
</transfer>

<!-- ========================================================================
REFUND OPERATION
======================================================================== -->

<transfer name="PaymentTemplateRefundRequest" strict="true">
</transfer>

<transfer name="PaymentTemplateRefundResponse" strict="true">
<property name="isSuccess" type="bool"/>
<property name="errorResponse" type="PaymentTemplateApiErrorResponse"/>
</transfer>

<!-- ========================================================================
CANCEL OPERATION
======================================================================== -->
Expand Down
Loading