Skip to main content
POST
/
v1
/
entitlements
/
{entitlementId}
/
grants
/
purchase
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
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API key authentication

Path Parameters

​
entitlementId
string
required

The unique identifier of the entitlement

Pattern: ^ent_[a-zA-Z0-9]+$

Body

application/json
​
amount
number
required

The number of credits to grant upon payment completion.

​
price
string
required

The price in decimal format (e.g., '5.00' for $5.00 USD). Must be at least $0.50.

​
idempotencyKey
string
required

Caller-provided deduplication key. Retrying with the same key returns the existing invoice.

Required string length: 1 - 255
​
effectiveAt
string<date-time>

When the grant becomes effective. Defaults to now.

​
expiresAt
string<date-time> | null

When the grant expires. If omitted, the grant does not expire.

​
successUrl
string<uri>

URL to redirect the customer to after successful payment.

​
cancelUrl
string<uri>

URL to redirect the customer to if payment is cancelled.

​
paymentExpiresAt
string<date-time>

When the payment session expires. If omitted, uses the default expiry.

Response

Grant purchase invoice created with payment session.

​
object
enum<string>
default:grant_purchase
required
Available options:
grant_purchase
​
invoiceId
string
required

The invoice ID for this grant purchase.

Pattern: ^inv_[a-f0-9]+$
​
entitlementId
string
required

The entitlement that will receive the grant.

Pattern: ^ent_[a-zA-Z0-9]+$
​
grantAmount
integer
required

The number of credits that will be granted on payment.

​
price
string
required

The price in decimal format (e.g., '5.00').

​
currency
string
required

The three-letter ISO 4217 currency code (e.g., 'usd').

​
paymentSessions
object[]
required

Payment session(s) for the customer to complete the purchase.