> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.
# New Payment Request
> # Create Payment Request
This endpoint requires authentication. Include your Bearer token in the Authorization header.
## Description
**Endpoint:** `/payment-request/`
**Method:** `POST`
## **Request Body**
| Field | Type | Required | Description |
| ------------------ | -------- | -------- | ------------------------------------------------ |
| `PaymentSettingId` | `string` | Yes | ID of the payment setting being used. |
| `currency` | `string` | Yes | Currency code for the payment. |
| `amountUSD` | `number` | Yes | Amount in USD. |
| `amount` | `number` | No | Amount in the specified currency (optional). |
| `memo` | `string` | No | Optional memo describing the purpose of payment. |
This endpoint allows you to create a new payment request, specifying the payment setting ID, currency, amounts, and an optional memo.
## Code Examples
```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/payment-request/', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"user": "sample-user",
"PaymentSettingId": "sample-PaymentSettingId",
"currency": "sample-currency",
"amountUSD": 1,
"amount": 1,
"memo": "sample-memo"
})
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.royalti.io/payment-request/',
headers={
'Authorization': f'Bearer {token}'
},
json={"user":"sample-user","PaymentSettingId":"sample-PaymentSettingId","currency":"sample-currency","amountUSD":1,"amount":1,"memo":"sample-memo"}
)
data = response.json()
print(data)
```
```bash cURL theme={null}
curl -X POST https://api.royalti.io/payment-request/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"user":"sample-user","PaymentSettingId":"sample-PaymentSettingId","currency":"sample-currency","amountUSD":1,"amount":1,"memo":"sample-memo"}'
```
## OpenAPI
````yaml post /payment-request/
openapi: 3.0.0
info:
title: Royalti.io API
description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
version: 2.6.0
contact:
name: Royalti.io Support
email: support@royalti.io
url: https://royalti.io
license:
name: Proprietary
url: https://royalti.io/terms
servers:
- url: https://api.royalti.io
description: Production server
- url: https://api-dev.royalti.io
description: Development server
- url: http://localhost:8084
description: Local development
security:
- bearerAuth: []
tags:
- name: Accounting
description: Accounting and financial transaction operations
- name: DDEX
description: DDEX operations (ERN/MEAD, messages, delivery, providers)
- name: Label
description: Label management operations
- name: Internal Webhooks
description: Internal system webhooks for royalty processing and downloads
- name: Payment Webhooks
description: Payment processor webhook endpoints
- name: Billing Webhooks
description: Stripe billing and subscription webhooks
- name: Infrastructure Webhooks
description: Cloudflare domain and SSL webhooks
- name: Distribution Webhooks
description: Digital distribution platform webhooks (FUGA)
paths:
/payment-request/:
post:
tags:
- Payment Requests
summary: New Payment Request
description: >-
# Create Payment Request
**Endpoint:** `/payment-request/`
**Method:** `POST`
## **Request Body**
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `PaymentSettingId` | `string` | Yes | ID of the payment setting being
used. |
| `currency` | `string` | Yes | Currency code for the payment. |
| `amountUSD` | `number` | Yes | Amount in USD. |
| `amount` | `number` | No | Amount in the specified currency
(optional). |
| `memo` | `string` | No | Optional memo describing the purpose of
payment. |
This endpoint allows you to create a new payment request, specifying the
payment setting ID, currency, amounts, and an optional memo.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
user:
type: string
format: uuid
description: >-
ID of the user to create the payment request for. Admin/API
key only. If not provided, creates for authenticated user.
PaymentSettingId:
type: string
description: >-
ID of the payment setting being used. Optional during
creation but required for approval and payment processing.
currency:
type: string
description: Currency code for the payment
amountUSD:
type: number
description: Amount in USD
amount:
type: number
description: Amount in the specified currency
memo:
type: string
description: Optional memo describing the purpose of payment
required:
- currency
- amountUSD
example:
PaymentSettingId: 24d2c371-4a7a-4acd-b4aa-d3eb3bebd8fa
currency: USD
amountUSD: 500
amount: 130
memo: Payment for services rendered
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
message:
type: string
newpayment:
type: object
properties:
id:
type: string
status:
type: string
TenantId:
type: integer
TenantUserId:
type: string
transactionDate:
type: string
format: date
currency:
type: string
amountUSD:
type: number
amount:
type: number
memo:
type: string
updatedAt:
type: string
format: date-time
createdAt:
type: string
format: date-time
example:
status: success
message: Payment Request created successfully
newpayment:
id: 0654cd19-cea3-4fad-b92e-4033c4252c79
status: pending
TenantId: 2
TenantUserId: f4b4e2f8-fe5e-4076-9e09-3424ff7f185f
transactionDate: '2023-04-21'
currency: USD
amountUSD: 100
amount: 74000
memo: Sale of album
updatedAt: '2023-11-22T20:48:36.034Z'
createdAt: '2023-11-22T20:48:36.034Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth: []
components:
schemas:
Error:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Authorization header using the Bearer scheme. Format: "Bearer
{token}"
````