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

# Verify Transaction

> Verify a payment transaction and return signed proof

<Info>
  Optional endpoint for merchants to verify payment status. Returns the transaction details and signed proof if the payment is complete.
</Info>

## Use Cases

* Merchant wants to verify a payment they didn't receive a webhook for
* Merchant's webhook handler failed and needs to recover
* Auditing and reconciliation

## Implementation

```javascript theme={null}
app.get('/verify/:txid', async (req, res) => {
  const { txid } = req.params;

  // 1. Find the transaction
  const payment = await db.getPayment(txid);
  if (!payment) {
    return res.status(404).json({
      error: { code: 'TXID_NOT_FOUND', message: 'Transaction not found' }
    });
  }

  // 2. Build response based on status
  if (payment.status === 'pending_settlement') {
    return res.json({
      status: 'pending',
      txid: payment.txid,
      amount: payment.amount,
      currency: payment.currency,
      createdAt: payment.createdAt,
      expiresAt: payment.expiresAt
    });
  }

  if (payment.status === 'completed') {
    // Reconstruct the proof
    const proof = {
      txid: payment.txid,
      issuer: YOUR_OCID,
      from: payment.from,
      to: { ocid: payment.merchantOcid, reference: payment.orderId },
      amount: payment.amount,
      currency: payment.currency,
      timestamp: payment.completedAt,
      memo: payment.memo
    };

    const signature = signProof(proof);

    return res.json({
      status: 'completed',
      proof,
      signature
    });
  }

  // Handle other statuses (failed, expired, etc.)
  res.json({
    status: payment.status,
    txid: payment.txid
  });
});
```

## Response Examples

**Completed payment:**

```json theme={null}
{
  "status": "completed",
  "proof": {
    "txid": "gateway_tx_456",
    "issuer": 300,
    "from": { "ocid": 200, "reference": "wallet_tx_123" },
    "to": { "ocid": 500, "reference": "ord_abc123" },
    "amount": "99.99",
    "currency": "USD",
    "timestamp": 1706500500
  },
  "signature": "a1b2c3..."
}
```

**Pending payment:**

```json theme={null}
{
  "status": "pending",
  "txid": "gateway_tx_456",
  "amount": "99.99",
  "currency": "USD",
  "createdAt": 1706500000,
  "expiresAt": 1706503600
}
```

**Failed/expired:**

```json theme={null}
{
  "status": "expired",
  "txid": "gateway_tx_456"
}
```


## OpenAPI

````yaml merchant-gateway-api/endpoint/merchant-gateway-api/openapi.json get /verify/{txid}
openapi: 3.1.0
info:
  title: Opencharge Merchant Gateway API
  description: >-
    API specification for merchant gateways integrating with the Opencharge
    protocol. Merchant gateways provide hosted checkout pages for online
    merchants and process payments on their behalf.
  version: 0.1.0
  license:
    name: MIT
servers:
  - url: https://pay.gateway.example/opencharge
    description: Example merchant gateway Opencharge endpoint
security: []
paths:
  /verify/{txid}:
    get:
      summary: Verify a transaction
      description: >-
        Optional endpoint for merchants to verify a payment transaction. Returns
        the transaction details and signature proof if it exists.
      operationId: verifyTransaction
      parameters:
        - name: txid
          in: path
          required: true
          description: The transaction ID to verify
          schema:
            type: string
      responses:
        '200':
          description: Transaction verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
              example:
                status: completed
                proof:
                  txid: gateway_tx_456
                  issuer: 300
                  from:
                    ocid: 200
                    reference: wallet_tx_123
                  to:
                    ocid: 500
                    reference: ord_xyz789
                  amount: '99.99'
                  currency: USD
                  timestamp: 1706500500
                  memo: Payment for ord_xyz789
                signature: a1b2c3...
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    VerifyResponse:
      type: object
      required:
        - status
        - proof
        - signature
      properties:
        status:
          type: string
          enum:
            - completed
            - pending
            - failed
        proof:
          $ref: '#/components/schemas/TransactionProof'
        signature:
          type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - INVALID_SIGNATURE
                - TIMESTAMP_EXPIRED
                - NONCE_REUSED
                - UNKNOWN_OCID
                - INVALID_PROOF
                - PROOF_SIGNATURE_INVALID
                - ISSUER_NOT_ACCEPTED
                - ORDER_NOT_FOUND
                - ORDER_EXPIRED
                - TXID_NOT_FOUND
                - MERCHANT_NOT_REGISTERED
                - INSUFFICIENT_FUNDS
                - PAYMENT_NOT_FOUND
                - PAYMENT_EXPIRED
                - ACCOUNT_NOT_FOUND
            message:
              type: string
            details:
              type: object
    TransactionProof:
      type: object
      required:
        - txid
        - issuer
        - from
        - to
        - amount
        - currency
        - timestamp
      properties:
        txid:
          type: string
        issuer:
          type: integer
        from:
          type: object
          required:
            - ocid
          properties:
            ocid:
              type: integer
            reference:
              type: string
        to:
          type: object
          required:
            - ocid
          properties:
            ocid:
              type: integer
            reference:
              type: string
        amount:
          type: string
        currency:
          type: string
        timestamp:
          type: integer
        memo:
          type: string

````