### Install PayPay OPA SDK for Python

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This command installs the PayPay OPA SDK using pip. Ensure you have Python and pip installed on your system. This is the first step before integrating PayPay payments into your application.

```shell
pip install paypayopa
```

--------------------------------

### PayPay OPA SDK - Python Installation

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Install the PayPay OPA Python SDK using pip.

```APIDOC
## PayPay OPA SDK - Python Installation

### Description
Install the PayPay OPA Python SDK using pip.

### Method
```sh
pip install paypayopa
```
```

--------------------------------

### PayPay OPA SDK - Client Setup

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Configure the PayPay OPA Python SDK client for production or sandbox environments.

```APIDOC
## PayPay OPA SDK - Client Setup

### Description
Configure the PayPay OPA Python SDK client for production or sandbox environments.

### Method
#### Production Mode
To work in production mode, specify your production API_KEY & API_SECRET along with `production_mode=True`.

```py
import paypayopa

API_KEY = "YOUR_PRODUCTION_API_KEY"
API_SECRET = "YOUR_PRODUCTION_API_SECRET"
MERCHANT_ID = "YOUR_MERCHANT_ID"

client = paypayopa.Client(auth=(API_KEY, API_SECRET),
                         production_mode=True)

client.set_assume_merchant(MERCHANT_ID)
```

#### Sandbox Mode
To work in sandbox mode, specify your sandbox API_KEY & API_SECRET keys. The `production_mode` flag defaults to `False` if not specified.

```py
import paypayopa

API_KEY = "YOUR_SANDBOX_API_KEY"
API_SECRET = "YOUR_SANDBOX_API_SECRET"

client = paypayopa.Client(auth=(API_KEY, API_SECRET),
                         production_mode=False) # Or omit production_mode
```

### Usage
After setting up the client instance, you can get the current PayPay SDK version:

```py
print(client.get_version())
```
```

--------------------------------

### Initialize PayPay OPA Client

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Configures the PayPay client with API credentials. Supports both sandbox and production environments, and allows setting a specific merchant ID for multi-merchant setups.

```python
import paypayopa

# Sandbox mode (for testing)
client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

# Production mode
client = paypayopa.Client(
    auth=("API_KEY", "API_SECRET"),
    production_mode=True
)

# Set merchant ID for multi-merchant scenarios
client.set_assume_merchant("MERCHANT_ID")

# Get SDK version
print(client.get_version())
```

--------------------------------

### Create Payment

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Details on how to create a payment request, including required parameters like merchantPaymentId, userAuthorizationId, and amount, along with an example payload and code.

```APIDOC
## Create Payment

### Description
This endpoint is used to initiate a payment transaction. You need to provide a unique merchant payment ID, the user's authorization ID, the payment amount, and an optional order description.

### Method
POST

### Endpoint
/v1/payment

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **merchantPaymentId** (string) - Required - The unique payment transaction ID provided by the merchant. Maximum length is 64 characters.
- **userAuthorizationId** (string) - Required - The PayPay user reference ID returned by the user authorization flow. Maximum length is 64 characters.
- **amount** (object) - Required - An object containing the payment amount and currency.
  - **amount** (integer) - Required - The amount the user has to pay. Maximum 11 characters.
  - **currency** (string) - Required - The currency of the amount (e.g., "JPY").
- **orderDescription** (string) - Optional - Description of the order. Maximum length is 255 characters.

### Request Example
```py
# Creating the payload to create a Payment, additional parameters can be added basis the API Documentation
request = {
    "merchantPaymentId": "my_payment_id",
    "userAuthorizationId": "my_user_authorization_id",
    "amount": {"amount": 1, "currency": "JPY"},
    "orderDescription": "Mune's Favourite Cake",
}
# Calling the method to create a payment
response = client.Payment.create(request)
# Printing if the method call was SUCCESS, this does not mean the payment was a success
print(response["resultInfo"]["code"])
```

### Response
#### Success Response (200)
- **resultInfo.code** (string) - Indicates 'SUCCESS' if the payment creation request was processed. Note: This does not confirm the payment itself was successful.

#### Response Example
```json
{
  "resultInfo": {
    "code": "SUCCESS",
    "message": ""
  }
}
```
```

--------------------------------

### Get PayPay OPA SDK Version

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

After initializing the PayPay OPA client, you can retrieve the current version of the SDK. This is useful for debugging and ensuring you are using a compatible version of the SDK.

```python
print(client.get_version())
```

--------------------------------

### GET /v1/cashback/reverse/{merchantCashbackReversalId}

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Retrieves the details of a specific cashback reversal.

```APIDOC
## GET /v1/cashback/reverse/{merchantCashbackReversalId}

### Description
Checks the status and details of a cashback reversal request.

### Method
GET

### Parameters
#### Path Parameters
- **merchantCashbackReversalId** (string) - Required - The reversal ID
- **merchantCashbackId** (string) - Required - The original cashback ID
```

--------------------------------

