### Upgrade Magento Setup

Source: https://developers.upayments.com/reference/magento

Commands to upgrade the Magento 2 setup after installing or enabling a new module. This ensures all database schema and data updates are applied.

```bash
php bin/magento setup:upgrade
```

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

### Example Return URL with Parameters

Source: https://developers.upayments.com/reference/addcharge

Demonstrates a typical return URL structure after a successful payment, including various transaction and order-related parameters.

```text
https://upayments.com/en/?payment_id=100527020000000598&result=CAPTURED&post_date=0927
&tran_id=527020000293353&ref=527020000040&track_id=019988a5066a999800a57eb83d309bafv2
&auth=B54978&order_id=019988a5066a999800a57eb83d309bae&requested_order_id=202210101255255144669
&refund_order_id=019988a5066a999800a57eb83d309bae&payment_type=knet&invoice_id=6058253
&transaction_date=2025-09-27%2003%3A09%3A49&receipt_id=019988a5066a999800a57eb83d309bae&trn_udf=User%20define%20data
```

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

### Add Card Response Example (cURL)

Source: https://developers.upayments.com/reference/cards-1

This snippet shows an example of a successful response (HTTP 201) from the UPayments Add Card API when using cURL. It confirms the data was received and provides a link for card management.

```json
{
  "status": true,
  "message": "Data received successfully",
  "data": {
    "link": "https://sandbox.upayments.com/my-cards?session_id=0667021n1210651V22U2FHj75672416644M754i1254kC2"
  }
}
```

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

### Create Customer Unique Token API Request Examples

Source: https://developers.upayments.com/reference/tokens

Provides cURL examples for making a POST request to the create customer unique token API endpoint. Includes headers for authorization and content type, and a JSON payload with the customer unique token.

```shell
curl --request POST \
     --url https://sandboxapi.upayments.com/api/v1/create-customer-unique-token \
     --header 'Authorization: Bearer jtest123' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "customerUniqueToken": "9904917379121"
}'
```

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

### Multi-Vendor Payment Splitting

Source: https://developers.upayments.com/reference/faqs

This section details how to split a customer payment between multiple vendors, including the calculation of commissions and delivery fees, and provides a request example.

