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

# Payment Initiation

> Initiate a payment on your platform and receive the iFrame redirect URL from PCX

Before rendering the iFrame, your platform must initiate a payment with PCX. PCX returns a `redirect_url` containing base64-encoded payment data. Pass this URL to your front end to use as the iFrame `src`.

***

## Why platform-side initiation matters

Payment parameters — amount, currency, payer details — are set on your platform and sent directly to PCX. The returned `redirect_url` carries an encoded reference to the payment record. This means the payer cannot modify the payment amount or currency before the iFrame loads.

***

## Initiate a payment

Call the PCX payment initiation endpoint from your platform:

```bash theme={null}
curl -X POST https://prod-api.pcxpay.com/v1/payments-init/initiate \
  -H "Authorization: NONE" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "GBP",
    "target_amount": 100.00,
    "target_currency": "GBP",
    "country": "GB",
    "payment_method": "bank_transfer",
    "direction": "payin",
    "org_id": "your-org-id",
    "client_reference": "your-unique-reference",
    "description": "Payment description",
    "payer_details": {
      "email": "payer@example.com",
      "name": "John Doe"
    },
    "metadata": {
      "beneficiary_name": "Recipient Name",
      "reason": "Payment reason"
    }
  }'
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "payment_id": "34751905-725f-4e1a-a0e6-998666aabee3",
  "transaction_id": "835de352-cf44-4330-8a90-d835a169e895",
  "response": {
    "success": true,
    "status": "initiated",
    "next_action": "redirect",
    "redirect_url": "https://remittances.pcxpay.com/xxxx?ref=eyJwYXltZW50X2lkIjoiMzQ3NTE5MDUtNzI1Zi00ZTFhLWEwZTYtOTk4NjY2YWFiZWUzIiwiYW1vdW50IjoxMDAuMCwiY3VycmVuY3kiOiJHQlAifQ==",
    "message": "Payment initiated. Redirect user to complete payment."
  }
}
```

Use `response.redirect_url` as the `src` of the iFrame. Do not construct this URL yourself — always use the value returned by PCX.

***

## Request headers

| Header          | Required | Description                                                        |
| --------------- | -------- | ------------------------------------------------------------------ |
| `Authorization` | Yes      | `Bearer <JWT>` if using JWT auth; set to `NONE` when using API key |
| `X-Api-Key`     | Yes      | Your organisation's API key; set to `NONE` when using JWT auth     |
| `Content-Type`  | Yes      | `application/json`                                                 |

Both headers must always be present. Set whichever one you are not using to the literal string `NONE`.

***

## Request fields

| Field                 | Type   | Required | Description                                       |
| --------------------- | ------ | -------- | ------------------------------------------------- |
| `amount`              | number | Yes      | Payment amount in source currency                 |
| `currency`            | string | Yes      | Source currency code (e.g. `GBP`)                 |
| `target_amount`       | number | Yes      | Amount in target/settlement currency              |
| `target_currency`     | string | Yes      | Target currency code (e.g. `GBP`)                 |
| `country`             | string | Yes      | Country code (e.g. `GB`)                          |
| `payment_method`      | string | Yes      | Must be `bank_transfer`                           |
| `direction`           | string | Yes      | Must be `payin`                                   |
| `org_id`              | string | Yes      | Your organisation ID                              |
| `client_reference`    | string | No       | Your unique reference for this payment            |
| `description`         | string | No       | Human-readable payment description                |
| `payer_details.email` | string | No       | Payer's email address                             |
| `payer_details.name`  | string | No       | Payer's full name                                 |
| `metadata`            | object | No       | Arbitrary key-value pairs stored with the payment |

***

## Response fields

| Field                   | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `payment_id`            | PCX's unique payment identifier — use to look up payment status |
| `transaction_id`        | PCX transaction identifier                                      |
| `response.redirect_url` | URL to set as the iFrame `src`                                  |
| `response.next_action`  | Will be `redirect` for iFrame flows                             |
| `response.status`       | Initial status — `initiated`                                    |

***

## The redirect URL

The `redirect_url` contains a base64-encoded `ref` parameter with the payment identifiers:

```
https://remittances.pcxpay.com/xxxx?ref=<base64_encoded_data>
```

Decoded `ref` structure:

```json theme={null}
{
  "payment_id": "34751905-725f-4e1a-a0e6-998666aabee3",
  "amount": 100.0,
  "currency": "GBP"
}
```

<Warning>
  Do not modify the `ref` parameter. The payment details are validated against the database when the payment is processed. Tampering with the parameter will cause the payment to fail.
</Warning>

<Warning>
  Do not expose your API key in client-side code. The payment initiation call must always originate from your platform.
</Warning>