> For the complete documentation index, see [llms.txt](https://roqqu-api-services.gitbook.io/ras/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://roqqu-api-services.gitbook.io/ras/payment-links/create-payment-link.md).
# Create Payment Link
Creates a new payment link that generates unique wallet addresses for customers to make cryptocurrency payments. Supported networks: Bitcoin (BTC), Tron (TRC20 USDT), and BNB Smart Chain (BEP20 USDT). You can either pre-generate wallet addresses at creation by passing the `wallets` parameter, or omit it to have wallets generated on demand when the customer starts a payment session (via the payment link session endpoint). See **Get Supported Networks** above for the list of valid network/token combinations.
**Endpoint:** `POST /payment-links`
**Authentication:** Required (x-api-key header for live, x-staging-api-key for sandbox)
#### Webhook Events
When a payment is processed, you will receive webhook notifications with the following event types:
* **payment\_link\_completed**: Triggered when payment is successfully completed (exact amount)
* **payment\_link\_completed\_overpaid**: Triggered when payment is completed but customer overpaid
* **payment\_link\_failed**: Triggered when payment fails or is underpaid
See the Webhook Events section for complete payload structures.
#### Request Parameters
| Parameter | Type | Required | Description |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| amount | number | Yes | Payment amount (must be greater than 0) |
| customer\_details | string | Yes | JSON string containing customer information. Required fields: email, first\_name, last\_name. Optional field: phone |
| payment\_reference | string | Yes | Alphanumeric reference for this payment (1-20 characters, letters and numbers only). Used to identify the payment in your system |
| success\_url | string | Yes | HTTPS URL to redirect customer after successful payment. Must use HTTPS protocol |
| cancel\_url | string | Yes | HTTPS URL to redirect customer if payment is cancelled. Must use HTTPS protocol |
| expires\_at | string | No | ISO 8601 date-time when the payment link expires. Must be a future date. If not provided, defaults to 2 hours from creation time |
| metadata | string | No | Optional JSON string containing additional metadata you want to store with the payment link. This will be included in webhook notifications |
| amount\_currency | string | No | Currency code for the amount (default: 'ngn'). Must be a supported currency |
| wallets | array | No | Optional array of `{ network, token }` objects. If provided and non-empty, wallet addresses are generated at creation. If omitted or empty, wallets are generated on demand when the customer starts a session. Valid combinations: bitcoin/BTC, trc20/USDT, bep20/USDT. Only one wallet per network allowed |
#### Example Request (with pre-generated wallets)
```
curl -X POST https://service.roqqu.com/v1/payment-links \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "amount=1000" \
-d "customer_details={\"email\":\"customer@example.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"phone\":\"+1234567890\"}" \
-d "payment_reference=ORDER123ABC" \
-d "success_url=https://yourwebsite.com/payment/success" \
-d "cancel_url=https://yourwebsite.com/payment/cancel" \
-d "amount_currency=ngn" \
-d "wallets=[{\"network\":\"bitcoin\",\"token\":\"BTC\"},{\"network\":\"trc20\",\"token\":\"USDT\"},{\"network\":\"bep20\",\"token\":\"USDT\"}]"
```
#### Example Request (on-demand wallets)
Omit `wallets` to have wallet addresses generated when the customer starts a payment session:
```
curl -X POST https://service.roqqu.com/v1/payment-links \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "amount=1000" \
-d "customer_details={\"email\":\"customer@example.com\",\"first_name\":\"John\",\"last_name\":\"Doe\"}" \
-d "payment_reference=ORDER123ABC" \
-d "success_url=https://yourwebsite.com/payment/success" \
-d "cancel_url=https://yourwebsite.com/payment/cancel" \
-d "amount_currency=ngn"
```
#### Example Response (pre-generated wallets)
When `wallets` was provided, the response includes wallet addresses and `wallet_pre_generated` is 1:
```
{
"status": "success",
"message": "payment link generated successfully",
"data": {
"refid": "abc123def456ghi789",
"payment_reference": "ORDER123ABC",
"payment_link": "https://payment.roqqu.com/abc123def456ghi789",
"wallets": [
{
"address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"network": "bitcoin",
"token": "BTC"
},
{
"address": "TXYZabcdefghijklmnopqrstuvwxyz123456",
"network": "trc20",
"token": "USDT"
},
{
"address": "0x1234567890abcdef1234567890abcdef12345678",
"network": "bep20",
"token": "USDT"
}
],
"wallet_pre_generated": 1,
"amount_required": 1000,
"amount_currency": "ngn",
"expires_at": "2024-12-31T23:59:59Z"
}
}
```
#### Example Response (on-demand wallets)
When `wallets` was omitted or empty, `data.wallets` is empty and `wallet_pre_generated` is 0. Wallet addresses are created when the customer starts a session via the payment link:
```
{
"status": "success",
"message": "payment link generated successfully",
"data": {
"refid": "abc123def456ghi789",
"payment_reference": "ORDER123ABC",
"payment_link": "https://payment.roqqu.com/abc123def456ghi789",
"wallets": [],
"wallet_pre_generated": 0,
"amount_required": 1000,
"amount_currency": "ngn",
"expires_at": "2024-12-31T23:59:59Z"
}
}
```