> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payviox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Payment Details

> Retrieve detailed information about a specific payment

## Overview

Returns comprehensive details about a payment, including the amount, fees, customer information, payment method, and transaction status. Use this endpoint for reconciliation, to verify payment status on-demand, or to retrieve data you may have missed from a webhook.

<Note>
  All monetary amounts are returned in **cents** (e.g., `10000` = \$100.00).
</Note>

## Authentication

This endpoint requires your **Secret API Key** (server-side only). See [Authentication](/api/authentication) for details.

```bash theme={null}
Authorization: Bearer sk_live_xxxxxxxxxxxx
```

<Warning>
  Never expose your Secret API Key in client-side code. This endpoint should only be called from your backend server.
</Warning>

## Path Parameters

<ParamField path="session_id" type="string" required>
  The session ID returned when you created the payment session.
</ParamField>

## Response Fields

<ResponseField name="session_id" type="string" required>
  Unique identifier for the payment session.
</ResponseField>

<ResponseField name="status" type="string">
  Current payment status: `succeeded`, `failed`, `pending`, `processing`, `pending_review`, `declined`, `expired`, or `null` if no payment attempt was made.
</ResponseField>

<ResponseField name="amount" type="integer" required>
  Gross amount in cents (what the customer pays).
</ResponseField>

<ResponseField name="fees" type="integer">
  Total fees in cents (Payviox + provider + addons). `null` if the payment has not been completed yet.
</ResponseField>

<ResponseField name="net_amount" type="integer">
  Net amount in cents (`amount - fees`). This is what your business receives. `null` if the payment has not been completed yet.
</ResponseField>

<ResponseField name="currency" type="string" required>
  Three-letter ISO currency code (e.g., `USD`).
</ResponseField>

<ResponseField name="order_id" type="string">
  Your unique order identifier, as provided when creating the session.
</ResponseField>

<ResponseField name="customer" type="string">
  Customer identifier, as provided when creating the session.
</ResponseField>

<ResponseField name="description" type="string">
  Payment description, as provided when creating the session.
</ResponseField>

<ResponseField name="items" type="array">
  Array of items from the original session.
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom key-value pairs attached to this session.
</ResponseField>

<ResponseField name="payment_method" type="string">
  Payment method identifier (e.g., `stripe_credit`, `paypal`, `stripe_apple_pay`).
</ResponseField>

<ResponseField name="provider" type="string">
  Payment provider used (e.g., `stripe`, `paypal`, `payssion`).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the session was created.
</ResponseField>

<ResponseField name="customer_details" type="object">
  Customer billing information collected during payment. `null` if the payment has not been completed.

  <Expandable title="Customer details properties">
    <ResponseField name="name" type="string">
      Customer's billing name.
    </ResponseField>

    <ResponseField name="email" type="string">
      Customer's email address.
    </ResponseField>

    <ResponseField name="phone" type="string">
      Customer's phone number.
    </ResponseField>

    <ResponseField name="address" type="object">
      Billing address with `line1`, `line2`, `city`, `state`, `postal_code`, and `country` fields.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_details" type="object">
  Payment method details. `null` if the payment has not been completed.

  <Expandable title="Payment details properties">
    <ResponseField name="type" type="string">
      Payment method type (e.g., `card`, `bancontact`, `ideal`).
    </ResponseField>

    <ResponseField name="card" type="object">
      Card details (only present when `type` is `card`): `brand`, `last4`, `exp_month`, `exp_year`, `country`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ip" type="string">
  End-user's IP address at the time of payment.
</ResponseField>

<ResponseField name="country" type="string">
  Two-letter country code detected from the end-user's IP address (e.g., `FR`, `US`).
</ResponseField>

<ResponseField name="user_agent" type="string">
  End-user's browser User-Agent string at the time of payment.
