Skip to main content

Create Payment Intent

POST 
/payment_intents

Approve a charge from your backend before any card is collected.

The intent locks the amount, currency, description and callback_url, and returns a client_secret that your frontend uses to fulfill it. A new intent is always created and expires one hour after creation.

This endpoint accepts the secret key only — that is what makes the intent an authorization your backend granted, rather than something the browser can mint on its own.

Request​

Body

required

    amount Amount (integer)required

    Possible values: >= 100

    A positive integer representing the payment amount in the smallest currency unit.

    Examples:

    • 1.00 SAR = 100
    • 1.00 KWD = 1000
    • 1 JPY = 1
    currency Currency (string)

    Default value: SAR

    ISO-4217 three-letter currency code.

    description string

    Possible values: <= 8000 characters

    Human readable description for the payment. This is shown to the merchant only and is not shown to the payer.

    callback_url uri

    A valid URL that is used to return the payer back to the merchant website after the payment is done.

    This field is required when the intent is fulfilled with a creditcard or token source.

Responses​

Successful operation

Schema

    id uuidrequired

    Unique identifier of the payment intent.

    amount Amount (integer)required

    Possible values: >= 100

    A positive integer representing the payment amount in the smallest currency unit.

    Examples:

    • 1.00 SAR = 100
    • 1.00 KWD = 1000
    • 1 JPY = 1
    currency Currency (string)required

    ISO-4217 three-letter currency code.

    description stringnullable
    callback_url urinullable
    status PaymentIntentStatus (string)required

    Possible values: [created, fulfilled, canceled]

    The intent's own lifecycle, not the payment's outcome.

    • created — awaiting fulfillment. Fulfillable until expires_at passes.
    • fulfilled — the intent was used to create a payment. Whether that payment was approved or declined is tracked on the payment, not here.
    • canceled — canceled before use; the client_secret no longer works.

    Expiry is not a status. An intent past its expires_at stays created but can no longer be fulfilled or canceled.

    client_secret ClientSecret (string)required

    Possible values: Value must match regular expression ^pi_secret_

    Single-use token that authorizes fulfillment of this intent. Pass it to your frontend and treat it as a credential — it is all a browser needs, alongside your publishable key, to create this one payment.

    expires_at date-timerequired

    Fulfillment deadline. Set automatically to one hour after creation.

    fulfilled_at date-timenullable

    Date and time when the intent was fulfilled. null until then.

    created_at date-timerequired
Loading...
Last updated on