### Acquire User Authorization

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This section details the process of acquiring user authorization by creating a JWT token. It includes the necessary claims for the token and examples of encoding and decoding JWTs for authorization.

```APIDOC
## Acquire User Authorization

### Description
This endpoint facilitates acquiring user authorization by creating a JWT token. The process involves defining specific claims within the token, such as issuer, expiration, scope, nonce, redirect URL, reference ID, and optionally device ID and phone number. After user authorization, a UserAuthorizationID is returned.

### Method
POST (Implicit, via JWT creation)

### Endpoint
N/A (JWT creation)

### Parameters
#### JWT Claims
- **iss** (string) - Required - The merchant name.
- **exp** (number) - Required - The expiration date of the authorization page URL in epoch time (seconds).
- **scope** (string) - Required - Must be 'direct_debit'.
- **nonce** (string) - Required - Will be sent back with the response for client-side validation.
- **redirectUrl** (string) - Required - The callback endpoint provided by the client. Must be HTTPS, and its domain should be in the allowed authorization callback domains.
- **referenceId** (string) - Required - The ID used to identify the user in the merchant system.
- **deviceId** (string) - Optional - The user's mobile phone device ID. If provided, can be used to verify the user and skip SMS verification for a smoother UX.
- **phoneNumber** (string) - Optional - The user's mobile phone number.

### Request Example
```py
# Helper function to create a JWT Token for requesting user Authorization
client.encode_jwt(API_SECRET,
                redirectUrl = "https://example.com",
                deviceId = "qwertyuiopoiuytre54567",
                phoneNumber = 90999999999 )
```

### Response
#### Success Response
Upon successful authorization, a UserAuthorizationID is returned as part of a JWT Token in the response or webhook.

#### Response Example
```py
# Retrieving userAuthorizationId from response JWT
client.decode_jwt(API_SECRET, token)
```
```

--------------------------------

### GET /v2/refunds/{merchantRefundId}

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Fetch the status and details of a specific refund.

```APIDOC
## GET /v2/refunds/{merchantRefundId}

### Description
Retrieves the current status of a refund request.

### Method
GET

### Endpoint
/v2/refunds/{merchantRefundId}

### Parameters
#### Path Parameters
- **merchantRefundId** (string) - Required - The unique refund ID
```

--------------------------------

### GET /v1/payments/pending/{merchantPaymentId}/refund

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Retrieves refund details for a pending payment.

```APIDOC
## GET /v1/payments/pending/{merchantPaymentId}/refund

### Description
Fetches refund information for a transaction that is currently in a pending state.

### Method
GET

### Parameters
#### Path Parameters
- **merchantPaymentId** (string) - Required - The unique payment ID

### Response
#### Success Response (200)
- **resultInfo** (object) - Status code information
- **data** (object) - Transaction status details
```

--------------------------------

### Get Payment Details

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This section explains how to retrieve the status of a payment using the merchantPaymentId, particularly useful if the initial payment request timed out.

```APIDOC
## Get Payment Details

### Description
If a payment request times out, you can use this method to retrieve the current status of the payment using the unique merchant payment ID.

### Method
GET

### Endpoint
/v1/payment/{merchantPaymentId}

### Parameters
#### Path Parameters
- **merchantPaymentId** (string) - Required - The unique payment transaction ID provided by the merchant. Maximum length is 64 characters.

#### Query Parameters
None

#### Request Body
None

### Request Example
```py
# Calling the method to get payment details
response = client.Payment.get_payment_details("<merchantPaymentId>")
# Printing if the method call was SUCCESS, this does not mean the payment was a success
print(response["resultInfo"]["code"])
```

### Response
#### Success Response (200)
- **resultInfo.code** (string) - Indicates 'SUCCESS' if the payment details were retrieved. The actual payment status would be within the response body (not detailed here).

#### Response Example
```json
{
  "resultInfo": {
    "code": "SUCCESS",
    "message": ""
  }
}
```
```

--------------------------------

### Get Refund Details for Pending Payment (Python)

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Fetches refund details for a pending payment. This is used when a customer decides to return purchased goods. The method requires the `merchantPaymentId` and returns information about the refund status. The `client.Pending.refund_details` method is called.

```python
# Calling the method to cancel pending payment
response = client.Pending.refund_details("<merchantPaymentId>")
# Printing if the method call was SUCCESS, this does not mean the payment was a success
print(response["resultInfo"]["code"])
# Printing if the transaction status for the code has COMPLETED/ AUTHORIZED
print(response["data"]["status"])
```

--------------------------------

### GET /v2/codes/{merchantPaymentId}

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Retrieves the current status of a QR code payment. Used for polling to determine if a customer has completed the payment.

```APIDOC
## GET /v2/codes/{merchantPaymentId}

### Description
Retrieves the payment status for a specific QR code payment.

### Method
GET

### Endpoint
/v2/codes/{merchantPaymentId}

### Parameters
#### Path Parameters
- **merchantPaymentId** (string) - Required - The unique ID used when creating the QR code.

### Response
#### Success Response (200)
- **status** (string) - Current payment status (e.g., COMPLETED, AUTHORIZED, EXPIRED).

#### Response Example
{
  "data": {
    "status": "COMPLETED",
    "paymentId": "PAY-98765"
  }
}
```

