> ## 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.
# VertoFX payment status webhook
> Receives payment status updates from VertoFX payment processor.
This endpoint requires authentication. Include your Bearer token in the Authorization header.
## Description
**Authentication:** Uses IP whitelist validation (no headers required).
**Workflow:**
1. Validates payment state is 'completed'
2. Validates payment type is 'account\_to\_wallet'
3. Updates Payment record status to 'completed'
## Code Examples
```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/webhook/verto/payment-outward/webhook', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"id": "verto_txn_abc123xyz",
"paymentId": "p1234567-89ab-cdef-0123-456789abcdef",
"status": "completed",
"state": "completed",
"type": "account_to_wallet",
"amount": 1250.75,
"currency": "USD",
"reference": "REF-2024-001234",
"account": {
"name": "John Doe",
"number": "****5678"
}
})
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.royalti.io/webhook/verto/payment-outward/webhook',
headers={
'Authorization': f'Bearer {token}'
},
json={"id":"verto_txn_abc123xyz","paymentId":"p1234567-89ab-cdef-0123-456789abcdef","status":"completed","state":"completed","type":"account_to_wallet","amount":1250.75,"currency":"USD","reference":"REF-2024-001234","account":{"name":"John Doe","number":"****5678"}}
)
data = response.json()
print(data)
```
```bash cURL theme={null}
curl -X POST https://api.royalti.io/webhook/verto/payment-outward/webhook \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"verto_txn_abc123xyz","paymentId":"p1234567-89ab-cdef-0123-456789abcdef","status":"completed","state":"completed","type":"account_to_wallet","amount":1250.75,"currency":"USD","reference":"REF-2024-001234","account":{"name":"John Doe","number":"****5678"}}'
```
## OpenAPI
````yaml post /webhook/verto/payment-outward/webhook
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:
/webhook/verto/payment-outward/webhook:
post:
tags:
- Payment Webhooks
summary: VertoFX payment status webhook
description: |-
Receives payment status updates from VertoFX payment processor.
**Authentication:** Uses IP whitelist validation (no headers required).
**Workflow:**
1. Validates payment state is 'completed'
2. Validates payment type is 'account_to_wallet'
3. Updates Payment record status to 'completed'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
- paymentId
- status
- state
- type
properties:
id:
type: string
description: Verto transaction ID
example: verto_txn_abc123xyz
paymentId:
type: string
format: uuid
description: Royalti Payment record UUID
example: p1234567-89ab-cdef-0123-456789abcdef
status:
type: string
enum:
- pending
- processing
- completed
- failed
- cancelled
description: Payment status
example: completed
state:
type: string
description: Payment state (must be 'completed' for processing)
example: completed
type:
type: string
description: Transaction type (must be 'account_to_wallet')
example: account_to_wallet
amount:
type: number
format: decimal
description: Payment amount
example: 1250.75
currency:
type: string
description: Currency code
example: USD
reference:
type: string
description: Payment reference number
example: REF-2024-001234
account:
type: object
description: Account details
properties:
name:
type: string
example: John Doe
number:
type: string
example: '****5678'
responses:
'200':
description: Webhook processed successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Payment record status is marked as completed
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
description: Payment record not found
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: error
message:
type: string
example: Payment Record not found
security:
- IPWhitelist: []
components:
responses:
BadRequestError:
description: Bad request - Invalid payload or validation error
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: error
message:
type: string
example: Invalid request data
UnauthorizedError:
description: Unauthorized - Invalid or missing authentication
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: error
message:
type: string
example: Invalid webhook signature
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Authorization header using the Bearer scheme. Format: "Bearer
{token}"
````