```APIDOC
## POST /api/payments/multivendor

### Description
This endpoint allows for splitting a single customer payment among multiple vendors, calculating commissions and delivery fees for each vendor and the administrator.

### Method
POST

### Endpoint
/api/payments/multivendor

### Parameters
#### Request Body
- **products** (array) - Required - An array of product objects.
  - **name** (string) - Required - The name of the product.
  - **price** (number) - Required - The price of the product.
  - **quantity** (number) - Required - The quantity of the product.
- **order** (object) - Required - Details of the order.
  - **id** (string) - Required - The unique identifier for the order.
  - **reference** (string) - Required - A reference number for the order.
  - **description** (string) - Required - A description of the order.
  - **currency** (string) - Required - The currency of the order (e.g., KWD).
  - **amount** (number) - Required - The total amount of the order.
- **extraMerchantData** (array) - Required - An array defining each vendor's share and associated fees.
  - **amount** (number) - Required - The amount to be allocated to the vendor.
  - **ccCharge** (number) - Required - The credit card charge amount.
  - **ccChargeType** (string) - Required - The type of credit card charge (e.g., 'percentage').
  - **knetCharge** (number) - Required - The KNET charge amount.
  - **knetChargeType** (string) - Required - The type of KNET charge (e.g., 'percentage').
  - **ibanNumber** (string) - Required - The IBAN number of the vendor.

### Request Example
```json
{
  "products": [
    { "name": "Logitech K380", "price": 500, "quantity": 1 },
    { "name": "Logitech M171 Wireless Optical Mouse", "price": 500, "quantity": 1 }
  ],
  "order": {
    "id": "202210101255255144669",
    "reference": "11111991",
    "description": "Purchase order received for Logitech",
    "currency": "KWD",
    "amount": 1200
  },
  "extraMerchantData": [
    {
      "amount": 600,
      "ccCharge": 25,
      "ccChargeType": "percentage",
      "knetCharge": 25,
      "knetChargeType": "percentage",
      "ibanNumber": "1111111111111111"
    },
    {
      "amount": 600,
      "ccCharge": 25,
      "ccChargeType": "percentage",
      "knetCharge": 25,
      "knetChargeType": "percentage",
      "ibanNumber": "2222222222222222"
    }
  ]
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the payment was processed.
- **details** (object) - Details about the transaction split.
  - **vendor1** (object) - Details for the first vendor.
    - **receivedAmount** (number) - The amount received by the vendor.
  - **vendor2** (object) - Details for the second vendor.
    - **receivedAmount** (number) - The amount received by the vendor.
  - **adminEarnings** (object) - Details of the administrator's earnings.
    - **commission** (number) - The total commission earned by the admin.
    - **deliveryFee** (number) - The total delivery fee earned by the admin.

#### Response Example
```json
{
  "message": "Payment split successfully.",
  "details": {
    "vendor1": {
      "receivedAmount": 450
    },
    "vendor2": {
      "receivedAmount": 450
    },
    "adminEarnings": {
      "commission": 100,
      "deliveryFee": 200
    }
  }
}
```

**Note:** The sum of all `extraMerchantData.amount` must equal `order.amount`. This method supports any number of vendors, variable prices, delivery fees, and commission rates.
```

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

### GET /check-refund/{order_id}

Source: https://developers.upayments.com/reference/checkrefund

Retrieves the refund status for a given order ID. This endpoint is useful for checking if a refund has been processed and when it was completed.

```APIDOC
## GET /check-refund/{order_id}

### Description
This API is designed for checking the specific refund status of a transaction based on the orderId received after successfully creating a refund. You need to pass the `order_id` that you received in a response from the Get Payment Status API, or from Webhook.

### Method
GET

### Endpoint
https://sandboxapi.upayments.com/api/v1/check-refund/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier for the order to check the refund status.

#### Query Parameters
None

#### Request Body
None

### Request Example
(No request body is required for this GET request)

### Response
#### Success Response (201)
- **status** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the outcome of the request.
- **data** (object) - Contains refund details.
  - **is_refunded** (boolean) - True if the refund has been processed, false otherwise.
  - **refunded_date** (string) - The date and time when the refund was processed, in 'YYYY-MM-DD HH:MM:SS' format.

#### Response Example
```json
{
    "status": true,
    "message": "Response received successfully",
    "data": {
        "is_refunded": true,
        "refunded_date": "2024-06-11 17:16:51"
    }
}
```

#### Error Response (404)
- **status** (boolean) - Indicates if the request was successful (will be false for errors).
- **message** (string) - A message describing the error.
- **data** (array) - An empty array for this error case.

#### Error Response Example
```json
{
  "status": false,
  "message": "Transaction not found",
  "data": []
}
```
```

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

### Get Multi-merchant Refund Status API Definition

Source: https://developers.upayments.com/reference/checkrefundstatus

Defines the GET endpoint '/check-refund-status/{order_id}' for checking the refund status of a transaction. It requires an order_id in the path and an Authorization header with a JWT Bearer Token. The response includes transaction status and refund details.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "sandbox-api-base-url",
    "version": "2.0"
  },
  "servers": [
    {
      "url": "https://sandboxapi.upayments.com/api/v1/"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/check-refund-status/{order_id}": {
      "get": {
        "summary": "Get Multi-merchant Refund Status",
        "description": "This API is designed for checking the refund status of a transaction based on the order_id received after successful payment.",
        "operationId": "checkrefundstatus",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "schema": {
              "type": "string",
              "default": "k4eJmnNR8p9c7cf29bc74e46feabbff746da2eae57v29c7cf354d55441108e82c3fc8c879656"
            },
            "required": true
          },
          {
            "name": "Authorization",
            "in": "header",
            "schema": {
              "type": "string",
              "default": "Bearer e66a94d579cf75fba327ff716ad68c53aae11528"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "201",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"status\": true,\n    \"message\": \"success\",\n    \"data\": {\n        \"orderId\": \"202309470620061311821887650932\",\n        \"isMultivendorRefund\": true,\n        \"refundPayload\": [\n            {\n                \"refundRequestId\": \"b2JxTEcyeDhEaw==\",\n                \"ibanNumber\": \"KW91KFHO0000000000051010173254\",\n                \"totalPaid\": \"10.000\",\n                \"refundedAmount\": 0,\n                \"remainingLimit\": 10,\n                \"amountToRefund\": 0,\n                \"merchantType\": \"vendor\"\n            },\n            {\n                \"refundRequestId\": \"TWw1THI1YjhLcQ==\",\n                \"ibanNumber\": \"KW31NBOK0000000000002010177457\",\n                \"totalPaid\": \"10.000\",\n                \"refundedAmount\": 0,\n                \"remainingLimit\": 10,\n                \"amountToRefund\": 0,\n                \"merchantType\": \"vendor\"\n            }\n        ],\n        \"multivendor_refund_end_point\": \"http://127.0.0.1:8000/api/v1/create-multivendor-refund\"\n    }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "message": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "orderId": {
                          "type": "string",
                          "example": "202309470620061311821887650932"
                        },
                        "isMultivendorRefund": {
                          "type": "boolean",
                          "example": true,
                          "default": true
                        },
                        "refundPayload": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "refundRequestId": {
                                "type": "string",
                                "example": "b2JxTEcyeDhEaw=="
                              },
                              "ibanNumber": {
                                "type": "string",
                                "example": "KW91KFHO0000000000051010173254"
                              },
                              "totalPaid": {
                                "type": "string",
                                "example": "10.000"
                              },
                              "refundedAmount": {
                                "type": "integer",
                                "example": 0,
                                "default": 0
                              },
                              "remainingLimit": {
                                "type": "integer",
                                "example": 10,
                                "default": 0
                              },
                              "amountToRefund": {
                                "type": "integer",
                                "example": 0,
                                "default": 0
                              }
                            }
                          }
                        },
                        "multivendor_refund_end_point": {
                          "type": "string",
                          "example": "http://127.0.0.1:8000/api/v1/create-multivendor-refund"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

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

### Using Live Cards in Production

Source: https://developers.upayments.com/reference/go-live-checklist

An important note emphasizing the necessity of using live credit/debit cards for testing transactions in the production environment.

```APIDOC
## Production Environment Card Usage

### Description
When conducting transactions in the production environment, it is crucial to use actual live credit or debit cards. Test cards will not function in the production environment.

### Note
Ensure you are using valid, live payment methods for any testing or transactions performed on the production API.
```

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

### Create Refunds (Sandbox)

Source: https://developers.upayments.com/reference/upgrade-from-v1-to-v2

This endpoint allows you to create refunds in the UInterface V2 Sandbox Testing Environment.

```APIDOC
## POST /api/v1/create-refund

### Description
Creates a refund in the UInterface V2 Sandbox Testing Environment.

### Method
POST

### Endpoint
https://sandboxapi.upayments.com/api/v1/create-refund

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **payment_id** (string) - Required - The ID of the payment to refund.
- **amount** (number) - Required - The amount to refund.

### Request Example
```json
{
  "payment_id": "pay_abc123",
  "amount": 25.00
}
```

### Response
#### Success Response (200)
- **refund_id** (string) - The unique identifier for the refund.
- **status** (string) - The status of the refund.

#### Response Example
```json
{
  "refund_id": "ref_def456",
  "status": "PENDING"
}
```
```

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

### Get Single Refund Status API Request

Source: https://developers.upayments.com/reference/checkrefund

This snippet shows the request URL for checking the refund status of a specific order. The `order_id` is a required path parameter. Authentication is typically handled via a Bearer token in the Authorization header.

```text
https://sandboxapi.upayments.com/api/v1/check-refund/9c7cf29bc74e46feabbff746da2eae57v2
```

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

### Initiate Payment

Source: https://developers.upayments.com/reference/create-invoice

Initiates a payment transaction with the provided details. This endpoint accepts customer information, return URLs, and optional plugin configurations.

```APIDOC
## POST /api/payments

### Description
Initiates a payment transaction with the provided details. This endpoint accepts customer information, return URLs, and optional plugin configurations.

### Method
POST

### Endpoint
/api/payments

### Parameters
#### Request Body
- **orderId** (string) - mandatory - Refers to the order or transaction ID in your own system we will save your ID for our reference.
- **customer** (object) - mandatory
  - **customer.uniqueId** (string) - mandatory - Pass customer unique ID for our reference
  - **customer.name** (string) - mandatory - Pass customer name for our reference
  - **customer.email** (string) - mandatory - Pass customer email address here. If **notificationType = email** customer will receive the payment receipt on this email address.
  - **customer.mobile** (number) - mandatory - Pass customer phone number here. If **notificationType = mobile** customer will receive the payment sms on this mobile number.
- **returnUrl** (string) - mandatory - The return URL you like to have the successful payment
- **cancelUrl** (string) - mandatory - The cancel URL you like to have the cancel or failure payment
- **notificationUrl** (string) - mandatory - The notification URL will receive the webhook data
- **plugin** (object) - optional
  - **plugin.src** (string) - optional - Supported plugin opencart,whmcs,cscart,opencart,woocommerce,magento,ecwid

### Request Example
```json
{
  "orderId": "YOUR_ORDER_ID",
  "customer": {
    "uniqueId": "CUSTOMER_UNIQUE_ID",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "mobile": 1234567890
  },
  "returnUrl": "https://yourdomain.com/success",
  "cancelUrl": "https://yourdomain.com/cancel",
  "notificationUrl": "https://yourdomain.com/webhook",
  "plugin": {
    "src": "woocommerce"
  }
}
```

### Response
#### Success Response (200)
- **paymentUrl** (string) - The URL to redirect the customer for payment.

#### Response Example
```json
{
  "paymentUrl": "https://paymentgateway.com/pay?token=ABCDEFG"
}
```
```

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

### Create Multi-Vendor Refunds (Sandbox)

Source: https://developers.upayments.com/reference/upgrade-from-v1-to-v2

This endpoint allows you to create multi-vendor refunds in the UInterface V2 Sandbox Testing Environment.

```APIDOC
## POST /api/v1/create-multivendor-refund

### Description
Creates multi-vendor refunds in the UInterface V2 Sandbox Testing Environment.

### Method
POST

### Endpoint
https://sandboxapi.upayments.com/api/v1/create-multivendor-refund

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **payment_id** (string) - Required - The ID of the payment to refund.
- **refunds** (array) - Required - A list of refunds to process.
  - **vendor_id** (string) - Required - The ID of the vendor.
  - **amount** (number) - Required - The amount to refund for this vendor.

### Request Example
```json
{
  "payment_id": "pay_abc123",
  "refunds": [
    {
      "vendor_id": "vendor_1",
      "amount": 10.00
    },
    {
      "vendor_id": "vendor_2",
      "amount": 15.00
    }
  ]
}
```

### Response
#### Success Response (200)
- **refund_ids** (array) - A list of unique identifiers for the refunds.
- **status** (string) - The overall status of the multi-vendor refund.

#### Response Example
```json
{
  "refund_ids": ["ref_mv1", "ref_mv2"],
  "status": "PROCESSING"
}
```
```

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

### Create Payment Request (Sandbox)

Source: https://developers.upayments.com/reference/upgrade-from-v1-to-v2

This endpoint allows you to create a payment request in the UInterface V2 Sandbox Testing Environment.

```APIDOC
## POST /api/v1/charge

### Description
Creates a payment request in the UInterface V2 Sandbox Testing Environment.

### Method
POST

### Endpoint
https://sandboxapi.upayments.com/api/v1/charge

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - The amount of the payment.
- **currency** (string) - Required - The currency of the payment.
- **description** (string) - Optional - A description for the payment.
- **customer_id** (string) - Optional - The ID of the customer.

### Request Example
```json
{
  "amount": 100.50,
  "currency": "USD",
  "description": "Test payment",
  "customer_id": "cust_123"
}
```

### Response
#### Success Response (200)
- **payment_id** (string) - The unique identifier for the payment.
- **redirect_url** (string) - The URL to redirect the user to complete the payment.

#### Response Example
```json
{
  "payment_id": "pay_abc123",
  "redirect_url": "https://sandbox.upayments.com/pay?id=pay_abc123"
}
```
```

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

### GET /get-payment-status/{track_id}

Source: https://developers.upayments.com/reference/checkpaymentstatus

Retrieves the payment status for a given transaction using the track ID.

```APIDOC
## GET /get-payment-status/{track_id}

### Description
Retrieves the payment status for a given transaction using the track ID.

### Method
GET

### Endpoint
https://sandboxapi.upayments.com/api/v1/get-payment-status/{track_id}

### Parameters
#### Path Parameters
- **track_id** (string) - Required - The unique identifier for tracking the payment.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "GET /get-payment-status/9bf8387bd32d45dda56f6c1c009eca4f"
}
```

### Response
#### Success Response (201)
- **status** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the outcome of the request.
- **data** (object) - Contains the transaction details.
  - **transaction** (object) - Details of the payment transaction.
    - **order_id** (string) - The order ID associated with the transaction.
    - **refund_order_id** (string) - The refund order ID, if applicable.
    - **payment_id** (string) - The unique ID for the payment.
    - **result** (string) - The result of the payment (e.g., "CAPTURED").
    - **payment_type** (string) - The method used for payment (e.g., "knet").
    - **track_id** (string) - The tracking ID for the payment.
    - **transaction_date** (string) - The date and time of the transaction.
    - **is_save_card** (boolean) - Whether the card was saved for future use.
    - **from_plugin** (boolean) - Whether the transaction originated from a plugin.
    - **product_details** (string) - Details about the purchased products.
    - **reference** (string) - A reference number for the transaction.
    - **total_paid_non_kwd** (string) - The total amount paid in non-KWD currency.
    - **total_price** (string) - The total price of the order.
    - **currency_type** (string) - The currency used for the transaction (e.g., "KWD").
    - **status** (string) - The overall status of the payment (e.g., "done").
    - **session_id** (string) - The session ID for the transaction.
    - **error_url** (string) - The URL to redirect to in case of an error.
    - **success_url** (string) - The URL to redirect to upon successful payment.
    - **redirect_url** (string) - The URL for payment redirection.
    - **notify_url** (string) - The URL to send payment notifications to.
    - **notify_url_called** (boolean) - Indicates if the notification URL was called.
    - **notify_url_response** (string) - The response from the notification URL.
    - **whitelabled** (boolean) - Indicates if the service is whitelabeled.
    - **customer_id** (integer) - The ID of the customer.
    - **customer_unique_id** (string) - A unique identifier for the customer.
    - **merchant_requested_order_id** (string) - The order ID requested by the merchant.
    - **extra_merchants_data** (any) - Additional data from merchants, can be null.
    - **is_paid_from_knet** (boolean) - Whether the payment was made via KNET.
    - **is_paid_from_cc** (boolean) - Whether the payment was made via credit card.
    - **is_from_nbk** (boolean) - Whether the transaction is from NBK.
    - **customer_extra_data** (string) - Additional data provided by the customer.
    - **created_at** (string) - The timestamp when the transaction was created.

#### Response Example
```json
{
  "status": true,
  "message": "Response received successfully",
  "data": {
    "transaction": {
      "order_id": "9bf8387beea04c368be502649d3fcbc8",
      "refund_order_id": "9bf8387beea04c368be502649d3fcbc8",
      "payment_id": "100412610000005799",
      "result": "CAPTURED",
      "payment_type": "knet",
      "track_id": "9bf8387bd32d45dda56f6c1c009eca4f",
      "transaction_date": "2024-05-05 13:14:01",
      "is_save_card": false,
      "from_plugin": false,
      "product_details": "{\"title\":[\"Logitech K380\",\"Logitech M171 Wireless Optical Mouse\"],\"name\":[\"Logitech K380 \\/ Easy-Switch for Upto 3 Devices, Slim Bluetooth Tablet Keyboar\",\"Logitech M171 Wireless Optical Mouse  (2.4GHz Wireless, Blue Grey)\"],\"price\":[10,10],\"qty\":[1,1],\"more_details\":\"\"}",
      "reference": "202210101202210101",
      "total_paid_non_kwd": "20.000",
      "total_price": "20.000",
      "currency_type": "KWD",
      "status": "done",
      "session_id": "de561c446f23ff03884dde2c81707219",
      "error_url": "https://error.com",
      "success_url": "https://upayments.com/en/",
      "redirect_url": "https://upayments.com/en/?payment_id=100412610000005799&result=CAPTURED&post_date=&tran_id=&ref=&track_id=9bf8387bd32d45dda56f6c1c009eca4f&auth=&order_id=9bf8387beea04c368be502649d3fcbc8&requested_order_id=202210101255255144669&refund_order_id=9bf8387beea04c368be502649d3fcbc8&payment_type=knet&invoice_id=5973181&transaction_date=2024-05-05 01:05:14&receipt_id=9bf8387beea04c368be502649d3fcbc8&trn_udf=User define data",
      "notify_url": "https://webhook.site/2547b895-5899-4a21-a6f2-ed34c4228216",
      "notify_url_called": true,
      "notify_url_response": "{\"success\":true,\"message\":\"Success\",\"data\":null}",
      "whitelabled": true,
      "customer_id": 2962509,
      "customer_unique_id": "2129879kjbljg767881",
      "merchant_requested_order_id": "202210101255255144669",
      "extra_merchants_data": null,
      "is_paid_from_knet": true,
      "is_paid_from_cc": false,
      "is_from_nbk": false,
      "customer_extra_data": "User define data",
      "created_at": "2024-05-05 13:14:01"
    }
  }
}
```
```

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

