# Payment callbacks API

> The Payment Callbacks API a Shoplazza payment app uses to report payment and refund results: complete payment, async notification, parameters, and responses.

The Payment Callbacks API lets payment service providers update Shoplazza with the status of payments and refunds.

Payment apps use two callback types:

* **Complete payment**: A synchronous callback used after customers complete redirect payments, iframe payments, or direct credit card payments that require 3DS verification. Shoplazza returns a redirect URL that sends the customer to the payment completion page.
* **Payment and refund notification**: An asynchronous callback used to notify Shoplazza of the final result for payments and refunds.

If Shoplazza does not receive a successful response, the payments app must retry the request according to the retry policy.

## Complete payment

Requires the `write_payment_info` access scope.

Use the Complete Payment API after the customer completes payment on a third-party page or after 3DS verification. At this stage, the final payment result does not need to be returned; the goal is to continue the customer-facing payment flow.

### Request headers

| Header | Description |
| --- | --- |
| `Access-Token` | OAuth authorization token returned upon authentication. |
| `Shoplazza-Shop-Domain` | Shoplazza system domain for the store. |
| `Shoplazza-Hmac-Sha256` | Signature calculated using the signature method. |
| `Content-Type` | Fixed as `application/json`. |

### Request parameters

| Key | Required | Type | Description |
| --- | --- | --- | --- |
| `app_id` | Yes | string | Payments app ID. |
| `payment_id` | Yes | string | Payment ID. |
| `amount` | Yes | number | Order amount. |
| `currency` | Yes | string | Currency code. |
| `transaction_no` | Yes | string | Third-party payment transaction number. |
| `type` | Yes | string | Payment type, such as `sale` or `authorization`. |
| `test` | Yes | boolean | Whether the request is in test mode. |
| `status` | Yes | string | Payment status, fixed as `paying`. |
| `extension` | No | object | Custom extension fields. |
| `timestamp` | Yes | string | ISO 8601 timestamp. |

### Successful response

```json
{
  "redirect_url": "https://developer.myshoplaza.com/checkout/12345"
}
```

## Payment and refund notification

Requires the `write_payment_info` access scope.

Use the notification callback to asynchronously notify Shoplazza of the final payment or refund result. Payments and refunds share the same request format, with different `type` and `status` values.

### Request headers

| Header | Description |
| --- | --- |
| `Access-Token` | OAuth authorization token returned upon authentication. |
| `Shoplazza-Shop-Domain` | Shoplazza system domain for the store. |
| `Shoplazza-Hmac-Sha256` | Signature calculated using the signature method. |
| `Content-Type` | Fixed as `application/json`. |

### Request parameters

| Key | Required | Type | Description |
| --- | --- | --- | --- |
| `app_id` | Yes | string | Payments app ID. |
| `payment_id` | Yes | string | Payment ID. |
| `amount` | Yes | number | Order or refund amount. |
| `currency` | Yes | string | Currency code. |
| `status` | Yes | string | Payment status (`paid`, `failed`) or refund status (`refund_success`, `refund_failed`). |
| `transaction_no` | Yes | string | Third-party payment transaction number. |
| `type` | Yes | string | `sale` for payment notifications or `refund` for refund notifications. |
| `message` | No | string | Failure message, required when the transaction fails. |
| `error_code` | Conditional | string | Error code, required when `status` is `failed`. |
| `test` | Yes | boolean | Whether the request is in test mode. |
| `extension` | No | object | Custom extension fields. |
| `timestamp` | Yes | string | ISO 8601 timestamp. |

### Successful response

Shoplazza returns HTTP `200` after receiving the notification.

```json
{}
```