> ## 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.

# Initiating a Payment

> How to create and share a payment link via the PCX API

## Endpoint

```
POST https://prod-api.pcxpay.com/v1/payments-init/initiate
```

Both auth headers are always required. Set whichever you are not using to the literal string `NONE`.

| Header          | Value                      |
| --------------- | -------------------------- |
| `X-Api-Key`     | Your API key               |
| `Authorization` | `NONE` (for API key flows) |

***

## Request

The `pay_by_link: true` flag in the `metadata` object is required for H2H. Without it the request defaults to iFrame integration.

```json theme={null}
{
  "amount": 100.00,
  "target_amount": 100.00,
  "target_currency": "GBP",
  "currency": "GBP",
  "country": "GB",
  "payment_method": "bank_transfer",
  "org_id": "your-org-id",
  "payer_details": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "metadata": {
    "beneficiary_name": "Recipient Name",
    "user_id": "user-uuid",
    "transaction_type": "bank",
    "reason": "Payment for services",
    "pay_by_link": true
  }
}
```

***

## Response

```json theme={null}
{
  "success": true,
  "status": "initiated",
  "next_action": "pay_by_link",
  "payment_link": "https://pay.pcxpay.com/pay/abc123xyz...",
  "payment_intent_id": "pi_xyz789",
  "expiry_time": "2024-01-15T12:00:00Z",
  "provider_payment_id": "pay_abc123",
  "message": "Payment link created. Share link with customer to complete payment."
}
```

### Response fields

| Field                 | Type    | Description                                                         |
| --------------------- | ------- | ------------------------------------------------------------------- |
| `success`             | boolean | Whether the request was successful                                  |
| `status`              | string  | Payment status — always `initiated` on creation                     |
| `next_action`         | string  | Always `pay_by_link` for H2H integration                            |
| `payment_link`        | string  | Direct payment link to share with the customer                      |
| `payment_intent_id`   | string  | Unique identifier for this payment intent — store this for tracking |
| `expiry_time`         | string  | ISO 8601 timestamp when the link expires (typically 24 hours)       |
| `provider_payment_id` | string  | PCX payment identifier                                              |
| `message`             | string  | Human-readable status message                                       |

***

## Sharing the link

Once you receive `payment_link`, deliver it to the customer via SMS, email, in-app message, or push notification.

* **Expiry** — the link expires after 24 hours. Check `expiry_time` in the response. If it expires, create a new payment request.
* **Tracking** — store `payment_intent_id` against the order in your system for status tracking.
* **Confirmation** — do not rely on the customer returning to your app to confirm payment. Always use webhooks for confirmation. See [Payment Status & Webhooks](/guides/h2h/payment-status).
* **Expired links** — if the customer tries to pay after expiry, surface a clear message and allow them to request a new link.