### GET /api/v1/get-payment-status?session_id={session_id}

Source: https://developers.upayments.com/reference/checkpaymentstatus

Retrieve payment status using the transaction session ID.

```APIDOC
## GET /api/v1/get-payment-status?session_id={session_id}

### Description
Retrieves the status of a payment using the `session_id`, a system-generated identifier for the transaction session. This ID can be found in the response of a charge request.

### Method
GET

### Endpoint
/api/v1/get-payment-status

### Parameters
#### Query Parameters
- **session_id** (string) - Required - The system-generated identifier for the transaction session.

### Request Example
```json
{
  "example": "https://sandbox.upayments.com/api/v1/get-payment-status?session_id=2025133235031228373483523989923251714885916179872"
}
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the payment (e.g., 'SUCCESS', 'FAILED', 'PENDING').
- **transaction_id** (string) - The internal transaction identifier.
- **amount** (number) - The transaction amount.
- **currency** (string) - The transaction currency.

#### Response Example
```json
{
  "example": {
    "status": "SUCCESS",
    "transaction_id": "txn_12345abcde",
    "amount": 100.50,
    "currency": "USD"
  }
}
```
```

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

### Webhooks

Source: https://developers.upayments.com/reference/overview

Implement webhooks to receive real-time server-to-server payment status notifications for reliable updates.

```APIDOC
## Webhooks

