Update Payment Request

curl --request PATCH \
  --url https://api.voiceaiwrapper.app/api/v2/external-billing/payment-requests/{payment_request_id}/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "PAID",
  "external_payment_id": "txn_abc123"
}
'

{
  "message": "Payment status updated successfully.",
  "data": {
    "id": "10",
    "client_id": "42",
    "client_name": "Acme Corp",
    "subscription_id": "1",
    "status": "PAID",
    "type": "SUBSCRIPTION",
    "amount": "99.00",
    "currency": "USD",
    "due_date": "2025-01-15T00:00:00",
    "grace_period_ends_at": "2025-01-22T00:00:00",
    "paid_at": "2025-01-14T09:30:00",
    "external_payment_id": "txn_abc123",
    "notes": null,
    "line_items": [],
    "period_start": "2025-01-01T00:00:00",
    "period_end": "2025-02-01T00:00:00",
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-14T09:30:00"
  }
}

{
  "message": "Invalid status 'UNKNOWN'.",
  "valid_values": [
    "PENDING",
    "PAID",
    "FAILED",
    "CANCELED",
    "OVERDUE"
  ]
}

{
  "message": "Authorization header not found"
}

{
  "message": "External Billing API access requires a PRO plan. Error Code: external_billing_api"
}

{
  "message": "Payment request not found"
}

{
  "message": "Internal server error"
}

PATCH

api

external-billing

payment-requests

{payment_request_id}

update

curl --request PATCH \
  --url https://api.voiceaiwrapper.app/api/v2/external-billing/payment-requests/{payment_request_id}/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "PAID",
  "external_payment_id": "txn_abc123"
}
'

{
  "message": "Payment status updated successfully.",
  "data": {
    "id": "10",
    "client_id": "42",
    "client_name": "Acme Corp",
    "subscription_id": "1",
    "status": "PAID",
    "type": "SUBSCRIPTION",
    "amount": "99.00",
    "currency": "USD",
    "due_date": "2025-01-15T00:00:00",
    "grace_period_ends_at": "2025-01-22T00:00:00",
    "paid_at": "2025-01-14T09:30:00",
    "external_payment_id": "txn_abc123",
    "notes": null,
    "line_items": [],
    "period_start": "2025-01-01T00:00:00",
    "period_end": "2025-02-01T00:00:00",
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-14T09:30:00"
  }
}

{
  "message": "Invalid status 'UNKNOWN'.",
  "valid_values": [
    "PENDING",
    "PAID",
    "FAILED",
    "CANCELED",
    "OVERDUE"
  ]
}

{
  "message": "Authorization header not found"
}

{
  "message": "External Billing API access requires a PRO plan. Error Code: external_billing_api"
}

{
  "message": "Payment request not found"
}

{
  "message": "Internal server error"
}

This endpoint requires a PRO plan or above. If your plan does not include the External Billing API, the request returns 403 with error code external_billing_api.

What happens when you mark a request as `PAID`

Sending "status": "PAID" triggers the internal payment service in addition to updating the status field:

paid_at is recorded with the current timestamp.
external_payment_id is stored if provided (useful as a reference to your payment processor’s transaction ID).
The platform checks whether the linked subscription has any remaining unpaid cycle requests (PENDING or OVERDUE).
- If none remain → subscription status returns to active and any paused campaigns are automatically resumed.
- If others remain → subscription stays in its current state until all are resolved.

`external_payment_id` is optional

You can mark a request as PAID without providing external_payment_id. It is recommended when you have a transaction reference from your payment processor (e.g. txn_abc123, pi_abc123 from Stripe), but the field is not required.

Status reference

Status	When to use
`PAID`	Client has paid. Triggers subscription recovery if no other cycle requests are outstanding.
`PENDING`	Reset to pending (e.g. if you marked paid by mistake).
`FAILED`	Payment attempt failed - client should be contacted.
`CANCELED`	Charge is void - no payment needed.
`OVERDUE`	Mark manually overdue (normally set automatically by the platform’s sweep).

Setting a cycle request to PAID can change the subscription status and resume paused campaigns. Verify you are acting on the correct payment request before proceeding.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

payment_request_id

string

required

Integer ID of the payment request to update.

Example:

"10"

Body

application/json

status

enum<string>

required

New status for the payment request. Required.

Available options:

PENDING,

PAID,

FAILED,

CANCELED,

OVERDUE

Example:

"PAID"

external_payment_id

string

Optional external transaction reference (e.g. txn_abc123 from your payment processor). Recommended when setting status to PAID.

Example:

"txn_abc123"

Response

Payment request updated successfully. Returns a confirmation message and the full updated payment request object.

message

string

Confirmation that the payment request status was updated.

Example:

"Payment status updated successfully."

data

object

Show child attributes

Getting Started

Campaigns

Client Account Configurations

Web Widgets

Client Forms

Agents

Clients

Voice Providers

Leads (v1)

Leads (v2)

External Billing

What happens when you mark a request as `PAID`

`external_payment_id` is optional

Status reference

Authorizations

Path Parameters

Body

Response

​What happens when you mark a request as PAID

​external_payment_id is optional

​Status reference

Authorizations

Path Parameters

Body

Response

What happens when you mark a request as `PAID`

`external_payment_id` is optional

Status reference