Skip to content

Commit

Permalink
Update docs after adding transactionRequestRefundForGrantedRefund mut…
Browse files Browse the repository at this point in the history 
…ation
  • Loading branch information
@korycins
korycins committed Jun 6, 2023
1 parent 4cc8b0b commit 4c6e0cb
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 22 deletions.
42 changes: 33 additions & 9 deletions docs/developer/extending/apps/synchronous-webhooks/transaction-webhooks.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ The example below shows the pre-defined payload that will be used in the case wh
{
"action": { "currency": "USD", "type": "charge", "value": "5.00" },
"meta": {
"issued_at": "1914-06-28T10:50:00+00:00",
"issued_at": "2022-06-28T10:50:00+00:00",
"issuing_principal": { "id": "Sample app objects", "type": "app" },
"version": "3.13.0-a"
},
Expand All @@ -94,10 +94,10 @@ The example below shows the pre-defined payload that will be used in the case wh
"canceled_value": "0.00",
"charged_value": "0.00",
"checkout_id": null,
"created_at": "1914-06-28T10:50:00Z",
"created_at": "2022-06-28T10:50:00Z",
"currency": "USD",
"message": "",
"modified_at": "1914-06-28T10:50:00Z",
"modified_at": "2022-06-28T10:50:00Z",
"name": "Credit card",
"order_id": "T3JkZXI6YjE1YzdlZTgtMzUxNy00MTczLWEzNWYtMmQxMDdkMWI4Yzhk",
"psp_reference": "PSP ref",
Expand Down Expand Up @@ -219,7 +219,7 @@ The example below shows the pre-defined payload that will be used in the case wh
{
"action": { "currency": "USD", "type": "cancel", "value": "0.00" },
"meta": {
"issued_at": "1914-06-28T10:50:00+00:00",
"issued_at": "2022-06-28T10:50:00+00:00",
"issuing_principal": { "id": "Sample app objects", "type": "app" },
"version": "3.13.0-a"
},
Expand All @@ -229,10 +229,10 @@ The example below shows the pre-defined payload that will be used in the case wh
"canceled_value": "0.00",
"charged_value": "0.00",
"checkout_id": null,
"created_at": "1914-06-28T10:50:00Z",
"created_at": "2022-06-28T10:50:00Z",
"currency": "USD",
"message": "",
"modified_at": "1914-06-28T10:50:00Z",
"modified_at": "2022-06-28T10:50:00Z",
"name": "Credit card",
"order_id": "T3JkZXI6YWEzYzVhOTMtN2NlYS00OGZkLWJmYWUtMWFkYjI5YTRjMmY1",
"psp_reference": "PSP ref",
Expand Down Expand Up @@ -341,18 +341,42 @@ subscription {
id
}
}
grantedRefund {
id
amount {
amount
}
lines {
id
quantity
orderLine {
unitPrice {
gross {
amount
}
}
}
}
}
}
}
}
```

:::note

`grantedRefund` - This field was introduced in **Saleor 3.15**. It contains the details about [OrderGrantedRefund](api-reference/orders/objects/order-granted-refund.mdx) related to the the refund request action.
The field will contain OrderGrantedRefund when a refund request was triggered by calling [transactionRequestRefundForGrantedRefund](../../../../api-reference/payments/mutations/transaction-request-refund-for-granted-refund) mutation.

:::

The example below shows the pre-defined payload that will be used in the case when a subscription query is not provided:

```json
{
"action": { "currency": "USD", "type": "refund", "value": "9.00" },
"meta": {
"issued_at": "1914-06-28T10:50:00+00:00",
"issued_at": "2022-06-28T10:50:00+00:00",
"issuing_principal": { "id": "Sample app objects", "type": "app" },
"version": "3.13.0-a"
},
Expand All @@ -362,10 +386,10 @@ The example below shows the pre-defined payload that will be used in the case wh
"canceled_value": "0.00",
"charged_value": "0.00",
"checkout_id": null,
"created_at": "1914-06-28T10:50:00Z",
"created_at": "2022-06-28T10:50:00Z",
"currency": "USD",
"message": "",
"modified_at": "1914-06-28T10:50:00Z",
"modified_at": "2022-06-28T10:50:00Z",
"name": "Credit card",
"order_id": "T3JkZXI6NjdlYTYxNDAtMzEwZi00YTRlLThmODktNTU2NjliMjk4NjU5",
"psp_reference": "PSP ref",
Expand Down
41 changes: 28 additions & 13 deletions docs/developer/payments.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -346,6 +346,11 @@ The following example shows how you can use the [transactionCreate](../api-refer
The transaction was authorized, and the payment was made with a credit card. The actions that can be called from Saleor are: `CANCEL` and `CHARGE`.
The authorized amount is **$99**.

::: info
The [transactionCreate] can only be called by staff users or app with
[HANDLE_PAYMENTS](api-storefront/users/enums/permission-enum.mdx#code-style-fontweight-normal-permissionenumbhandle_paymentsbcode) permission.
:::

##### Saleor 3.13+

```graphql
Expand Down Expand Up @@ -465,8 +470,9 @@ It takes the following arguments:

:::info

The [transactionUpdate](../api-reference/payments/mutations/transaction-update) can only be called by the transaction owner.
The owner is the User or App that created the given transaction.
The [transactionUpdate](../api-reference/payments/mutations/transaction-update) can only be called by staff users with
[HANDLE_PAYMENTS](api-storefront/users/enums/permission-enum.mdx#code-style-fontweight-normal-permissionenumbhandle_paymentsbcode) permission
or by App which is the owner of the transaction and has [HANDLE_PAYMENTS](api-storefront/users/enums/permission-enum.mdx#code-style-fontweight-normal-permissionenumbhandle_paymentsbcode) permission.
:::

The following example shows how you can use the [transactionUpdate](../api-reference/payments/mutations/transaction-create) mutation to update the transaction.
Expand Down Expand Up @@ -579,8 +585,9 @@ It takes the following arguments:

:::info

The [transactionEventReport](../api-reference/payments/mutations/transaction-event-report) can be called only by
the owner of the transaction.
The [transactionEventReport](../api-reference/payments/mutations/transaction-event-report) can only be called by staff users with
[HANDLE_PAYMENTS](api-storefront/users/enums/permission-enum.mdx#code-style-fontweight-normal-permissionenumbhandle_paymentsbcode) permission
or by App which is the owner of the transaction and has [HANDLE_PAYMENTS](api-storefront/users/enums/permission-enum.mdx#code-style-fontweight-normal-permissionenumbhandle_paymentsbcode) permission.
The owner is the User or App that created the given transaction.
:::

Expand Down Expand Up @@ -648,15 +655,23 @@ An action request is called when a staff user or an app triggers a request for a

#### Saleor 3.13+

Calling mutation [transactionRequestAction](../api-reference/payments/mutations/transaction-request-action) will also create a new
[TransactionEvent](../api-reference/payments/objects/transaction-event) with one of the request type ([AUTHORIZATION_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbauthorization_requestbcode),
[CHARGE_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbcharge_requestbcode),
[REFUND_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbrefund_requestbcode),
[CANCEL_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbcancel_requestbcode)),
`amount` and the `owner` (User or App). Saleor will send a synchronous webhook dedicated to the action
[TRANSACTION_CHARGE_REQUESTED](../api-reference/webhooks/enums/webhook-event-type-sync-enum.mdx#code-style-fontweight-normal-webhookeventtypesyncenumbtransaction_charge_requestedbcode),
[TRANSACTION_CANCELATION_REQUESTED](../api-reference/webhooks/enums/webhook-event-type-sync-enum.mdx#code-style-fontweight-normal-webhookeventtypesyncenumbtransaction_cancelation_requestedbcode),
[TRANSACTION_REFUND_REQUESTED](../api-reference/webhooks/enums/webhook-event-type-sync-enum.mdx#code-style-fontweight-normal-webhookeventtypesyncenumbtransaction_refund_requestedbcode)
There are two mutations that can trigger the action on the app side:

- Calling mutation [transactionRequestAction](../api-reference/payments/mutations/transaction-request-action) will also create a new
[TransactionEvent](../api-reference/payments/objects/transaction-event) with one of the request type ([AUTHORIZATION_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbauthorization_requestbcode),
[CHARGE_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbcharge_requestbcode),
[REFUND_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbrefund_requestbcode),
[CANCEL_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbcancel_requestbcode)),
`amount` and the `owner` (User or App). Saleor will send a synchronous webhook dedicated to the action
[TRANSACTION_CHARGE_REQUESTED](../api-reference/webhooks/enums/webhook-event-type-sync-enum.mdx#code-style-fontweight-normal-webhookeventtypesyncenumbtransaction_charge_requestedbcode),
[TRANSACTION_CANCELATION_REQUESTED](../api-reference/webhooks/enums/webhook-event-type-sync-enum.mdx#code-style-fontweight-normal-webhookeventtypesyncenumbtransaction_cancelation_requestedbcode),
[TRANSACTION_REFUND_REQUESTED](../api-reference/webhooks/enums/webhook-event-type-sync-enum.mdx#code-style-fontweight-normal-webhookeventtypesyncenumbtransaction_refund_requestedbcode)

- Calling mutation [transactionRequestRefundForGrantedRefund](../api-reference/payments/mutations/transaction-request-refund-for-granted-refund) will create a new [TransactionEvent](../api-reference/payments/objects/transaction-event) with
[REFUND_REQUEST](../api-reference/payments/enums/transaction-event-type-enum#code-style-fontweight-normal-transactioneventtypeenumbrefund_requestbcode) type, `amount` and the `owner` (User or App).
Saleor will send a synchronous webhook [TRANSACTION_REFUND_REQUESTED](../api-reference/webhooks/enums/webhook-event-type-sync-enum.mdx#code-style-fontweight-normal-webhookeventtypesyncenumbtransaction_refund_requestedbcode).
[OrderGrantedRefund](api-reference/orders/objects/order-granted-refund.mdx) will be included in the webhook payload (if requested in a [subscription query](developer/extending/apps/subscription-webhook-payloads.mdx#custom-payloads) for the webhook).
The mutation is useful when the payment provider requires details about lines that are related to refund action.

The response should contain at least `pspReference` of the action. The `pspReference` will be placed in the previously created event of `_REQUEST` type.
Optionally the response can contain the details of the completed action.
Expand Down

0 comments on commit 4c6e0cb

Please sign in to comment.