### Description
Webhooks provide real-time, server-to-server notifications about payment status changes. Implementing webhooks is the most reliable way to track transaction outcomes, especially in scenarios where customer redirects might fail.

### Method
POST (typically, but depends on your webhook implementation)

### Endpoint
[Your specified webhook URL]

### Parameters
(Payload structure will vary based on the event type, but common fields include:)
#### Request Body (Example for Payment Success)
- **eventType** (string) - The type of event (e.g., 'PAYMENT_SUCCESS', 'PAYMENT_FAILED').
- **transactionId** (string) - The ID of the transaction.
- **orderId** (string) - The order ID associated with the transaction.
- **amount** (number) - The transaction amount.
- **currency** (string) - The currency of the transaction.
- **timestamp** (string) - The time the event occurred.

### Request Example (Illustrative Payload)
```json
{
  "eventType": "PAYMENT_SUCCESS",
  "transactionId": "txn_123456789",
  "orderId": "order_abc123",
  "amount": 10.50,
  "currency": "KWD",
  "timestamp": "2023-10-27T10:30:00Z"
}
```

### Response
#### Success Response (2xx)
Your webhook endpoint should typically return a 2xx status code (e.g., 200 OK) to acknowledge receipt of the webhook. Failure to do so may result in retries by the UPayments system.

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Webhook received successfully"
}
```
```

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

