curl --request POST \
--url https://api.paygentic.io/v1/entitlements/{entitlementId}/grants/purchase \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 1000,
"price": "5.00",
"idempotencyKey": "purchase-march-2026-topup"
}
'{
"object": "grant_purchase",
"invoiceId": "<string>",
"entitlementId": "<string>",
"grantAmount": 123,
"price": "<string>",
"currency": "<string>",
"paymentSessions": [
{
"url": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"amount": 123
}
]
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}Purchase Grant
Create an ad-hoc invoice with a payment session for a grant purchase. The customer pays via the returned payment URL; the grant is created automatically on payment completion. If payment expires, the invoice is cancelled and no grant is created.
To confirm payment completion, subscribe to the invoice.paid.v0 webhook. The payload includes the original invoiceId and the created grantId, so you can correlate the purchase response with downstream fulfilment without an extra fetch. As a fallback if you cannot consume webhooks, poll GET /v2/invoices/{invoiceId} (interval 2s, timeout 60s) and check for status === "PAID".
curl --request POST \
--url https://api.paygentic.io/v1/entitlements/{entitlementId}/grants/purchase \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 1000,
"price": "5.00",
"idempotencyKey": "purchase-march-2026-topup"
}
'{
"object": "grant_purchase",
"invoiceId": "<string>",
"entitlementId": "<string>",
"grantAmount": 123,
"price": "<string>",
"currency": "<string>",
"paymentSessions": [
{
"url": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"amount": 123
}
]
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}Authorizations
API key authentication
Path Parameters
The unique identifier of the entitlement to purchase credits for.
^ent_[a-zA-Z0-9]+$Body
The number of credits to grant upon payment completion.
1e-8The price in decimal format (e.g., '5.00' for $5.00 USD). A non-negative decimal with at most 9 fractional digits (nanodollar precision). Must be at least $0.50 and must not exceed 4503599.62 (the maximum supported grant purchase amount).
^\d+(\.\d{1,9})?$Caller-provided deduplication key. Retrying with the same key returns the existing invoice.
1 - 255When the grant becomes effective. Defaults to now.
When the grant expires. If omitted, the grant does not expire.
URL to redirect the customer to after successful payment.
URL to redirect the customer to if payment is cancelled.
When the payment session expires. If omitted, uses the default expiry.
Maximum balance carried over at the entitlement's reset boundary. If omitted, the purchased grant balance rolls over until consumed or expired. Set to 0 to discard any remaining balance at each reset. Ignored when the target entitlement has no usagePeriod (one-time entitlement) — one-time entitlements have no reset boundary, so this field has no effect.
0 <= x <= 999999999999Minimum balance at the entitlement's reset boundary; balances below this are floored up. Defaults to 0 (no floor). Ignored when the target entitlement has no usagePeriod (one-time entitlement).
0 <= x <= 999999999999Response
Grant purchase invoice created with payment session.
grant_purchase The invoice ID for this grant purchase.
^inv_[a-f0-9]+$The entitlement that will receive the grant.
^ent_[a-zA-Z0-9]+$The number of credits that will be granted on payment.
The price in decimal format (e.g., '5.00').
The three-letter ISO 4217 currency code (e.g., 'usd').
Payment session(s) for the customer to complete the purchase.
Show child attributes
Show child attributes
Was this page helpful?