--------------------------------

### Get Payment Details - Python

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Fetches the details of a specific payment using the merchantPaymentId. It is recommended to poll this endpoint every 4-5 seconds. The status in the response indicates if the payment is COMPLETED or AUTHORIZED (for preauth).

```python
client.Payment.get_payment_details("<merchantPaymentId>")
```

--------------------------------

### Get User Authorization Status - Python

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Checks the current status of a user's authorization using their unique authorization ID. This helps in verifying if a user has successfully linked their PayPay account.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

user_authorization_id = "user-auth-id-from-callback"

response = client.User.get_authorization_status(user_authorization_id)
print(f"Authorization Status: {response['resultInfo']['code']}")
```

--------------------------------

### Get Pending Payment Details - Python

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Retrieves the status of a pending payment request using the merchant payment ID. It requires the PayPay client to be initialized with API credentials.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

merchant_payment_id = "pending-order-12345"

response = client.Pending.get_payment_details(merchant_payment_id)
print(f"Status: {response['data']['status']}")
# PENDING, COMPLETED, CANCELED, EXPIRED
```

--------------------------------

### Get PayPay Refund Details

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Retrieves the status and detailed information of a previously requested PayPay refund. This function requires the merchant's refund ID to fetch the specific refund details.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

merchant_refund_id = "refund-12345"

response = client.Payment.refund_details(merchant_refund_id)
print(f"Refund Status: {response['data']['status']}")
print(f"Refund Amount: {response['data']['amount']['amount']}")
```

--------------------------------

### Get Pending Payment Details

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This code snippet illustrates how to retrieve the details of a pending payment, which is useful if the initial payment request times out. It requires the `merchantPaymentId` to be passed as an argument to the `get_payment_details` method. The snippet also shows how to check the response code to confirm the success of the API call.

```python
# Calling the method to get payment details
response = client.Pending.get_payment_details("<merchantPaymentId>")
# Printing if the method call was SUCCESS, this does not mean the payment was a success
print(response["resultInfo"]["code"])
```

--------------------------------

### Initialize PayPay OPA Python Client

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This Python code demonstrates how to initialize the PayPay OPA client. It shows configurations for both production and sandbox environments using API keys and secrets. The client is essential for making subsequent API calls.

```python
import paypayopa

# For production mode
API_KEY = "YOUR_PRODUCTION_API_KEY"
API_SECRET = "YOUR_PRODUCTION_API_SECRET"
client = paypayopa.Client(auth=(API_KEY, API_SECRET), production_mode=True)
client.set_assume_merchant("MERCHANT_ID")

# For sandbox mode (production_mode defaults to False)
API_KEY_SANDBOX = "YOUR_SANDBOX_API_KEY"
API_SECRET_SANDBOX = "YOUR_SANDBOX_API_SECRET"
client_sandbox = paypayopa.Client(auth=(API_KEY_SANDBOX, API_SECRET_SANDBOX))

```

--------------------------------

### Get Payment Details

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Retrieves the details of a payment associated with a merchant payment ID.

```APIDOC
## GET /v2/payments/{merchantPaymentId}

### Description
Fetches the details of a specific payment using the merchant payment ID. Recommended to poll this endpoint at a 4-5 second interval.

### Method
GET

### Endpoint
/v2/payments/{merchantPaymentId}

### Parameters
#### Path Parameters
- **merchantPaymentId** (string) - Required - The unique payment transaction id provided by the merchant.

### Response
#### Success Response (200)
- **status** (string) - The current status of the payment (e.g., COMPLETED, AUTHORIZED, PENDING).
- **amount** (object) - The payment amount.
  - **amount** (integer) - The payment amount.
  - **currency** (string) - The currency code.

#### Response Example
```json
{
  "status": "COMPLETED",
  "amount": {
    "amount": 1,
    "currency": "JPY"
  }
}
```
```

--------------------------------

### Create a QR Code

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Creates a QR code for receiving payments. This is the initial step for a payment flow.

```APIDOC
## POST /v2/codes

### Description
Creates a QR code that can be used to receive payments. This is the first step in the payment process.

### Method
POST

### Endpoint
/v2/codes

### Parameters
#### Request Body
- **merchantPaymentId** (string) - Required - The unique payment transaction id provided by the merchant, max 64 characters.
- **amount** (object) - Required - The amount the user has to pay.
  - **amount** (integer) - Required - The payment amount, max 11 characters.
  - **currency** (string) - Required - The currency code (e.g., JPY).
