shopware.payment.method.sync
shopware.payment.method.async
shopware.payment.method.prepared
shopware.payment.method.refund
pay
: This method will be called after an order has been placed. You receive a Shopware\Core\Checkout\Payment\Cart\AsyncPaymentTransactionStruct
or a Shopware\Core\Checkout\Payment\Cart\SyncPaymentTransactionStruct
which contains the transactionId, order details, the amount of the transaction, a return URL, payment method information and language information. Please be aware, Shopware 6 supports multiple transactions, and you have to use the amount provided and not the total order amount. If you're using the AsynchronousPaymentHandlerInterface
, the pay
method has to return a RedirectResponse
to redirect the customer to an external payment provider. Note: The AsyncPaymentTransactionStruct contains a return URL. This represents the URL that the external payment provider needs to know, so they can also redirect your customer back to your shop. If an error occurs while e.g. calling the API of your external payment provider, you should throw an AsyncPaymentProcessException
. Shopware 6 will handle this exception and set the transaction to the cancelled
state. The same happens if you are using the SynchronousPaymentHandlerInterface
: throw a SyncPaymentProcessException
in an error case.finalize
: The finalize
method is only required if you implemented the AsynchronousPaymentHandlerInterface
, returned a RedirectResponse
in your pay
method and the customer has been redirected from the payment provider back to Shopware 6. You must check here if the payment was successful or not and update the order transaction state accordingly. Similar to the pay action you are able to throw exceptions if some error cases occur. Throw the CustomerCanceledAsyncPaymentException
if the customer canceled the payment process on the payment provider site. If another general error occurs throw the AsyncPaymentFinalizeException
e.g. if your call to the payment provider API fails. Shopware 6 will handle these exceptions and will set the transaction to the cancelled
state.validate
: This method will be called before an order was placed and should check, if a given prepared payment is valid. The payment handler has to verify the given payload with the payment service, because Shopware cannot ensure that the transaction created by the frontend is valid for the current cart. Throw an ValidatePreparedPaymentException
to fail the validation in your implementation.capture
: This method will be called after an order was placed, but only if the validation did not fail and stop the payment flow before. At this point, the order was created and the payment handler will be called again to charge the payment. When the charge was successful, the payment handler should update the transaction state to paid
. The user will be forwarded to the finish page. Throw an CapturePreparedPaymentException
on any errors to fail the capture process and the after order process will be active, so the customer can complete the payment again.refund
: This method is called, whenever a successful transaction is claimed to be refunded. The implementation of the refund handler should validate the legitimacy of the refund and call the PSP to refund the given transaction. Throw a RefundException
to let the refund fail.\Shopware\Core\System\SalesChannel\SalesChannelContext
injected. Please note, that this class contains properties, which are nullable. If you want to use this information, you have to ensure in your code that they are set and not NULL
.ExamplePayment
here.OrderTransactionStateHandler
in this example, as it is helpful for changing an order's transaction state, e.g. to paid
. The payment handler has to be marked as such as well, hence the tag shopware.payment.method.sync
, shopware.payment.method.async
or shopware.payment.method.prepared
respectively for a synchronous, an asynchronous or a prepared payment handler.RedirectResponse
in the pay
method and no finalize
method is necessary either.stateId
of the order should already be done in the pay
method, since there will be no finalize
method. If you have to execute some logic which might fail, e.g. a call to an external API, you should throw a SyncPaymentProcessException
. Shopware 6 will handle this exception and set the transaction to the cancelled
state.paid
.RedirectResponse
.finalize
method to properly handle your customer, when he was returned back to your shop. This is where you check the payment state and set the order transaction state accordingly.pay
method. You'll have to start with letting your external payment provider know, where he should redirect your customer in return when the payment was done. This is usually done by making an API call and transmitting the return URL, which you can fetch from the passed AsyncPaymentTransactionStruct
by using the method getReturnUrl
. Since this is just an example, the method sendReturnUrlToExternalGateway
is empty. Fill in your logic in there in order to actually send the return URL to the external payment provider. The last thing you need to do, is to redirect your customer to the external payment provider via a RedirectResponse
.finalize
method will be executed. In here you have to check whether or not the payment process was successful. If e.g. the customer cancelled the payment process, you'll have to throw a CustomerCanceledAsyncPaymentException
exception.paid
. If not, you could e.g. reopen the order's transaction.RefundPaymentHandlerInterface
.install
method, you actually start by creating a new payment method, if it doesn't exist yet. If you don't know what's happening in there, you might want to have a look at our guide regarding Writing data.uninstall
method and remove the payment method. This might lead to data inconsistency, if the payment method was used in some orders. Instead, only deactivate the method!activate
method and deactivate
method just do that, activating and deactivating the payment method respectively.formattedHandlerIdentifier
. It shortens the original handler identifier (php class reference): Custom/Payment/SEPAPayment
to handler_custom_sepapayment
The syntax for the shortening can be looked up in Shopware\Core\Checkout\Payment\DataAbstractionLayer\PaymentHandlerIdentifierSubscriber.