API reference

Developer Payout Setup API

Select an eligible destination, verify a PayPal payout email and distinguish setup from payment execution.

Start with getting started Explore API docs

SoundSync

Choose and verify a payout destination

Complete the business profile
Use the actual registered-business country. A bank or PayPal account country is a separate fact; do not change business country to bypass provider requirements.
Have the owner select the provider
One payout provider is active per developer and environment. The workspace owner controls destination setup; read-only billing access does not grant onboarding authority.
Complete Stripe requirements
Finish the Connect requirements and inspect live readiness. Eligible same-country routes can quote local bank settlement; availability depends on the country, bank and saved account status.
Verify PayPal separately if chosen
Use the payout email you own, which can differ from the login email. Verify the eight-digit code, supply the registered PayPal country and confirm the account can receive USD. Live PayPal sending awaits provider approval.
Review changes before the run
A destination change can impose a 24-hour wait. A transfer or bank payment in progress can prevent switching providers. Saving an email is not a payment or proof of provider eligibility.

SoundSync

Verify the destination before saving it

The current setup form keeps email verification, account country and destination selection distinct. This is example setup, not a payment; live PayPal sending awaits provider approval.

Current payout-method controls with PayPal email verification and registered-country confirmation, using only an example email placeholder. — Payout destination setup, not a completed payout. Live PayPal sending still requires provider approval. Sensitive account values are blurred.

SoundSync

Supported setup aliases

POST /api/developer/earnings/payout-method

Select one Stripe or PayPal developer payout destination

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: provider: stripe | paypal (required)
environment: test | live
paypalEmail: string
email: string. Supported alias for paypalEmail.
paypalAccountCountry: string
confirmPayPalAccount: boolean
Returns: HTTP 200: provider, currency, environment, connection.
Notes: For PayPal, verify the SoundSync account and payout email first, provide the registered PayPal country, and confirm account ownership/ability to receive USD. paypalEmail takes precedence over the email alias; an existing saved PayPal email may be reused when neither is sent. Confirmation must be true. Changing a destination can impose a 24-hour wait. In-progress payments block provider switching. Email verification or saving PayPal details does not prove live Payouts approval; live sending remains subject to provider activation. Stripe local settlement does not change USD accounting.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "stripe",
        "paypal"
      ]
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    },
    "paypalEmail": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$",
      "description": "Supported alias for paypalEmail."
    },
    "paypalAccountCountry": {
      "type": "string"
    },
    "confirmPayPalAccount": {
      "type": "boolean"
    }
  },
  "additionalProperties": true,
  "required": [
    "provider"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "provider": {
            "const": "paypal"
          }
        },
        "required": [
          "provider"
        ]
      },
      "then": {
        "properties": {
          "confirmPayPalAccount": {
            "const": true
          }
        },
        "required": [
          "confirmPayPalAccount"
        ]
      }
    }
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "stripe",
        "paypal"
      ]
    },
    "currency": {
      "const": "usd"
    },
    "environment": {
      "type": "string"
    },
    "connection": {
      "anyOf": [
        {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

Operation errors: PAYPAL_ACCOUNT_CONFIRMATION_REQUIRED, PAYPAL_EMAIL_VERIFICATION_REQUIRED, PAYPAL_ACCOUNT_COUNTRY_REQUIRED, PAYOUT_EMAIL_NOT_VERIFIED, PAYPAL_COUNTRY_UNSUPPORTED, PAYPAL_PAYOUTS_DISABLED, PAYOUT_IN_PROGRESS, STRIPE_USD_PAYOUT_COUNTRY_UNAVAILABLE.

POST /api/developer/earnings/payout-email/send-code

Send a private verification code to the proposed PayPal payout email

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: email: string (required)
environment: test | live
Returns: HTTP 200: verification.
Notes: Eight-digit code, fifteen-minute expiry, one-minute resend cooldown and five sends per hour. Sends a transactional email. It does not change the active destination or prove PayPal eligibility. verification:null means the delivery result no longer matches an active request, for example because the provider was switched during sending. Do not mark that email verified or silently resend; reload the saved destination and verification state.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "email"
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "verification": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "email": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verified",
                "locked",
                "expired",
                "delivery_failed"
              ]
            },
            "expiresAt": {
              "type": "string",
              "format": "date-time"
            },
            "resendAt": {
              "type": "string",
              "format": "date-time"
            }
          },
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: INVALID_PAYPAL_EMAIL, PAYOUT_EMAIL_NOT_VERIFIED, PAYPAL_COUNTRY_UNSUPPORTED, PAYOUT_EMAIL_COOLDOWN, PAYOUT_EMAIL_RATE_LIMIT, PAYOUT_EMAIL_DELIVERY_FAILED.

POST /api/developer/earnings/payout-email/verify

Verify the proposed PayPal payout email before saving it

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: email: string (required)
code: string (required)
environment: test | live
Returns: HTTP 200: verification.
Notes: Five failed attempts lock this code. A successful verification does not save the payout method: complete payout-method separately.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "code": {
      "type": "string",
      "pattern": "^[0-9]{8}$"
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "email",
    "code"
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "verification": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "verified",
            "locked",
            "expired",
            "delivery_failed"
          ]
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "resendAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: INVALID_PAYPAL_EMAIL, PAYOUT_EMAIL_CODE_EXPIRED, PAYOUT_EMAIL_CODE_LOCKED, PAYOUT_EMAIL_CODE_INVALID.