- **codeType** (string) - Required - The type of QR code. Must be "ORDER_QR".
- **orderDescription** (string) - Optional - Description of the order, max 255 characters.
- **isAuthorization** (boolean) - Optional - If true, the amount will be captured later (preauth and capture payment). Defaults to false.
- **redirectUrl** (string) - Optional - The URL to redirect the user to after payment.
- **redirectType** (string) - Optional - The type of redirect. Possible values: "WEB_LINK", "APP_LINK".
- **orderItems** (array) - Optional - Details of items in the order.
  - **name** (string) - Required - Name of the item.
  - **category** (string) - Required - Category of the item.
  - **quantity** (integer) - Required - Quantity of the item.
  - **productId** (string) - Required - Product ID.
  - **unitPrice** (object) - Required - Unit price of the item.
    - **amount** (integer) - Required - The unit price amount.
    - **currency** (string) - Required - The currency code.

### Request Example
```json
{
    "merchantPaymentId": "cb31bcc0-3b6c-46e0-9002-e5c4bb1e3d5f",
    "codeType": "ORDER_QR",
    "redirectUrl": "http://foobar.com",
    "redirectType":"WEB_LINK",
    "orderDescription":"Example - Mune Cake shop",
    "orderItems": [
        {
            "name": "Moon cake",
            "category": "pasteries",
            "quantity": 1,
            "productId": "67678",
            "unitPrice": {
                "amount": 1,
                "currency": "JPY"
            }
        }
    ],
    "amount": {
        "amount": 1,
        "currency": "JPY"
    }
}
```

### Response
#### Success Response (201)
- **codeId** (string) - The ID of the created QR code.
- **qrCodeString** (string) - The generated QR code string.
- **expiresAt** (string) - The expiration timestamp of the QR code.

#### Response Example
```json
{
  "codeId": "some_code_id",
  "qrCodeString": "some_qr_code_string",
  "expiresAt": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Create User Authorization Session - Python

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Creates a QR session for user authorization, enabling merchants to link a user's PayPay account. This involves specifying scopes, redirect types, and user/device identifiers.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

auth_request = {
    "scopes": ["direct_debit"],
    "nonce": "unique-random-string-12345",
    "redirectType": "WEB_LINK",
    "redirectUrl": "https://mystore.com/paypay-callback",
    "referenceId": "user-123-in-my-system",
    "phoneNumber": "09012345678",
    "deviceId": "device-unique-id"
}

response = client.Account.create_qr_session(auth_request)
print(f"Authorization URL: {response['data']['url']}")
# Redirect user to this URL to complete authorization
```

--------------------------------

### Get Pending Payment Details

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Retrieves the details and status of a pending payment using the merchantPaymentId.

```APIDOC
## GET /paypay/get_payment_details

### Description
Retrieves the details of a pending payment.

### Method
GET

### Endpoint
/paypay/get_payment_details

### Parameters
#### Query Parameters
- **merchantPaymentId** (string) - Required - The unique payment transaction id provided by merchant (<= 64 characters).

### Request Example
```python
response = client.Pending.get_payment_details("<merchantPaymentId>")
```

### Response
#### Success Response (200)
- **resultInfo** (object) - Information about the result of the operation.
  - **code** (string) - The result code.
- **data** (object) - Payment details.
  - **status** (string) - The status of the payment.

#### Response Example
```json
{
  "resultInfo": {
    "code": "SUCCESS"
  },
  "data": {
    "status": "COMPLETED"
  }
}
```
```

--------------------------------

### Unlink User

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This section describes how to unlink a user from the client using their UserAuthorizationId. It includes the required parameters and a Python code example.

```APIDOC
## Unlink User

### Description
This endpoint allows you to unlink a PayPay user from your client application using their unique UserAuthorizationId obtained during the authorization flow.

### Method
POST

### Endpoint
/v1/user/unlink

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **userAuthorizationId** (string) - Required - The PayPay user reference ID returned by the user authorization flow. Maximum length is 64 characters.

### Request Example
```py
# Calling the method to unlink a Payment
response = client.User.unlink_user_athorization('userAuthorizationId')
# Printing if the method call was SUCCESS
print(response["resultInfo"]["code"])
```

### Response
#### Success Response (200)
- **resultInfo.code** (string) - Indicates 'SUCCESS' if the unlinking operation was performed correctly.

#### Response Example
```json
{
  "resultInfo": {
    "code": "SUCCESS",
    "message": ""
  }
}
```
```

--------------------------------

### Create QR Code for Payment - Python

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Generates a QR code for receiving payments. Requires merchantPaymentId, codeType, and amount. Optionally accepts redirectUrl, orderDescription, and isAuthorization for preauth payments. The response includes a codeId for future reference.

```python
request = {
    "merchantPaymentId": "cb31bcc0-3b6c-46e0-9002-e5c4bb1e3d5f",
    "codeType": "ORDER_QR",
    "redirectUrl": "http://foobar.com",
    "redirectType":"WEB_LINK",
    "orderDescription":"Example - Mune Cake shop",
    "orderItems": [{
        "name": "Moon cake",
        "category": "pasteries",
        "quantity": 1,
        "productId": "67678",
        "unitPrice": {
            "amount": 1,
            "currency": "JPY",
        },
    }],
    "amount": {
        "amount": 1,
        "currency": "JPY",
    },
}

client.Code.create_qr_code(request)
```

