API Docs
API referencePayment requests

Finalize a payment request

POST/api/v2/payment-requests/{id}/finalize

Moves a draft to open. For a counterparty payer, Talentir issues the invoice in your team's name and the response carries it in invoice. For an email payer, the invoice follows when the payer enters their billing details on paymentUrl. Talentir emails nothing; use send for that. After this, only tags can change, and the request cannot be deleted. Needs payment-requests:write.

Path Parameters

id*string

The payment request id (payment_request_…) or your customId.

Header Parameters

idempotency-key?maxLength(255)

Client-chosen key, 1 to 255 characters (a UUID is recommended). The same key on the same endpoint within 24 hours replays the stored response with Idempotent-Replayed: true.

Length1 <= length <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v2/payment-requests/payment_request_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e/finalize"
{  "object": "payment_request",  "id": "payment_request_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",  "customId": "campaign-42",  "description": "string",  "amount": "100.00",  "currency": "USD",  "amountDue": "100.00",  "amountRemaining": "100.00",  "payer": {    "type": "email",    "email": "jane@example.com"  },  "status": "draft",  "tags": [    "string"  ],  "paymentUrl": "string",  "invoice": {    "number": "string",    "url": "string",    "issuedAt": "string",    "vatRate": "19.00",    "vatAmount": "100.00",    "creditNote": {      "number": "string",      "url": "string",      "issuedAt": "string"    }  },  "settlements": [    {      "type": "bank_transfer",      "transactionId": "transaction_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e_out",      "status": "pending",      "amount": "100.00",      "createdAt": "2026-09-24T10:00:00.000Z"    }  ],  "sentAt": "2026-09-24T10:00:00.000Z",  "firstViewedAt": "2026-09-24T10:00:00.000Z",  "transferAnnouncedAt": "2026-09-24T10:00:00.000Z",  "paidAt": "2026-09-24T10:00:00.000Z",  "cancelledAt": "2026-09-24T10:00:00.000Z",  "createdAt": "2026-09-24T10:00:00.000Z",  "updatedAt": "2026-09-24T10:00:00.000Z"}

Delete a payment request DELETE

Allowed while `status` is `draft`. A finalized request is cancelled instead. A deleted request is gone from the API: every endpoint answers 404 `PAYMENT_REQUEST_NOT_FOUND` for it, and lists do not include it. Its `customId` is free again. Needs `payment-requests:write`.

Send a payment request POST

Talentir emails `paymentUrl` to the payer and sets `sentAt`. A `draft` is finalized first. With an invoice, the email is the invoice: it names the invoice number, states `amountDue`, and attaches the PDF. Without one, it is a payment request for `amount` before VAT, and the invoice follows by email once the payer enters their billing details. Calling it again resends the email. One reminder follows a week after the latest email, unless the payer announced a transfer or started a payout. Payment is due on receipt. Allowed while `status` is `draft` or `open`. A counterparty payer without an email fails with `PAYER_EMAIL_MISSING`. Needs `payment-requests:write`.