> Documentation index: [Saleor](/llms.txt) · [This section](/developer/llms.txt)
> Source: https://docs.saleor.io/developer/app-store/apps/np-atobarai/webhooks

# NP Atobarai App Webhooks

This page covers each webhook behavior, data it expects and returns and what it can return.

<a id="saleor-webhooks"></a>

## Saleor Webhooks

App supports the following synchronous and asynchronous webhooks. All of these webhooks are executed as a result of explicit mutations called by storefront (to manage payments) or by Dashboard (to refund payments or to update tracking number).

Check the [Transactions documentation](/developer/payments/transactions.md) to learn more.

<a id="paymentgatewayinitializesession"></a>

### `PaymentGatewayInitializeSession`

This webhook checks if the App is properly configured and checkout or order has valid data. If there is invalid data in checkout / order app will return error in `data` field. See [errors](/developer/app-store/apps/np-atobarai/errors.md) for more information on possible app errors.

App will validate if checkout or order has:

-   `JPY` as currencyCode (based on checkout / order channel)
-   `JP` as shipping address country
-   billing address phone that starts with `+81`
-   email

<a id="transactioninitializesession"></a>

### `TransactionInitializeSession`

This webhook takes data from checkout or order and registers transaction in NP Atobarai.

If NP Atobarai returns pending credit check, the app will return `CHARGE_ACTION_REQUIRED` as a transaction event result. At this point storefront can fix problematic data and retry the payment using `transactionProcess` mutation.

Error that may be raised by NP Atobarai:

```text
- RE009:lack of address information
- RE014:address_confirmation of work
- RE015:Address_Insufficient delivery destination information
- RE020:Address_Confirmation of work at delivery destination
- RE021:TEL_Phone number error
- RE023:TEL_phone number error of delivery destination
- RE026:Other_Reason of merchant
```

If transaction is created successfully, the app will return transaction event with `CHARGE_SUCESS` result to Saleor.

<a id="transactionprocesssession"></a>

### `TransactionProcessSession`

`TransactionProcessSession` is supposed to be executed once `TransactionInitializeSession` returns `CHARGE_ACTION_REQUIRED` as a transaction event result. Ask storefront user to update checkout or order fields and call `TransactionProcessSession` to update transaction with the new fields.

If transaction is updated successfully, the app will return transaction event with `CHARGE_SUCESS` result to Saleor.

<a id="transactionrefundrequested"></a>

### `TransactionRefundRequested`

This webhook is executed when a staff user wants to refund the payment. App will try figure out if refund action was requested before adding tracking number to the fulfillment or after.

<a id="before-adding-tracking-number"></a>

#### Before adding tracking number

App will execute following logic based on payment amounts:

-   Refunding full amount of the order - app will cancel the transaction in NP Atobarai
-   Refunding partial amount of the order - app will update transaction with new line `Discount` that is the same as partial refund
-   Refunding with line items (grantedRefund) - app will update transaction with the new lines

<a id="after-adding-tracking-number"></a>

#### After adding tracking number

App will execute following logic based on payment amounts:

-   Refunding full amount of the order - app will cancel the transaction in NP Atobarai
-   Refunding partial amount of the order - app will cancel the transaction in NP Atobarai and create new one with new line `Discount` that is the same as partial refund
-   Refunding with line items (grantedRefund) - app will cancel the transaction in NP Atobarai and create new one with new line items based on items that were not included in grantedRefund

In both cases if all operations succeeds app will report `REFUND_SUCCESS` event or `REFUND_FAILURE` event is case of the error.

<a id="fulfilmenttrackingnumberupdated"></a>

### `FulfilmentTrackingNumberUpdated`

This asynchronous webhook is executed when a staff user updates the tracking number of the fulfillment.

Before reporting fulfillment, the app filters the order's transactions to find completed ones — those with `CHARGE_SUCCESS` or `AUTHORIZATION_SUCCESS` events. This filtering ensures that "ghost" transactions (e.g. failed or incomplete payment attempts) don't block fulfillment reporting.

The app then validates that exactly one completed transaction exists:

-   **No completed transactions** — the app skips fulfillment reporting and adds an order note: _"NP Atobarai skipped fulfillment reporting: No completed transactions found for the order"_.
-   **Multiple completed transactions** — the app skips fulfillment reporting and adds an order note: _"NP Atobarai skipped fulfillment reporting: Multiple completed transactions found for the order"_.
-   **Exactly one completed transaction** — the app proceeds to report fulfillment to NP Atobarai with the tracking number provided in the webhook payload. Based on NP Atobarai API response (success or failure), the app adds an order note with the operation result.