--------------------------------

### Acquire User Authorization and Decode JWT

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Demonstrates how to construct the payload for user authorization and how to decode the resulting JWT token to retrieve the userAuthorizationId.

```python
payload = {
  "scopes": ["direct_debit"],
  "nonce": "rtyuhghj7989",
  "redirectType": "WEB_LINK",
  "redirectUrl": "www.example.com",
  "referenceId": "uioiugf789",
  "phoneNumber": "90999999999",
  "deviceId": "qwertyuiopoiuytre54567",
  "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
}

client.Account.create_qr_session(payload)

# Retrieving userAuthorizationId from response JWT
client.decode_jwt(API_SECRET, token)
```

--------------------------------

### Get Payment Details API

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Information on retrieving payment details, with specific error codes for not finding the payment or general bad requests.

```APIDOC
## Get Payment Details

### Response Codes

| Status  | CodeId  | Code                      | Message                |
|---|---|---------------------------|------------------------|
| 400     | 01652075                  | DYNAMIC_QR_PAYMENT_NOT_FOUND | Dynamic QR payment not found |
| 400     | 01650000                  | DYNAMIC_QR_BAD_REQUEST     | Dynamic QR bad request error |
```

--------------------------------

### Create Dynamic QR Code Payment

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Generates a dynamic QR code for customer scanning. Requires payment details like amount, order description, and redirect URLs to handle the post-payment flow.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

request = {
    "merchantPaymentId": "order-12345",
    "codeType": "ORDER_QR",
    "redirectUrl": "https://mystore.com/payment-complete",
    "redirectType": "WEB_LINK",
    "orderDescription": "Mune Cake Shop - Order #12345",
    "orderItems": [{
        "name": "Moon Cake",
        "category": "pastries",
        "quantity": 2,
        "productId": "prod-67678",
        "unitPrice": {
            "amount": 500,
            "currency": "JPY"
        }
    }],
    "amount": {
        "amount": 1000,
        "currency": "JPY"
    },
    "isAuthorization": False
}

response = client.Code.create_qr_code(request)
print(f"QR Code URL: {response['data']['url']}")
print(f"Code ID: {response['data']['codeId']}")
```

--------------------------------

### Create Payment Authorization

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Shows how to structure the payment authorization request payload and invoke the pre_authorize_create method using the PayPay OPA SDK.

```python
request_payload = {
    "merchantPaymentId": "merchant_payment_id",
    "userAuthorizationId": "user_authorization_id",
    "amount": {
      "amount": 26.00,
      "currency": "JPY"
    },
    "requestedAt": 5353454354,
    "orderReceiptNumber": "435435435",
    "orderDescription": "Mune's Favourite Cake",
  }

client.Preauth.pre_authorize_create(request_payload)
```

--------------------------------

### Execute Native Payment

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Initiates a direct payment using a user's pre-authorized account ID. This is typically used for subscription or one-click payment flows.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

request = {
    "merchantPaymentId": "native-payment-12345",
    "userAuthorizationId": "user-auth-id-from-authorization-flow",
    "amount": {
        "amount": 1500,
        "currency": "JPY"
    },
    "orderDescription": "Monthly Subscription - Premium Plan"
}

response = client.Payment.create(request)
if response["resultInfo"]["code"] == "SUCCESS":
    print(f"Payment ID: {response['data']['paymentId']}")
    print(f"Status: {response['data']['status']}")
```

--------------------------------

### Create a QRCode API

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Details for creating QR codes, including specific error codes related to duplicate requests or unsupported merchant features.

```APIDOC
## Create a QRCode

### Response Codes

| Status  | CodeId  | Code                      | Message                                                              | 
|---|---|---------------------------|----------------------------------------------------------------------|
| 400     | 01652073                  | DUPLICATE_DYNAMIC_QR_REQUEST          | Duplicate Dynamic QR request error                                   |
| 400     | 00400060                  | PRE_AUTH_CAPTURE_UNSUPPORTED_MERCHANT | Merchant do not support Pre-Auth-Capture                             |
| 400     | 00400061                  | PRE_AUTH_CAPTURE_INVALID_EXPIRY_DATE  | Provided Expiry Date is above the allowed limit of Max allowed expiry days |
| 400     | 01650000                  | DYNAMIC_QR_BAD_REQUEST                | Dynamic QR bad request error                                         |
```

--------------------------------

### POST /v2/cashback

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Issues cashback to a user's wallet.

```APIDOC
## POST /v2/cashback

### Description
Provides a cashback balance to a verified PayPay user.

### Method
POST

### Endpoint
/v2/cashback

### Parameters
#### Request Body
- **merchantCashbackId** (string) - Required - Unique cashback ID
- **userAuthorizationId** (string) - Required - PayPay user reference ID
- **amount** (object) - Required - Amount and currency
- **requestedAt** (integer) - Required - Epoch timestamp

### Request Example
{
  "merchantCashbackId": "ab31bcc0-3b6c-46e0-9002-e5c4bb1e3d5f",
  "userAuthorizationId": "3b6c-a7c9-9002-e5c4bb1e3d5f",
  "amount": {"amount": 100, "currency": "JPY"},
  "requestedAt": 1609749559
}
```