### Create Customer Unique Token (Sandbox)

Source: https://developers.upayments.com/reference/upgrade-from-v1-to-v2

This endpoint is used to create a unique token for a customer in the UInterface V2 Sandbox Testing Environment, typically for saving card details.

```APIDOC
## POST /api/v1/create-customer-unique-token

### Description
Creates a unique token for a customer in the UInterface V2 Sandbox Testing Environment for saving card details.

### Method
POST

### Endpoint
https://sandboxapi.upayments.com/api/v1/create-customer-unique-token

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **customer_id** (string) - Required - The unique identifier for the customer.

### Request Example
```json
{
  "customer_id": "cust_123"
}
```

### Response
#### Success Response (200)
- **token** (string) - The unique token generated for the customer.

#### Response Example
```json
{
  "token": "tok_xyz789"
}
```
```

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

### GET /api/v1/get-payment-status/{track_id}

Source: https://developers.upayments.com/reference/checkpaymentstatus

Retrieve payment status using the unique transaction tracking ID.

```APIDOC
## GET /api/v1/get-payment-status/{track_id}

### Description
Retrieves the status of a payment using a `track_id`, which is a unique identifier for each transaction attempt. This `track_id` can be obtained from redirect URLs or the Notification Webhook.

### Method
GET

### Endpoint
/api/v1/get-payment-status/`{track_id}`

### Parameters
#### Path Parameters
- **track_id** (string) - Required - The unique transaction tracking identifier.

### Request Example
```json
{
  "example": "https://sandbox.upayments.com/api/v1/get-payment-status/019ae3cc7da914644b7efd5638cdc83fv2"
}
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the payment (e.g., 'SUCCESS', 'FAILED', 'PENDING').
- **transaction_id** (string) - The internal transaction identifier.
- **amount** (number) - The transaction amount.
- **currency** (string) - The transaction currency.

