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

# Browser callback after hosted checkout

> Browser redirect endpoint that payment providers send the customer to after hosted checkout finishes. You do not call this endpoint yourself — PCX registers it with the provider during redirect checkout flows (`next_action: redirect`). It requires no authentication.

PCX looks up the payment from the query parameters, then issues a `302` redirect to the `return_url` you supplied at initiation, appending `status` and `reference` query parameters. `status` is `completed` or `failed` where the provider outcome maps to a final state; otherwise the raw provider status is passed through. `reference` is your `client_reference` from initiation, or the first 10 characters of the payment ID when no `client_reference` was supplied.

If no `return_url` was stored for the payment, or the stored URL is invalid, the customer is redirected to the PCX remittances page instead.




## OpenAPI

````yaml /api-reference/external/openapi.yaml get /payments-init/callback
openapi: 3.0.3
info:
  title: PCX API
  description: >
    The PCX integration API. Every request requires two headers: `Authorization`
    (Bearer JWT for user-facing flows, or the literal string `NONE`) and
    `X-Api-Key` (your API key for server-to-server calls, or the literal string
    `NONE`). Pass `NONE` for whichever header you are not using.
  version: '1.0'
servers:
  - url: https://prod-api.pcxpay.com/v1
    description: Production
  - url: https://devs.pcxpay.com/v1
    description: Development
security: []
tags:
  - name: Payment Initiation
    description: Initiate payments and poll for status
  - name: API Keys
    description: Create and manage API keys for programmatic access
  - name: Webhooks
    description: Register endpoints and receive transaction notifications
  - name: Beneficiaries
    description: Manage payment recipients
  - name: Payments
    description: Initiate and track payments
  - name: Bank Validation
    description: Validate bank accounts before initiating a payment
  - name: Transactions
    description: Query the financial transaction ledger
  - name: Virtual Accounts
    description: Multi-currency virtual account provisioning and fund operations
  - name: Payment Links
    description: Generate shareable payment links for customer checkout
  - name: Escrow
    description: Milestone-based escrow projects, parties, contracts, and funding
paths:
  /payments-init/callback:
    get:
      tags:
        - Payment Initiation
      summary: Browser callback after hosted checkout
      description: >
        Browser redirect endpoint that payment providers send the customer to
        after hosted checkout finishes. You do not call this endpoint yourself —
        PCX registers it with the provider during redirect checkout flows
        (`next_action: redirect`). It requires no authentication.


        PCX looks up the payment from the query parameters, then issues a `302`
        redirect to the `return_url` you supplied at initiation, appending
        `status` and `reference` query parameters. `status` is `completed` or
        `failed` where the provider outcome maps to a final state; otherwise the
        raw provider status is passed through. `reference` is your
        `client_reference` from initiation, or the first 10 characters of the
        payment ID when no `client_reference` was supplied.


        If no `return_url` was stored for the payment, or the stored URL is
        invalid, the customer is redirected to the PCX remittances page instead.
      operationId: paymentBrowserCallback
      parameters:
        - name: payment_id
          in: query
          required: false
          schema:
            type: string
          description: >
            PCX payment ID used to look up the payment. The aliases
            `merchantPaymentId` and `merchant_payment_id` are also accepted.
        - name: provider_payment_id
          in: query
          required: false
          schema:
            type: string
          description: >
            Provider-side payment ID, used as a fallback lookup when no PCX
            payment ID is present. The aliases `transactionId` and `paymentId`
            are also accepted.
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: >
            Provider-reported payment status. The alias `paymentStatus` is also
            accepted. `success`, `successful`, `settled`, and `completed` map to
            `completed`; `failed` maps to `failed`.
      responses:
        '302':
          description: >
            Redirect to the stored `return_url` with `status` and `reference`
            query parameters appended, or to the PCX remittances page when no
            valid `return_url` is stored.
          headers:
            Location:
              schema:
                type: string
                format: uri
                example: >-
                  https://your-app.com/transaction-success?status=completed&reference=ORDER-123
        '404':
          description: No payment matched the supplied identifiers
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Payment not found

````