Payouts

Initiate a video payout

Creates the payout priced by POST /payouts/videos/calculate: pass its context, calculation and integrityToken back unchanged with your lineItems (free to customize; for fixed-amount terms they must add up to that amount). Mint the id yourself (orgpay_ plus 12 alphanumeric characters); it is the idempotency key, so a retry with the same id and the same details returns the original payout instead of paying twice, and the same id with different details is a 409. The payout counts toward the campaign whose terms were used, else toward the campaign the relation names. payoutProvider="manual" (the default) records a payment you already made elsewhere; payoutProvider="talentir" creates a Talentir payout that waits for approval by a member of your Talentir team in the dashboard — this route never approves one.

post/payouts/videos/initiate

Request

Base URL: https://viral.app/api/v1
URL: https://viral.app/api/v1/payouts/videos/initiate
Auth: API key in header x-api-key

Request body

idstring required

Payout id minted by the caller (orgpay_ plus 12 alphanumeric characters) — the idempotency key. Re-send the same id to retry: the same details return the original payout, different details are a 409.

creatorIdstring required

Organization creator ID with orgcre_ prefix

integrityTokenstring required

Integrity token returned by POST /payouts/videos/calculate. Pass it unchanged together with context and calculation.

referencestring

Optional payout reference for reconciliation, invoicing, or external bookkeeping.

notesstring

Optional internal payout notes visible to organization members.

payoutProvider'manual' | 'talentir'

"manual" records a payment made outside viral.app; "talentir" creates a Talentir payout that waits for approval in the dashboard.

Example request

{
  "id": "orgpay_RwmraAffhMt9",
  "context": {
    "videos": [
      {
        "platform": "facebook"
      }
    ],
    "coveringCampaignId": "orgcamp_RwmraAffhMt9",
    "termsCampaignId": "orgcamp_RwmraAffhMt9"
  },
  "calculation": {
    "metrics": {
      "perVideo": {
        "items": [
          {
            "platform": "facebook"
          }
        ]
      },
      "perCategory": [
        {
          "items": [
            {
              "platform": "facebook"
            }
          ]
        }
      ],
      "manuallyExcludedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "conditionMisses": [
        {
          "items": [
            {
              "platform": "facebook",
              "creative": {
                "by": {
                  "platform": "facebook"
                }
              }
            }
          ]
        }
      ],
      "carriedVideos": [
        {
          "items": [
            {
              "platform": "facebook"
            }
          ]
        }
      ],
      "mergedCopies": [
        {
          "items": [
            {
              "platform": "facebook",
              "into": {
                "platform": "facebook"
              }
            }
          ]
        }
      ]
    },
    "settlement": {
      "separatelyPaidVideos": [
        {
          "platform": "facebook"
        }
      ],
      "placedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "includedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "carriedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "priorCarriedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "timeZone": "UTC"
    },
    "engine": {
      "factTraces": [
        {
          "requirement": {
            "platformFilter": {
              "include": [
                "facebook"
              ],
              "exclude": [
                "facebook"
              ]
            }
          },
          "billingWindow": {
            "timeZone": "UTC"
          }
        }
      ],
      "engineEvents": [
        {
          "factTrace": {
            "requirement": {
              "platformFilter": {
                "include": [
                  "facebook"
                ],
                "exclude": [
                  "facebook"
                ]
              }
            },
            "billingWindow": {
              "timeZone": "UTC"
            }
          }
        }
      ],
      "accountSnapshot": {
        "accounts": [
          {
            "platform": "facebook",
            "platformAccountId": "7123456789012345678"
          }
        ]
      }
    }
  }
}

Response

successunknown required

payoutIdstring required

Payout ID with orgpay_ prefix

providerPayoutIdstring nullable

Example response

{
  "payoutId": "orgpay_RwmraAffhMt9"
}

Changes

No recorded changes to this operation across all 1 revision of this API.