POST /api/developer/settlements/payout-method

Select one Stripe or PayPal developer payout destination

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: provider: stripe | paypal (required)
environment: test | live
paypalEmail: string
email: string. Supported alias for paypalEmail.
paypalAccountCountry: string
confirmPayPalAccount: boolean
Returns: HTTP 200: provider, currency, environment, connection.
Notes: For PayPal, verify the SoundSync account and payout email first, provide the registered PayPal country, and confirm account ownership/ability to receive USD. paypalEmail takes precedence over the email alias; an existing saved PayPal email may be reused when neither is sent. Confirmation must be true. Changing a destination can impose a 24-hour wait. In-progress payments block provider switching. Email verification or saving PayPal details does not prove live Payouts approval; live sending remains subject to provider activation. Stripe local settlement does not change USD accounting.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "stripe",
        "paypal"
      ]
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    },
    "paypalEmail": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$",
      "description": "Supported alias for paypalEmail."
    },
    "paypalAccountCountry": {
      "type": "string"
    },
    "confirmPayPalAccount": {
      "type": "boolean"
    }
  },
  "additionalProperties": true,
  "required": [
    "provider"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "provider": {
            "const": "paypal"
          }
        },
        "required": [
          "provider"
        ]
      },
      "then": {
        "properties": {
          "confirmPayPalAccount": {
            "const": true
          }
        },
        "required": [
          "confirmPayPalAccount"
        ]
      }
    }
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "stripe",
        "paypal"
      ]
    },
    "currency": {
      "const": "usd"
    },
    "environment": {
      "type": "string"
    },
    "connection": {
      "anyOf": [
        {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

POST /api/developer/settlements/payout-email/send-code

Send a private verification code to the proposed PayPal payout email

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: email: string (required)
environment: test | live
Returns: HTTP 200: verification.
Notes: Eight-digit code, fifteen-minute expiry, one-minute resend cooldown and five sends per hour. Sends a transactional email. It does not change the active destination or prove PayPal eligibility. verification:null means the delivery result no longer matches an active request, for example because the provider was switched during sending. Do not mark that email verified or silently resend; reload the saved destination and verification state.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "email"
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "verification": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "email": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verified",
                "locked",
                "expired",
                "delivery_failed"
              ]
            },
            "expiresAt": {
              "type": "string",
              "format": "date-time"
            },
            "resendAt": {
              "type": "string",
              "format": "date-time"
            }
          },
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: INVALID_PAYPAL_EMAIL, PAYOUT_EMAIL_NOT_VERIFIED, PAYPAL_COUNTRY_UNSUPPORTED, PAYOUT_EMAIL_COOLDOWN, PAYOUT_EMAIL_RATE_LIMIT, PAYOUT_EMAIL_DELIVERY_FAILED.

POST /api/developer/settlements/payout-email/verify

Verify the proposed PayPal payout email before saving it

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: email: string (required)
code: string (required)
environment: test | live
Returns: HTTP 200: verification.
Notes: Five failed attempts lock this code. A successful verification does not save the payout method: complete payout-method separately.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "code": {
      "type": "string",
      "pattern": "^[0-9]{8}$"
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "email",
    "code"
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "verification": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "verified",
            "locked",
            "expired",
            "delivery_failed"
          ]
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "resendAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: INVALID_PAYPAL_EMAIL, PAYOUT_EMAIL_CODE_EXPIRED, PAYOUT_EMAIL_CODE_LOCKED, PAYOUT_EMAIL_CODE_INVALID.

POST /api/developer/payouts/payout-method

