### Payment Request Example

Source: https://api-docs.solidgate.com/

Example of a JSON payload for initiating a payment.

```APIDOC
## POST /payments

### Description
Initiates a payment transaction with the provided details.

### Method
POST

### Endpoint
/payments

### Request Body
- **payment_method** (string) - Required - The payment method to use (e.g., "paypal-vault").
- **order_id** (string) - Required - Unique identifier for the order.
- **amount** (integer) - Required - The transaction amount.
- **currency** (string) - Required - The currency of the transaction (e.g., "USD").
- **order_description** (string) - Optional - Description of the order.
- **order_date** (string) - Optional - The date and time the order was placed (YYYY-MM-DD HH:MM:SS).
- **customer_account_id** (string) - Optional - Unique identifier for the customer account.
- **customer_email** (string) - Optional - Customer's email address.
- **customer_first_name** (string) - Optional - Customer's first name.
- **customer_last_name** (string) - Optional - Customer's last name.
- **customer_date_of_birth** (string) - Optional - Customer's date of birth (YYYY-MM-DD).
- **customer_phone** (string) - Optional - Customer's phone number.
- **item_category** (string) - Optional - Category of the items being purchased.
- **billing_address** (object) - Optional - Billing address details.
  - **country** (string) - Required - Country.
  - **state** (string) - Required - State/Province.
  - **city** (string) - Required - City.
  - **zip** (string) - Required - Postal code.
  - **line1** (string) - Required - Street address line 1.
  - **line2** (string) - Optional - Street address line 2.
- **shipping_address** (object) - Optional - Shipping address details.
  - **country** (string) - Required - Country.
  - **state** (string) - Required - State/Province.
  - **city** (string) - Required - City.
  - **zip** (string) - Required - Postal code.
  - **line1** (string) - Required - Street address line 1.
  - **line2** (string) - Optional - Street address line 2.
- **language** (string) - Optional - Language code for the transaction.
- **ip_address** (string) - Optional - Customer's IP address.
- **platform** (string) - Optional - The platform used for the transaction (e.g., "WEB").
- **user_agent** (string) - Optional - User agent string.
- **order_metadata** (object) - Optional - Additional metadata for the order.
  - **coupon_code** (string) - Optional - Coupon code applied.
  - **partner_id** (string) - Optional - Partner identifier.
- **success_url** (string) - Optional - URL to redirect to upon success.
- **fail_url** (string) - Optional - URL to redirect to upon failure.
- **return_url** (string) - Optional - URL to return to after the transaction.

### Request Example
```json
{
  "payment_method": "paypal-vault",
  "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
  "amount": 1020,
  "currency": "USD",
  "order_description": "Premium package",
  "order_date": "2025-12-21 11:21:30",
  "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
  "customer_email": "example@example.com",
  "customer_first_name": "Nikola",
  "customer_last_name": "Tesla",
  "customer_date_of_birth": "1988-11-21",
  "customer_phone": "+15551234567",
  "item_category": "digital_goods",
  "billing_address": {
    "country": "USA",
    "state": "WA",
    "city": "New York",
    "zip": "10005",
    "line1": "123 Main St.",
    "line2": "Apt. 123"
  },
  "shipping_address": {
    "country": "USA",
    "state": "NY",
    "city": "Boston",
    "zip": "91191",
    "line1": "777 Main St.",
    "line2": "Apt. 321"
  },
  "language": "en",
  "ip_address": "203.0.113.0",
  "platform": "WEB",
  "user_agent": "Mozilla/5.0",
  "order_metadata": {
    "coupon_code": "NY2025",
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail",
  "return_url": "https://merchant.example/success"
}
```

### Response
#### Success Response (200)
- **order** (object) - Details of the processed order.
  - **method** (string) - The payment method used.
  - **order_id** (string) - The unique identifier for the order.
  - **created_at** (string) - Timestamp when the order was created.
  - **updated_at** (string) - Timestamp when the order was last updated.
  - **amount** (integer) - The transaction amount.
  - **currency** (string) - The currency of the transaction.
  - **order_description** (string) - Description of the order.
  - **status** (string) - The current status of the order (e.g., "processing").
  - **customer_account_id** (string) - Unique identifier for the customer account.
  - **customer_email** (string) - Customer's email address.
  - **ip_address** (string) - Customer's IP address.
- **transactions** (array) - List of transactions associated with the order.
  - **method** (string) - The payment method used for the transaction.
  - **id** (string) - Unique identifier for the transaction.
  - **created_at** (string) - Timestamp when the transaction was created.
  - **amount** (integer) - The transaction amount.
  - **currency** (string) - The currency of the transaction.
  - **status** (string) - The status of the transaction (e.g., "processing", "success").
  - **type** (string) - The type of transaction (e.g., "pay", "refund").
- **pay_form** (object) - Information related to the payment form.
  - **script_url** (string) - URL for the payment form script.
- **order_metadata** (object) - Additional metadata for the order.
  - **coupon_code** (string) - Coupon code applied.
  - **partner_id** (string) - Partner identifier.

#### Response Example
```json
{
  "order": {
    "method": "paypal-vault",
    "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
    "created_at": "2025-12-27 11:45:30",
    "updated_at": "2025-12-28 11:45:30",
    "amount": 1020,
    "currency": "USD",
    "order_description": "Premium package",
    "status": "processing",
    "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
    "customer_email": "example@example.com",
    "ip_address": "203.0.113.0"
  },
  "transactions": [
    {
      "method": "paypal-vault",
      "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
      "created_at": "2025-12-27 11:45:30",
      "amount": 100,
      "currency": "USD",
      "status": "processing",
      "type": "pay"
    },
    {
      "method": "paypal-vault",
      "id": "another_unique_id",
      "created_at": "2025-12-28 12:00:00",
      "amount": 50,
      "currency": "USD",
      "status": "success",
      "type": "refund"
    }
  ],
  "pay_form": {
    "script_url": "https://payment-provider.example/widget/example.js"
  },
  "order_metadata": {
    "coupon_code": "NY2025",
    "partner_id": "123989"
  }
}
```
```

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

### Get Products Response Example

Source: https://api-docs.solidgate.com/

This JSON structure represents a successful response when retrieving product data. It includes an array of product objects and pagination details.

```json
{
  "data": [
    {
      "id": "cb43b415-5522-4373-b026-a365462f9114",
      "name": "Luxury product",
      "type": "one-time",
      "description": "This product is the best product all over the world",
      "public_description": "That cool product that you have bought",
      "status": "active",
      "created_at": "2025-05-31 12:53:12",
      "updated_at": "2025-05-31 12:53:13",
      "payment_action": "auth_settle",
      "settle_interval": 48,
      "tax": {
        "category_id": "taxc_01JJVD231C879QBHVTVCWJ1K2A",
        "behavior": "included"
      }
    }
  ],
  "pagination": {
    "offset": 20,
    "limit": 10,
    "total_count": 150
  }
}
```

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

### Authentication Failed Error Example

Source: https://api-docs.solidgate.com/

This example demonstrates the response structure when authentication fails.

```APIDOC
## Error Response (401)

### Description
This response indicates that the authentication failed, likely due to invalid credentials or an expired token.

### Response Example
```json
{
  "error": {
    "code": "2.01",
    "messages": [
      "Authentication failed"
    ]
  }
}
```
```

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

### Subscription Details Response Example

Source: https://api-docs.solidgate.com/

This is an example of a successful response when retrieving subscription details. It includes status, dates, payment information, and customer details.

```json
{
  "<subscription_id_value_#1>": {
    "id": "64e1c283-17bf-45a7-90ea-2cb938081b2f",
    "status": "cancelled",
    "started_at": "2025-06-10 15:42:24",
    "updated_at": "2025-06-10 15:42:25",
    "expired_at": "2025-09-10 16:42:24",
    "next_charge_at": "2025-11-26 11:43:52",
    "payment_type": "paypal-vault",
    "trial": true,
    "cancelled_at": "2025-06-26 06:43:58",
    "cancellation_requested_at": "2025-06-25 06:43:58",
    "cancel_code": "8.01",
    "cancel_message": "Card brand is not supported",
    "customer": {
      "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
      "customer_email": "example@example.com"
},
    "pause": {
      "from_date": "2025-03-27 11:26:08",
      "to_date": "2025-03-27 11:26:08"
}
},
  "<subscription_id_value_#2>": {
    "id": "64e1c283-17bf-45a7-90ea-2cb938081b2f",
    "status": "cancelled",
    "started_at": "2025-06-10 15:42:24",
    "updated_at": "2025-06-10 15:42:25",
    "expired_at": "2025-09-10 16:42:24",
    "next_charge_at": "2025-11-26 11:43:52",
    "payment_type": "paypal-vault",
    "trial": true,
    "cancelled_at": "2025-06-26 06:43:58",
    "cancellation_requested_at": "2025-06-25 06:43:58",
    "cancel_code": "8.01",
    "cancel_message": "Card brand is not supported",
    "customer": {
      "customer_account_id": "93a1c659-288d-4d62-929d-10e241078faa",
      "customer_email": "example@example.com"
},
    "pause": {
      "from_date": "2025-03-27 11:26:08",
      "to_date": "2025-03-27 11:26:08"
}
}

}
```

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

### Order Not Found Error Example

Source: https://api-docs.solidgate.com/

This example illustrates the response when a requested order cannot be found.

```APIDOC
## Error Response (404)

### Description
This response indicates that the specified order could not be found.

### Response Example
```json
{
  "error": {
    "code": "2.01",
    "messages": [
      "Order not found"
    ]
  }
}
```
```

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

### Error Response Example

Source: https://api-docs.solidgate.com/

This example demonstrates an API response indicating an authentication failure.

```APIDOC
## Error Response Example

### Description
This sample shows an API response when authentication fails or an order is not found.

### Response Example
```json
{
  "error": {
    "code": "2.01",
    "messages": [
      "Invalid data"
    ],
    "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
    "merchant_advice_code": "30"
  }
}
```

Or:

```json
{
  "error": {
    "code": "2.01",
    "messages": [
      "Order not found"
    ]
  }
}
```
```

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

### Success Response Example

Source: https://api-docs.solidgate.com/

This example shows a successful API response containing order and transaction details.

```APIDOC
## Success Response (200)

### Description
This response indicates a successful operation, providing detailed information about the order and the associated transaction.

### Response Example
```json
{
  "order": {
    "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
    "order_description": "Premium package",
    "psp_order_id": "854756336423874823bdfsg6743gf5",
    "provider_payment_id": "charge_64789DFS3827563HGF56",
    "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
    "product_id": "a51ba9fd-3be1-4ef9-b00f-bb85157597f5",
    "product_name": "Luxury product",
    "amount": 100,
    "currency": "USD",
    "processing_amount": 0,
    "processing_currency": "USD",
    "marketing_amount": 0,
    "marketing_currency": "USD",
    "refunded_amount": 0,
    "status": "settle_ok",
    "auth_code": "2w9m8",
    "payment_type": "1-click",
    "payment_method": "card",
    "customer_account_id": "93a1c659-288d-4d72-929d-10e241078faa",
    "customer_email": "example@example.com",
    "descriptor": "google.com",
    "mid": "bank-mid-1",
    "ip_address": "203.0.113.0",
    "traffic_source": "facebook"
  },
  "transaction": {
    "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
    "created_at": "2025-12-27 11:45:30",
    "updated_at": "2025-12-28 11:45:30",
    "amount": 100,
    "currency": "USD",
    "marketing_amount": 0,
    "marketing_currency": "USD",
    "operation": "recurring-auth",
    "status": "processing",
    "scheme_transaction_id": "MDSCAJVIJ1201",
    "transaction_link_id": "A1bCDefGhijkLmNopQrStu",
    "descriptor": "google.com",
    "billing_details": {
      "address": "21 Bedford Ave",
      "country": "USA",
      "city": "Boston",
      "state": "NY",
      "zip": "91191"
    },
    "refund_reason": "Solidgate - Issuer Fraud Notification",
    "refund_reason_code": "0022",
    "card_token": {
      "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
      "original_payment_method": "apple-pay"
    },
    "card": {
      "bank": "JSC UNIVERSAL BANK",
      "bin": "444111",
      "brand": "VISA",
      "card_exp_month": "12",
      "card_exp_year": 2028,
      "card_holder": "John Snow",
      "card_type": "CREDIT",
      "is_reloadable": true,
      "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
      "country": "USA",
      "number": "444111XXXXXX9435",
      "card_token": {
        "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
        "original_payment_method": "apple-pay"
      }
    },
    "error": {
      "code": "2.01",
      "messages": [
        "Invalid data"
      ],
      "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side",
      "merchant_advice_code": "30"
    },
    "payment_account_reference": "PAR_1A2B3C4D5E6F7G8H9",
    "arn_code": "24871153022084127852235",
    "rrn_code": "100034876543"
  },
  "transactions": {
    "<transaction_id_value_#1>": {
      "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
      "created_at": "2025-12-27 11:45:30",
      "updated_at": "2025-12-28 11:45:30",
      "amount": 100,
      "currency": "USD",
      "marketing_amount": 0,
      "marketing_currency": "USD",
      "operation": "recurring-auth",
      "status": "processing",
      "scheme_transaction_id": "MDSCAJVIJ1201",
      "transaction_link_id": "A1bCDefGhijkLmNopQrStu",
      "descriptor": "google.com",
      "billing_details": {
        "address": "21 Bedford Ave",
        "city": "Boston",
        "country": "USA",
        "state": "NY",
        "zip": "91191"
      },
      "refund_reason": "Solidgate - Issuer Fraud Notification",
      "refund_reason_code": "0022",
      "card_token": {
        "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
        "original_payment_method": "apple-pay"
      },
      "card": {
        "bank": "JSC UNIVERSAL BANK",
        "bin": "444111",
        "brand": "VISA",
        "card_exp_month": "12",
        "card_exp_year": 2028,
        "card_holder": "John Snow",
        "card_type": "CREDIT",
        "is_reloadable": true,
        "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
        "country": "USA",
        "number": "444111XXXXXX9435",
        "card_token": {
          "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
          "original_payment_method": "apple-pay"
        }
      },
      "error": {
        "code": "2.01",
        "messages": [
          "Invalid data"
        ],
        "recommended_message_for_user": "The problem here lies with the data format and accuracy, validation error on the acquiring side"
      }
    }
  }
}
```
```

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

### Subscription Update Response Example

Source: https://api-docs.solidgate.com/

This is an example of a successful response when a subscription is updated. It includes various fields detailing the subscription's status, timestamps, and associated data.

```json
{
  "id": "9e252e9f-c5a3-4dca-93df-4c9fcf54267e",
  "status": "pending",
  "started_at": "2025-12-08 12:37:24",
  "updated_at": "2025-12-08 12:37:25",
  "expired_at": "2025-12-12 12:37:24",
  "payment_type": "card",
  "discount": {
    "created_at": "2025-05-31 12:53:12",
    "coupon_code": "SUMMER25OFF",
    "coupon": {
      "name": "Summer 25% OFF",
      "description": "25% off for 3 months",
      "type": "percentage",
      "value": 25
}
},
  "trial": false,
  "trial_started_at": "2025-12-08 12:37:24",
  "trial_ended_at": "2025-12-08 12:37:25",
  "cancelled_at": "2025-12-12 19:37:24",
  "cancellation_requested_at": "2025-12-11 19:37:24",
  "cancel_code": "8.09",
  "cancel_message": "Cancellation after redemption period",
  "pause": {
    "from_date": "2025-12-27 11:26:08",
    "to_date": "2025-12-27 11:26:08"
}
}
```

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

### Authentication Failed Response Example

Source: https://api-docs.solidgate.com/

This example demonstrates an API response when authentication fails, including an error code and a recommended message for the user.

```APIDOC
## Error Response (e.g., 401 Unauthorized)

### Description
This is a sample response indicating an authentication failure. It includes an error code and a user-friendly message.

### Response Example
```json
{
  "error": {
    "code": "2.01",
    "messages": [
      "Authentication failed"
    ],
    "recommended_message_for_user": "Please check your credentials and try again."
  }
}
```
```

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

### Order Not Found Response Example

Source: https://api-docs.solidgate.com/

This example shows an API response when a requested order cannot be found.

```APIDOC
## Order Not Found Response (e.g., 404 Not Found)

### Description
This response is returned when the specified order ID does not exist in the system.

### Response Example
```json
{
  "error": {
    "code": "X.XX",
    "messages": [
      "Order not found"
    ],
    "recommended_message_for_user": "The order you are looking for could not be found. Please verify the order ID."
  }
}
```
```

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

### Request Payload Example

Source: https://api-docs.solidgate.com/

This is an example of a request payload for the Solidgate API, demonstrating the structure for order, error, and transaction details.

```APIDOC
## Request Payload Example

### Description
This is an example of a request payload for the Solidgate API, demonstrating the structure for order, error, and transaction details.

### Content Type
application/json

### Request Body Example
```json
{
  "order": {
    "order_id": "923bb4e6-4a5f-41ec-81fb-28eb8a152e55",
    "order_description": "Premium package",
    "psp_order_id": "854756336423874823bdfsg6743gf5",
    "provider_payment_id": "charge_64789DFS3827563HGF56",
    "product_id": "a51ba9fd-3be1-4ef9-b00f-bb85157597f5",
    "product_name": "Luxury product",
    "subscription_id": "83b19018-cbc4-4df0-899a-dda84fd2705e",
    "amount": 100,
    "currency": "USD",
    "processing_amount": 0,
    "processing_currency": "USD",
    "marketing_amount": 0,
    "marketing_currency": "USD",
    "refunded_amount": 0,
    "authorized_amount": 100,
    "status": "auth_ok",
    "auth_code": "2w9m8",
    "payment_type": "1-click",
    "payment_method": "card",
    "customer_account_id": "93a1c659-288d-4d72-929d-10e241078faa",
    "customer_email": "example@example.com",
    "descriptor": "google.com",
    "mid": "bank-mid-1",
    "ip_address": "8.8.8.8",
    "traffic_source": "facebook"
  },
  "error": {
    "code": "3.08",
    "messages": [
      "Do not honor"
    ],
    "recommended_message_for_user": "Advise the customer to contact their card issuer to resolve potential restrictions like blocked cards, insufficient limits, or currency issues before retrying the transaction"
  },
  "transaction": {
    "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
    "created_at": "2025-12-27 11:45:30",
    "updated_at": "2025-12-28 11:45:30",
    "amount": 100,
    "currency": "USD",
    "marketing_amount": 0,
    "marketing_currency": "USD",
    "operation": "auth",
    "status": "processing",
    "authorization_type": "final",
    "scheme_transaction_id": "MDSCAJVIJ1201",
    "transaction_link_id": "A1bCDefGhijkLmNopQrStu",
    "descriptor": "google.com",
    "billing_details": {
      "address": "21 Bedford Ave",
      "country": "USA",
      "city": "Boston",
      "state": "NY",
      "zip": "91191"
    },
    "refund_reason": "Solidgate - Issuer Fraud Notification",
    "refund_reason_code": "0022",
    "card_token": {
      "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
      "original_payment_method": "apple-pay"
    },
    "card": {
      "bank": "JSC UNIVERSAL BANK",
      "bin": "444111",
      "brand": "VISA",
      "card_exp_month": "12",
      "card_exp_year": 2028,
      "card_holder": "John Snow",
      "card_type": "CREDIT",
      "is_reloadable": true,
      "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
      "country": "USA",
      "number": "444111XXXXXX9435",
      "card_token": {
        "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
        "original_payment_method": "apple-pay"
      }
    },
    "error": {
      "code": "3.08",
      "messages": [
        "Do not honor"
      ],
      "recommended_message_for_user": "Advise the customer to contact their card issuer to resolve potential restrictions like blocked cards, insufficient limits, or currency issues before retrying the transaction"
    },
    "payment_account_reference": "PAR_1A2B3C4D5E6F7G8H9",
    "arn_code": "24871153022084127852235",
    "rrn_code": "100034876543"
  },
  "transactions": {
    "<transaction_id_value_#1>": {
      "id": "5019d00bb70f82cd42f6bc654cbdfcbd63a9b5b1dbd6a",
      "created_at": "2025-12-27 11:45:30",
      "updated_at": "2025-12-28 11:45:30",
      "amount": 100,
      "currency": "USD",
      "marketing_amount": 0,
      "marketing_currency": "USD",
      "operation": "auth",
      "status": "processing",
      "authorization_type": "final",
      "scheme_transaction_id": "MDSCAJVIJ1201",
      "transaction_link_id": "A1bCDefGhijkLmNopQrStu",
      "descriptor": "google.com",
      "billing_details": {
        "address": "21 Bedford Ave",
        "city": "Boston",
        "country": "USA",
        "state": "NY",
        "zip": "91191"
      },
      "refund_reason": "Solidgate - Issuer Fraud Notification",
      "refund_reason_code": "0022",
      "card_token": {
        "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
        "original_payment_method": "apple-pay"
      },
      "card": {
        "bank": "JSC UNIVERSAL BANK",
        "bin": "444111",
        "brand": "VISA",
        "card_exp_month": "12",
        "card_exp_year": 2028,
        "card_holder": "John Snow",
        "card_type": "CREDIT",
        "is_reloadable": true,
        "card_id": "22733af4-f6c6-4368-b7d0-98aeb0253a57",
        "country": "USA",
        "number": "444111XXXXXX9435",
        "card_token": {
          "token": "baf2ff5c5a125aeabb4b80d7b983f66f3abf5dbb8d939df48b40755674eddceee78084eab5fa9c15a339c94f1ad2b30cf299",
          "original_payment_method": "apple-pay"
        }
      }
    }
  }
}
```
```