#### Response Example
```json
{
  "example": {
    "status": "SUCCESS",
    "transaction_id": "txn_12345abcde",
    "amount": 100.50,
    "currency": "USD"
  }
}
```
```

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

### Get Payment Status by Invoice ID

Source: https://developers.upayments.com/reference/check-status

Retrieve the status and details of a transaction using its encrypted_invoice_id.

```APIDOC
## GET /api/v1/get-payment-status?invoice_id={encrypted_invoice_id}

### Description
This API is designed to retrieve the status and details of a previously initiated transaction using the `encrypted_invoice_id`. This method is specifically used for transactions initiated via the `create-invoice` `Charge `API.

### Method
GET

### Endpoint
https://sandboxapi.upayments.com/api/v1/get-payment-status?invoice_id={encrypted_invoice_id}

### Parameters
#### Path Parameters
None

#### Query Parameters
- **invoice_id** (string) - Required - The encrypted invoice ID returned in the response of the `create-invoice` API.

#### Request Body
None

### Request Example
```json
{
  "example": "GET /api/v1/get-payment-status?invoice_id=R9kA7oMzL4"
}
```

### Response
#### Success Response (201)
- **status** (boolean) - Indicates the success of the operation.
- **message** (string) - A message describing the result of the operation.
- **data** (object) - Contains transaction details.
  - **transaction** (object) - Detailed transaction object.