--------------------------------

### Cancel Payment - Python

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Cancels a payment transaction. This is typically used when the Get Payment Details polling times out and the payment status is uncertain. The cancellation is possible until 00:14:59 AM the day after the payment.

```python
client.Payment.cancel_payment("<merchantPaymentId>")
```

--------------------------------

### Create PayPay Payment Authorization (PreAuth)

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Creates a payment authorization on PayPay, reserving funds without immediate capture. The authorized amount can be captured later. This requires a pre-authorization request object including merchant payment ID, user authorization ID, amount, currency, and order description.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

preauth_request = {
    "merchantPaymentId": "preauth-order-12345",
    "userAuthorizationId": "user-auth-id",
    "amount": {
        "amount": 5000,
        "currency": "JPY"
    },
    "orderDescription": "Hotel Reservation - 2 nights"
}

response = client.Preauth.pre_authorize_create(preauth_request)
if response["resultInfo"]["code"] == "SUCCESS":
    print(f"Authorization Status: {response['data']['status']}")  # AUTHORIZED
    print(f"Payment ID: {response['data']['paymentId']}")
```

--------------------------------

### Create and Retrieve Payment Details

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Methods to initiate a payment transaction using a payload and to query the status of a payment using the merchantPaymentId. These are used for processing transactions and handling timeouts.

```python
# Creating the payload to create a Payment
request = {
    "merchantPaymentId": "my_payment_id",
    "userAuthorizationId": "my_user_authorization_id",
    "amount": {"amount": 1, "currency": "JPY"},
    "orderDescription": "Mune's Favourite Cake",
}
# Calling the method to create a payment
response = client.Payment.create(request)
print(response["resultInfo"]["code"])

# Calling the method to get payment details
response = client.Payment.get_payment_details("<merchantPaymentId>")
print(response["resultInfo"]["code"])
```

--------------------------------

### Give Cashback - Python

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Awards cashback to a user's PayPay wallet. This function requires user authorization with the 'cashback' scope and detailed transaction information.

```python
import paypayopa
import time

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

cashback_request = {
    "merchantCashbackId": "cashback-campaign-12345",
    "userAuthorizationId": "user-auth-id-with-cashback-scope",
    "amount": {
        "amount": 100,
        "currency": "JPY"
    },
    "requestedAt": int(time.time()),
    "orderDescription": "Welcome bonus cashback",
    "walletType": "PREPAID",
    "expiryDate": None,
    "metadata": {}
}

response = client.Cashback.give_cashback(cashback_request)
print(f"Cashback Result: {response['resultInfo']['code']}")
# REQUEST_ACCEPTED
```

--------------------------------

### POST /v2/payments/preauthorize

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Creates a payment authorization that reserves funds without capturing them immediately.

```APIDOC
## POST /v2/payments/preauthorize

### Description
Creates a payment authorization that reserves funds without capturing them.

### Method
POST

### Endpoint
/v2/payments/preauthorize

### Request Body
- **merchantPaymentId** (string) - Required - Unique ID for the order.
- **userAuthorizationId** (string) - Required - User authorization identifier.
- **amount** (object) - Required - Amount object.

### Response
#### Success Response (200)
- **data** (object) - Contains status and paymentId.
```

--------------------------------

### Give Cashback to User with PayPay SDK

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Grants cashback to a PayPay user. Requires user authorization and specific transaction metadata like amount and wallet type.

```python
payload = {
    "merchantCashbackId": "ab31bcc0-3b6c-46e0-9002-e5c4bb1e3d5f",
    "userAuthorizationId": "3b6c-a7c9-9002-e5c4bb1e3d5f",
    "amount": {
        "amount": 100,
        "currency": "JPY"
    },
    "requestedAt": 1609749559,
    "orderDescription": "order description",
    "walletType": "PREPAID",
    "expiryDate": None,
    "metadata": ""
}
client.Cashback.give_cashback(payload)
```

--------------------------------

### Check Cashback Reversal Details using PayPay OPA SDK

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

This snippet demonstrates how to retrieve the status of a specific cashback reversal. It requires the merchant cashback reversal ID and the merchant cashback ID as inputs to the client's Cashback module.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

merchant_cashback_reversal_id = "reversal-12345"
merchant_cashback_id = "cashback-campaign-12345"

response = client.Cashback.check_cashback_reversal_detail(
    merchant_cashback_reversal_id,
    merchant_cashback_id
)
print(f"Reversal Status: {response['resultInfo']['code']}")
```

--------------------------------

### Reverse Cashback Transaction (Python)

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Initiates a cashback reversal for a specific transaction. Requires merchant cashback reversal ID, merchant cashback ID, amount, currency, and optionally a reason and metadata. The function `client.Cashback.reverse_cashback` is used to execute this operation.