</ResponseField>

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.payviox.com/payment/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 \
    -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.payviox.com/payment/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6', {
    headers: {
      'Authorization': 'Bearer sk_live_xxxxxxxxxxxx'
    }
  });

  const payment = await response.json();
  console.log(payment.status);       // "succeeded"
  console.log(payment.net_amount);   // 10000
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.payviox.com/payment/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
      headers={
          'Authorization': 'Bearer sk_live_xxxxxxxxxxxx'
      }
  )

  payment = response.json()
  print(payment['status'])       # "succeeded"
  print(payment['net_amount'])   # 10000
  ```

  ```php PHP theme={null}
  <?php

  $apiKey = 'sk_live_xxxxxxxxxxxx';
  $sessionId = 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
  $url = "https://api.payviox.com/payment/{$sessionId}";

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer ' . $apiKey
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $payment = json_decode($response, true);
  echo $payment['status'];       // "succeeded"
  echo $payment['net_amount'];   // 10000
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  session_id = 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
  uri = URI("https://api.payviox.com/payment/#{session_id}")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = 'Bearer sk_live_xxxxxxxxxxxx'

  response = http.request(request)
  payment = JSON.parse(response.body)
  puts payment['status']       # "succeeded"
  puts payment['net_amount']   # 10000
  ```

  ```go Go theme={null}
  package main

  import (
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      sessionID := "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
      url := fmt.Sprintf("https://api.payviox.com/payment/%s", sessionID)

      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Set("Authorization", "Bearer sk_live_xxxxxxxxxxxx")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var payment map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&payment)
      fmt.Println(payment["status"])      // "succeeded"
      fmt.Println(payment["net_amount"])  // 10000
  }
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "status": "succeeded",
    "amount": 10250,
    "fees": 250,
    "net_amount": 10000,
    "currency": "USD",
    "order_id": "order_12345",
    "customer": "customer_abc123",
    "description": "Premium subscription",
    "items": [
      {
        "name": "Premium Plan",
        "quantity": 1,
        "price": 10000
      }
    ],
    "metadata": {
      "user_id": "usr_123",
      "plan": "premium"
    },
    "payment_method": "stripe_credit",
    "provider": "stripe",
    "created_at": "2026-05-04T10:30:00.000000Z",
    "customer_details": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+33612345678",
      "address": {
        "line1": "123 Main St",
        "city": "Paris",
        "postal_code": "75001",
        "country": "FR"
      }
    },
    "payment_details": {
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": "12",
        "exp_year": "2028",
        "country": "FR"
      }
    },
    "ip": "203.0.113.42",
    "country": "FR",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
  }
  ```

  ```json Payment Not Yet Completed (200) theme={null}
  {
    "session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "status": null,
    "amount": 10000,
    "fees": null,
    "net_amount": null,
    "currency": "USD",
    "order_id": "order_12345",
    "customer": "customer_abc123",
    "description": "Premium subscription",
    "items": [
      {
        "name": "Premium Plan",
        "quantity": 1,
        "price": 10000
      }
    ],
    "metadata": {
      "user_id": "usr_123"
    },
    "payment_method": null,
    "provider": null,
    "created_at": "2026-05-04T10:30:00.000000Z",
    "customer_details": null,
    "payment_details": null,
    "ip": null,
    "country": null,
    "user_agent": null
  }
  ```

  ```json Not Found (404) theme={null}
  {
    "error": "Payment not found"
  }
  ```

  ```json Unauthorized (401) theme={null}
  {
    "error": "Unauthorized"
  }
  ```
</ResponseExample>

## Error Responses

<AccordionGroup>
  <Accordion title="401 -- Unauthorized">
    Returned when the API key is missing or invalid. This endpoint requires your **Secret API Key**.

    **How to resolve:** Ensure you are sending a valid Secret API key in the `Authorization: Bearer` header. Public API keys are not accepted for this endpoint.

    ```json theme={null}
    {
      "error": "Unauthorized"
    }
    ```
  </Accordion>

  <Accordion title="404 -- Payment not found">
    Returned when the `session_id` does not exist or does not belong to your business.

    **How to resolve:** Verify the `session_id` is correct. You can only retrieve payments created by your own business.

    ```json theme={null}
    {
      "error": "Payment not found"
    }
    ```
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml GET /payment/{session_id}
openapi: 3.0.3
info:
  title: Payviox API
  description: Payment processing API
  version: 1.0.0
servers:
  - url: https://api.payviox.com
security:
  - bearerAuth: []
paths:
  /payment/{session_id}:
    get:
      tags:
        - Payments
      summary: Get Payment Details
      description: Retrieve detailed information about a specific payment
      operationId: getPaymentDetails
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
          description: The session ID returned when you created the payment session
      responses:
        '200':
          description: Payment details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentDetailsResponse'
        '401':
          description: Unauthorized
        '404':
          description: Payment not found
components:
  schemas:
    GetPaymentDetailsResponse:
      type: object
      properties:
        session_id:
          type: string
          description: Unique identifier for the payment session
        status:
          type: string
          nullable: true
          description: Current payment status
        amount:
          type: integer
          description: Gross amount in cents (what the customer pays)
        fees:
          type: integer
          nullable: true
          description: Total fees in cents (null if payment not completed)
        net_amount:
          type: integer
          nullable: true
          description: Net amount in cents (amount - fees, null if payment not completed)
        currency:
          type: string
          description: Three-letter ISO currency code
        order_id:
          type: string
          description: Your unique order identifier
        customer:
          type: string
          description: Customer identifier
        description:
          type: string
          nullable: true
          description: Payment description
        items:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Array of items from the original session
        metadata:
          type: object
          additionalProperties: true
          description: Custom key-value pairs attached to this session
        payment_method:
          type: string
          nullable: true
          description: Payment method identifier (e.g., stripe_credit, paypal)
        provider:
          type: string
          nullable: true
          description: Payment provider used (e.g., stripe, paypal)
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of session creation
        customer_details:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CustomerDetails'
          description: Customer billing information (null if payment not completed)
        payment_details:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PaymentDetails'
          description: Payment method details (null if payment not completed)
        ip:
          type: string
          nullable: true
          description: End-user's IP address
        country:
          type: string
          nullable: true
          description: Two-letter country code from IP geolocation
        user_agent:
          type: string
          nullable: true
          description: End-user's browser User-Agent string
    CustomerDetails:
      type: object
      properties:
        name:
          type: string
          description: Customer's billing name
        email:
          type: string
          description: Customer's email address
        phone:
          type: string
          description: Customer's phone number
        address:
          type: object
          properties:
            line1:
              type: string
            line2:
              type: string
            city:
              type: string
            state:
              type: string
            postal_code:
              type: string
            country:
              type: string
    PaymentDetails:
      type: object
      properties:
        type:
          type: string
          description: Payment method type (e.g., card, bancontact, ideal)
        card:
          type: object
          description: Card details (only present when type is card)
          properties:
            brand:
              type: string
            last4:
              type: string
            exp_month:
              type: string
            exp_year:
              type: string
            country:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````