#### Response Example
```json
{
  "example": "{\n  "status": true,\n  "message": "Transaction details retrieved successfully.",\n  "data": {\n    "transaction": {\n      // ... transaction object details ...\n    }\n  }\n}"
}
```
```

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

### Make Charge

Source: https://developers.upayments.com/reference/addcharge

Creates a payment charge and returns a payment link.

```APIDOC
## POST /websites/developers_upayments/make_charge

### Description
This endpoint creates a payment charge and returns a payment link for the user to complete the transaction.

### Method
POST

### Endpoint
/websites/developers_upayments/make_charge

### Parameters
#### Request Body
- **amount** (integer) - Required - The amount to be charged.
- **currency** (string) - Required - The currency of the charge (e.g., "USD", "EUR").
- **description** (string) - Optional - A description for the charge.

### Request Example
```json
{
  "amount": 1000,
  "currency": "USD",
  "description": "Payment for service"
}
```

### Response
#### Success Response (201)
- **payment_link** (string) - The URL for the payment.
- **charge_id** (string) - The unique identifier for the charge.

#### Response Example
```json
{
  "payment_link": "https://pay.upayments.com/abcdef12345",
  "charge_id": "ch_12345abcde"
}
```

#### Error Response (400)
- **error** (string) - Description of the error.

