# Create payment link

`POST /v2/payments/intents/link`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobpay.co.za`
- Production: `https://api.bobpay.co.za`

**Authentication:** Bearer token required. Obtain one via `POST /login` (see the Authentication page).

## Example request

```bash
curl -X POST "https://api.sandbox.bobpay.co.za/v2/payments/intents/link" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "amount": 499.99,
    "email": "customer@gmail.co.za",
    "mobile_number": "",
    "custom_payment_id": "478",
    "item_name": "Order 1452",
    "item_description": "Lego Star Wars",
    "notify_url": "https://api-sandbox.mystore.co.za/payment/bobpay",
    "success_url": "https://sandbox.mystore.co.za/accounts/payment-confirmation",
    "pending_url": "https://sandbox.mystore.co.za/accounts/payment-confirmation",
    "cancel_url": "https://sandbox.mystore.co.za/accounts/payment-cancel",
    "short_url": true
}'
```

This endpoint allows you to generate a unique, secure payment link for a customer, which they can use to complete payment via supported methods. Optionally, a shortened URL can be returned for easier sharing.

---

The payment is made to the account you are authenticated as, so no account code or signature is required.

### Request body parameters

| Key | Description | Type | Required |
| --- | --- | --- | --- |
| amount | The payment amount in ZAR. Must be greater than zero. | float | Yes |
| email | Payer's email address. | string | Conditional* |
| mobile_number | Payer's mobile number in international format (e.g., +27821234567). | string | Conditional* |
| custom_payment_id | Your unique reference for this payment. If not provided, a UUID is generated automatically. | string | No |
| item_name | Name of the item being purchased. | string | No |
| item_description | Description of the item. | string | No |
| notify_url | URL to send payment status notifications to. | string | No |
| success_url | URL to redirect to on successful payment. | string | No |
| pending_url | URL to redirect to if payment is pending. | string | No |
| cancel_url | URL to redirect to if payment is cancelled. | string | No |
| payment_method | Direct the payer to a specific payment method (e.g., `credit-card`). Omit to show all available payment methods. | string | No |
| short_url | Set to `true` to also return a shortened payment link. | boolean | No |

\* **Note:** Either `email` or `mobile_number` must be provided.

---

### Response

**Status code:** 200 OK
**Content-Type:** application/json

**Response body**

```json
{
    "url": "https://sandbox.bobpay.co.za/pay/ref/3WFFG",
    "short_url": "https://api.sandbox.bob.co.za/r/V4X7WG"
}
```

---

### Response fields

| Field | Description | Type |
| --- | --- | --- |
| url | The unique payment link for the transaction. | string |
| short_url | Shortened version of the payment link. Equal to `url` unless `short_url: true` was requested. | string |