Select one Stripe or PayPal developer payout destination

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: provider: stripe | paypal (required)
environment: test | live
paypalEmail: string
email: string. Supported alias for paypalEmail.
paypalAccountCountry: string
confirmPayPalAccount: boolean
Returns: HTTP 200: provider, currency, environment, connection.
Notes: For PayPal, verify the SoundSync account and payout email first, provide the registered PayPal country, and confirm account ownership/ability to receive USD. paypalEmail takes precedence over the email alias; an existing saved PayPal email may be reused when neither is sent. Confirmation must be true. Changing a destination can impose a 24-hour wait. In-progress payments block provider switching. Email verification or saving PayPal details does not prove live Payouts approval; live sending remains subject to provider activation. Stripe local settlement does not change USD accounting.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "stripe",
        "paypal"
      ]
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    },
    "paypalEmail": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$",
      "description": "Supported alias for paypalEmail."
    },
    "paypalAccountCountry": {
      "type": "string"
    },
    "confirmPayPalAccount": {
      "type": "boolean"
    }
  },
  "additionalProperties": true,
  "required": [
    "provider"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "provider": {
            "const": "paypal"
          }
        },
        "required": [
          "provider"
        ]
      },
      "then": {
        "properties": {
          "confirmPayPalAccount": {
            "const": true
          }
        },
        "required": [
          "confirmPayPalAccount"
        ]
      }
    }
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "stripe",
        "paypal"
      ]
    },
    "currency": {
      "const": "usd"
    },
    "environment": {
      "type": "string"
    },
    "connection": {
      "anyOf": [
        {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

POST /api/developer/payouts/payout-email/send-code

Send a private verification code to the proposed PayPal payout email

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: email: string (required)
environment: test | live
Returns: HTTP 200: verification.
Notes: Eight-digit code, fifteen-minute expiry, one-minute resend cooldown and five sends per hour. Sends a transactional email. It does not change the active destination or prove PayPal eligibility. verification:null means the delivery result no longer matches an active request, for example because the provider was switched during sending. Do not mark that email verified or silently resend; reload the saved destination and verification state.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "email"
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "verification": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "email": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verified",
                "locked",
                "expired",
                "delivery_failed"
              ]
            },
            "expiresAt": {
              "type": "string",
              "format": "date-time"
            },
            "resendAt": {
              "type": "string",
              "format": "date-time"
            }
          },
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: INVALID_PAYPAL_EMAIL, PAYOUT_EMAIL_NOT_VERIFIED, PAYPAL_COUNTRY_UNSUPPORTED, PAYOUT_EMAIL_COOLDOWN, PAYOUT_EMAIL_RATE_LIMIT, PAYOUT_EMAIL_DELIVERY_FAILED.

POST /api/developer/payouts/payout-email/verify

Verify the proposed PayPal payout email before saving it

Auth: Account Bearer session token
Scope: billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.
Request fields: email: string (required)
code: string (required)
environment: test | live
Returns: HTTP 200: verification.
Notes: Five failed attempts lock this code. A successful verification does not save the payout method: complete payout-method separately.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 127,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "code": {
      "type": "string",
      "pattern": "^[0-9]{8}$"
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "email",
    "code"
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "verification": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "verified",
            "locked",
            "expired",
            "delivery_failed"
          ]
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "resendAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: INVALID_PAYPAL_EMAIL, PAYOUT_EMAIL_CODE_EXPIRED, PAYOUT_EMAIL_CODE_LOCKED, PAYOUT_EMAIL_CODE_INVALID.

Sale earnings and the received payout are different

SoundSync covers ordinary payment processing on SoundSync-managed checkout, not on payments collected by outside resellers or partners. Sending a developer payout is a separate service: applicable provider payout, active-account, cross-border and currency-conversion costs are developer-paid and itemized or reconciled against the payout balance. They are not another marketplace percentage or a second checkout-processing charge.

A $49 pre-tax sale less the 10% SoundSync fee produces $44.10 in sale earnings before any agreed affiliate/collaborator allocation. The payout preview then shows applicable sending costs, invoice offsets and other recorded adjustments to the eligible balance.

Where local-currency settlement is available, the displayed FX quote already includes its conversion cost; it must not be counted twice. Cross-border amounts can be estimates. Provider-reported fees are authoritative, and a later difference can debit or credit a future payout. Cent rounding remains in your balance, not a hidden fee.

Setup is not payment execution

These operations do not approve or send payouts. Test and live destinations are separate. Use the existing summary, history and CSV operations to inspect readiness and completed provider records. Never infer a bank receipt from a saved destination or a successful status refresh.

SoundSync

Related reporting

Billing API

Statements, summary, history and payout status.

Explore

Payout guide

Availability, quote interpretation and changing a destination.

Explore

SoundSync

Payout setup response states

Response or input	Next step
verification.status: pending	The code has been sent, not verified. Enter the current code for the same email and environment.
verification.status: verified	Verification succeeded. Saving the payout destination is still a separate action.
verification: null	The send result no longer matches an active request, for example after switching providers during delivery. Reload the saved destination and verification state. Do not treat this as verified or silently send another code.
Expired, locked or delivery_failed	Use the returned error or current verification state. Respect the cooldown and hourly limits before requesting a new code.
confirmPayPalAccount: true	Required when selecting PayPal. Confirm ownership and ability to receive USD; use the actual registered PayPal country.
paypalEmail / email	paypalEmail is preferred; email is an accepted alias. If both are omitted, an existing saved PayPal email may be reused. A different email still needs verification.

Choose and verify a payout destination

Complete the business profile

Have the owner select the provider

Complete Stripe requirements

Verify PayPal separately if chosen

Review changes before the run

Verify the destination before saving it

Supported setup aliases

Request (application/json)

HTTP 200 response (application/json)

Request (application/json)

HTTP 200 response (application/json)

Request (application/json)

HTTP 200 response (application/json)

Request (application/json)

HTTP 200 response (application/json)

Request (application/json)

HTTP 200 response (application/json)

Request (application/json)

HTTP 200 response (application/json)

Request (application/json)

HTTP 200 response (application/json)

Request (application/json)

HTTP 200 response (application/json)

Request (application/json)

HTTP 200 response (application/json)

Sale earnings and the received payout are different

Setup is not payment execution

Related reporting

Billing API

Payout guide

Payout setup response states