#### Error Response Example
```json
{
  "error": "Invalid currency provided."
}
```
```

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

### Get Payment Status by Session ID

Source: https://developers.upayments.com/reference/check-status

Retrieve the status and details of a transaction using its session_id.

```APIDOC
## GET /api/v1/get-payment-status?session_id={session_id}

### Description
This API is designed to retrieve the status and details of a previously initiated transaction using the `session_id`.

### Method
GET

### Endpoint
https://sandboxapi.upayments.com/api/v1/get-payment-status?session_id={session_id}

### Parameters
#### Path Parameters
None

#### Query Parameters
- **session_id** (string) - Required - A system-generated identifier for the transaction session.

#### Request Body
None

### Request Example
```json
{
  "example": "GET /api/v1/get-payment-status?session_id=2025133235031228373483523989923251714885916179872"
}
```

### Response
#### Success Response (201)
- **status** (boolean) - Indicates the success of the operation.
- **message** (string) - A message describing the result of the operation.
- **data** (object) - Contains transaction details.
  - **transaction** (object) - Detailed transaction object.

#### Response Example
```json
{
  "example": "{\n  "status": true,\n  "message": "Transaction details retrieved successfully.",\n  "data": {\n    "transaction": {\n      // ... transaction object details ...\n    }\n  }\n}"
}
```
```

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

### Add Card (Sandbox)

Source: https://developers.upayments.com/reference/upgrade-from-v1-to-v2

This endpoint allows you to add a card for a customer in the UInterface V2 Sandbox Testing Environment.

```APIDOC
## POST /api/v1/add-card

### Description
Adds a card for a customer in the UInterface V2 Sandbox Testing Environment.

### Method
POST

### Endpoint
https://sandboxapi.upayments.com/api/v1/add-card

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **customer_token** (string) - Required - The token of the customer.
- **card_number** (string) - Required - The card number.
- **expiry_month** (string) - Required - The expiry month of the card (MM).
- **expiry_year** (string) - Required - The expiry year of the card (YYYY).
- **cvv** (string) - Required - The CVV of the card.

### Request Example
```json
{
  "customer_token": "tok_xyz789",
  "card_number": "4111111111111111",
  "expiry_month": "12",
  "expiry_year": "2025",
  "cvv": "123"
}
```

### Response
#### Success Response (200)
- **card_token** (string) - The token representing the added card.

#### Response Example
```json
{
  "card_token": "card_abc456"
}
```
```

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

### Get Sales Report - cURL

Source: https://developers.upayments.com/reference/reports

This snippet demonstrates how to make a GET request to the UPayments Sales Report API using cURL. It includes the endpoint URL with query parameters for date filtering (fromDate, toDate), keyword search, and pagination (page, perPage), along with the necessary Authorization and Accept headers.

```shell
curl --request GET \
     --url 'https://sandboxapi.upayments.com/api/v1/reports/sales?fromDate=2024-08-31&toDate=2025-08-31&keyword=test&page=1&perPage=10' \
     --header 'Authorization: Bearer jtest123' \
     --header 'accept: application/json'
```