```python
payload = {
    "merchantCashbackReversalId": "e031bcc0-3b6c-9a7d-9002-e5c4cc1e3d5f",
    "merchantCashbackId": "ab31bcc0-3b6c-46e0-9002-e5c4bb1e3d5f",
    "amount": {
        "amount": 100,
        "currency": "JPY"
    },
    "requestedAt": 1609749559,
    "reason": "reversal reason",
    "metadata": {}
}
client.Cashback.reverse_cashback(payload)
```

--------------------------------

### Create Pending Payment Authorization

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This section details the process of creating a pending payment authorization. It requires a specific request payload including merchant payment ID, user authorization ID, amount, and timestamp. The `create_pending_payment` method is then invoked. The snippet also shows how to verify the API call's success and provides guidance on checking the payment status and referring to the API documentation for more details.

```python
# Creating the payload for a payment authorization request, additional parameters can be added basis the API Documentation
request_payload = {
  "merchantPaymentId": "merchant_payment_id",
  "userAuthorizationId": "my_user_authorization_id",
  "amount": {
    "amount": 1,
    "currency": "JPY"
  },
  "requestedAt": 1632123456,
  "expiryDate": None,
  "storeId": "001",
  "terminalId": "0042",
  "orderReceiptNumber": "0878",
  "orderDescription": "Example - Mune Cake shop",
    "orderItems": [
        {
            "name": "Moon cake",
            "category": "pasteries",
            "quantity": 1,
            "productId": "67678",
            "unitPrice": {
                "amount": 1,
                "currency": "JPY"
            }
        }
    ],
  "metadata": {}
}

# Calling the method to create a continuous payment authorization
client.Pending.create_pending_payment(request_payload)

# Printing if the method call was SUCCESS, this does not mean the payment was a success
print(response["resultInfo"]["code"])
```

--------------------------------

### POST /v2/codes

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Creates a dynamic QR code for merchant payments. This endpoint allows merchants to define order details, amounts, and redirect behavior for the customer.

```APIDOC
## POST /v2/codes

### Description
Creates a dynamic QR code that customers can scan to initiate a payment.

### Method
POST

### Endpoint
/v2/codes

### Parameters
#### Request Body
- **merchantPaymentId** (string) - Required - Unique ID for the payment generated by the merchant.
- **codeType** (string) - Required - Type of code (e.g., ORDER_QR).
- **amount** (object) - Required - Amount object containing amount and currency.
- **redirectUrl** (string) - Optional - URL to redirect the user after payment.

### Request Example
{
  "merchantPaymentId": "order-12345",
  "codeType": "ORDER_QR",
  "amount": {"amount": 1000, "currency": "JPY"}
}

### Response
#### Success Response (200)
- **codeId** (string) - Unique identifier for the generated QR code.
- **url** (string) - The URL of the generated QR code.

#### Response Example
{
  "data": {
    "codeId": "04-ABCDEF123456",
    "url": "https://qr.paypay.ne.jp/..."
  }
}
```

--------------------------------

### Create Continuous Payment Authorization

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This snippet demonstrates how to create a continuous payment authorization request. It involves constructing a request payload with payment details and then calling the `create_continuous_payment` method on the client's Payment object. The success of the API call is indicated by checking the response code.

```python
# Creating the payload for a payment authorization request, additional parameters can be added basis the API Documentation
request_payload = {
    "merchantPaymentId": "merchant_payment_id",
    "userAuthorizationId": "my_user_authorization_id",
    "orderDescription": "Mune's Favourite Cake",
    "amount": {
        "amount": 1,
        "currency": "JPY"
    }
}

# Calling the method to create a continuous payment authorization
client.Payment.create_continuous_payment(request_payload)

# Printing if the method call was SUCCESS, this does not mean the payment was a success
print(response["resultInfo"]["code"])
```

--------------------------------

### POST /v2/payments

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

Initiates a native payment using a user's stored authorization ID. This is typically used for recurring or one-click payments.

```APIDOC
## POST /v2/payments

### Description
Creates a direct payment using a user's stored authorization.

### Method
POST

### Endpoint
/v2/payments

### Parameters
#### Request Body
- **merchantPaymentId** (string) - Required - Unique ID for the payment.
- **userAuthorizationId** (string) - Required - The authorization ID linked to the user.
- **amount** (object) - Required - Payment amount and currency.

### Request Example
{
  "merchantPaymentId": "native-payment-12345",
  "userAuthorizationId": "auth-id-123",
  "amount": {"amount": 1500, "currency": "JPY"}
}

### Response
#### Success Response (200)
- **paymentId** (string) - The PayPay payment ID.
- **status** (string) - Status of the payment.

#### Response Example
{
  "data": {
    "paymentId": "PAY-123",
    "status": "COMPLETED"
  }
}
```

--------------------------------

### Acquire User Authorization

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

This endpoint is used to initiate the user authorization flow, allowing users to grant permissions for various operations.

