Add Payment App Tutorial #1224
Add Payment App Tutorial #1224
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
|
||
| ### What is a Transaction | ||
|
|
||
| A transaction represents a payment event that happened in Order or Checkout. These events include actions like charging a payment, authorizing or refunding it. You can see the complete list of events in the [`TransactionEventTypeEnum`](api-reference/payments/enums/transaction-event-type-enum.mdx). |
There was a problem hiding this comment.
A transaction represents a payment event
I would say payment instance instead of event, as this could be misleading when we take into account TransactionEvent.
These events include actions like charging a payment, authorizing or refunding it.
I would say, that the events such as charges, refunds that happen for TransactionItem(Payment instance), are represented by TransactionEvent
|
|
||
| ### Checkout | ||
|
|
||
| In Saleor, the payment process is a part of [checkout](developer/checkout/overview.mdx). In this tutorial, we will focus on the payment part only. We will assume that the checkout is already created and the user is ready to pay. |
There was a problem hiding this comment.
the payment process is a part of [checkout]
TransactionAPI can be used with Checkout and Order. This part suggest me that the payment process is only working with checkout.
We will assume that the checkout is already created and the user is ready to pay.
Maybe worth adding a link to the checkout creation part? https://docs.saleor.io/developer/checkout/overview#creating-a-checkout-session 🤔
There was a problem hiding this comment.
We could also add another link to quickstart:
https://saleor-docs-git-payment-app-guide-saleorcommerce.vercel.app/docs/quickstart/api
I would also use the word API, like part of Checkout and Order API, because Checkout as standalone might be ambiguous with the front end
| 1. It is designed for the staff users to charge the payment manually. Since we want a checkout user (possibly unauthenticated) to be able to pay for the order, it is not a good fit. | ||
| 2. It does not allow the return of the `CHARGE_ACTION_REQUIRED` event status. | ||
|
|
||
| That leaves us with the `TRANSACTION_INITIALIZE_SESSION` webhook. It is triggered on the [`transactionInitialize`](api-reference/payments/mutations/transaction-initialize.mdx) mutation which can be used without any permissions. It can result in the `CHARGE_ACTION_REQUIRED` event status, as required. |
There was a problem hiding this comment.
which can be used without any permissions.
Except using with action field https://saleor-docs-git-payment-app-guide-saleorcommerce.vercel.app/docs/api-reference/payments/mutations/transaction-initialize#transactioninitializeactiontransactionflowstrategyenum-
|
|
||
| With our transaction events mapped out, let's determine which webhooks we need to implement to handle these events. | ||
|
|
||
| When exploring the [Transaction Events](developer/extending/webhooks/synchronous-events/transaction.mdx) documentation, you may notice that two webhooks can result in the `CHARGE_SUCCESS` event: [`TRANSACTION_CHARGE_REQUESTED`](developer/extending/webhooks/synchronous-events/transaction.mdx#transaction-charge) and [`TRANSACTION_INITIALIZE_SESSION`](developer/extending/webhooks/synchronous-events/transaction.mdx#request-4). |
There was a problem hiding this comment.
You may notice that two webhooks can result in the
CHARGE_SUCCESSevent:
Actually three - TRANSACTION_PROCESS_SESSION
|
|
||
| ### Transaction Events | ||
|
|
||
| The first step in building our Payment App does not involve any code. To avoid further rework, we need to understand the transaction flow we want to model. The goal is to have a list of events produced by the app and their corresponding webhooks. |
There was a problem hiding this comment.
I would also place somewhere an info, that in our case as we want to cover the 3D secure flow, we will need two actions to be done: initialize and process, but some of the flow could require only initialize action.
| }; | ||
| ``` | ||
|
|
||
| ### Calling the `transactionInitialize` Mutation |
There was a problem hiding this comment.
I would add a separate section before this, that would say that you need to re-install app as you added new webhooks.
There was a problem hiding this comment.
Right at the end of this section, I write (in a "warning" admonition):
Beware that modifying a subscription query for a registered webhook or adding a new webhook requires manual webhook update in Saleor API. The easiest way to do it is to reinstall the app.
Do you think we should have it in a separate section?
| A real-world `TRANSACTION_PROCESS_SESSION` webhook handler might: | ||
|
|
||
| - Call the payment provider API to confirm the payment status. | ||
| - Return either `CHARGE_SUCCESS` or `CHARGE_FAILURE` based on the response. |
There was a problem hiding this comment.
or CHARGE_ACTION_REQUIRED. Payment provider could have a multiple validation checks to be perform before returning SUCCESS or FAILURE. So for some payment provider, ``TRANSACTION_PROCESS_SESSION` could be called in the "loop"
|
|
||
| When installing the app back, you may get "**App with the same identifier is already installed**" error. | ||
|
|
||
| Saleor throws this error because the process of fully uninstalling the app is handled by an asynchronous Saleor worker. This means it can take some time before you can install the app with the same identifier again. |
There was a problem hiding this comment.
Also worth mentioning, that in the case of using Saleor locally, you should have active background workers (celery) and celery-beat
|
|
||
| Congratulations on building your first Saleor Payment App! | ||
|
|
||
| Its scope doesn't have to end here. You can further extend the app with additional features: |
There was a problem hiding this comment.
Would be also good to include the generic link to the transactionAPi docs: https://saleor-docs-git-payment-app-guide-saleorcommerce.vercel.app/docs/developer/payments
Also the part responsible for re-calculating the amounts for transaction: https://saleor-docs-git-payment-app-guide-saleorcommerce.vercel.app/docs/developer/payments#recalculations-of-transaction-amounts
|
|
||
| We will integrate with a fictional **Dummy Payment Gateway**. This gateway will simulate real payment processing without handling actual payments. | ||
|
|
||
| ::: |
There was a problem hiding this comment.
I would add here a mermaid chart that would show the full flow that we will achieve with this section.
The chart would include storefront, saleor, apps, mutations that we use, webhooks that we use. This should give you an overall view of the final flow that we want to implement.
|
|
||
| ### Checkout | ||
|
|
||
| In Saleor, the payment process is a part of [checkout](developer/checkout/overview.mdx). In this tutorial, we will focus on the payment part only. We will assume that the checkout is already created and the user is ready to pay. |
There was a problem hiding this comment.
We could also add another link to quickstart:
https://saleor-docs-git-payment-app-guide-saleorcommerce.vercel.app/docs/quickstart/api
I would also use the word API, like part of Checkout and Order API, because Checkout as standalone might be ambiguous with the front end
|
|
||
| :::note | ||
|
|
||
| We will integrate with a fictional **Dummy Payment Gateway**. This gateway will simulate real payment processing without handling actual payments. |
There was a problem hiding this comment.
I would avoid calling it dummy payment gateway to avoid confusion with dummy payment app
There was a problem hiding this comment.
actually there are 3 of them already, two dummy payment plugins and one app :D
The preview is here: https://saleor-docs-git-payment-app-guide-saleorcommerce.vercel.app/docs/developer/extending/apps/building-payment-app