```APIDOC
## Acquire User Authorization

### Description
Initiates the user authorization flow to grant permissions for operations like direct debit, cashback, balance checks, etc.

### Method
POST

### Endpoint
/v1/account/authorize

### Parameters
#### Query Parameters
- **scopes** (Array of string) - Required - Scopes of the user authorization. Enum: 'direct_debit', 'cashback', 'get_balance', 'quick_pay', 'continuous_payments', 'merchant_topup', 'pending_payments', 'user_notification', 'user_topup', 'user_profile', 'preauth_capture_native', 'preauth_capture_transaction', 'push_notification', 'notification_center_ob', 'notification_center_ab', 'notification_center_tl'
- **nonce** (string) - Required - Random generated string.
- **redirectType** (string) - Optional - Parameter to decide whether to redirect to merchant app or merchant web application. Enum: 'APP_DEEP_LINK', 'WEB_LINK'. Default: 'WEB_LINK'.
- **redirectUrl** (string) - Required - The callback endpoint provided by client. For 'WEB_LINK' it must be HTTPS, and its domain should be in the allowed authorization callback domains.
- **referenceId** (string) - Required - The id used to identify the user in merchant system. It will be stored in the PayPay db for reconciliation purpose.
- **phoneNumber** (string) - Optional - The user mobile phone number.
- **deviceId** (string) - Optional - The user mobile phone device id. If provided, can be used to verify the user and skip SMS verification for a more fluent UX.
- **userAgent** (string) - Optional - The User agent of the web browser. Provided when redirectType is 'WEB_LINK'. On mobile devices, PayPay tries to open the browser that the merchant website is using.

### Request Example
```python
payload = {
  "scopes": [
    "direct_debit"
  ],
  "nonce": "rtyuhghj7989",
  "redirectType": "WEB_LINK",
  "redirectUrl": "www.example.com",
  "referenceId": "uioiugf789",
  "phoneNumber": "90999999999",
  "deviceId": "qwertyuiopoiuytre54567",
  "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
}

client.Account.create_qr_session(payload)
```

### Response
#### Success Response (200)
- **token** (string) - JWT Token containing the UserAuthorizationID.

#### Response Example
```python
# Retrieving userAuthorizationId from response JWT
client.decode_jwt(API_SECRET, token)
```
```

--------------------------------

### POST /v1/cashback/reverse

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Reverses a previously processed cashback transaction.

```APIDOC
## POST /v1/cashback/reverse

### Description
Reverses a cashback transaction initiated by the merchant.

### Method
POST

### Parameters
#### Request Body
- **merchantCashbackReversalId** (string) - Required - Unique reversal ID
- **merchantCashbackId** (string) - Required - Original cashback ID
- **amount** (integer) - Required - Amount to reverse
- **currency** (string) - Required - Currency code (e.g., JPY)
- **reason** (string) - Optional - Reason for reversal
- **metadata** (string) - Optional - Extra info

### Request Example
{
  "merchantCashbackReversalId": "e031bcc0-3b6c-9a7d-9002-e5c4cc1e3d5f",
  "merchantCashbackId": "ab31bcc0-3b6c-46e0-9002-e5c4bb1e3d5f",
  "amount": {
    "amount": 100,
    "currency": "JPY"
  },
  "requestedAt": 1609749559,
  "reason": "reversal reason",
  "metadata": {}
}
```

--------------------------------

### Implement API Error Handling for PayPay Payments

Source: https://context7.com/paypay/paypayopa-sdk-python/llms.txt

This snippet shows how to handle various API response codes when creating a payment. It uses a try-except block to catch value errors and conditional logic to interpret specific result codes returned by the SDK.

```python
import paypayopa

client = paypayopa.Client(auth=("API_KEY", "API_SECRET"))

try:
    response = client.Payment.create({
        "merchantPaymentId": "test-123",
        "userAuthorizationId": "invalid-auth-id",
        "amount": {"amount": 100, "currency": "JPY"}
    })

    result_code = response["resultInfo"]["code"]

    if result_code == "SUCCESS":
        print("Payment successful")
    elif result_code == "INVALID_REQUEST_PARAMS":
        print(f"Invalid parameters: {response['resultInfo']['message']}")
    elif result_code == "UNAUTHORIZED":
        print("Authentication failed - check API credentials")
    elif result_code == "UNACCEPTABLE_OP":
        print("Operation not permitted - check user authorization")
    elif result_code == "NO_SUFFICIENT_FUND":
        print("User has insufficient balance")
    elif result_code == "RATE_LIMIT":
        print("Too many requests - implement backoff")
    else:
        print(f"Error: {response['resultInfo']['code']} - {response['resultInfo']['message']}")

except ValueError as e:
    print(f"Missing required parameter: {e}")
```

--------------------------------

### Fetch Refund Status and Details

Source: https://github.com/paypay/paypayopa-sdk-python/blob/master/README.md

Retrieves the current status and details of a specific refund request using the merchantRefundId. Useful for verifying the outcome of a refund operation.

```python
response = client.Payment.refund_details("<merchantRefundId>")
print(response["resultInfo"]["code"])
```