Create Payment Intent

Once you have an access token, create a payment intent. Forte returns the data needed to initialize the payment widget or redirect the user to a hosted payment page.

Endpoint

Buyers are purchasing a non-tokenized (off-chain) asset that will be delivered by you (after receiving confirmation via Forte Webhook), directly into their game account.

POST /payments/v2/intent
Authorization: Bearer {{access_token}}

Request Body

You must include either buyer.email or buyer.wallet (or both). Use the same identifier format consistently for a given user across all payment sessions.

{
  "transaction_type": "BUY_VDA",
  "buyer": {
    "email": "user@example.com",
    "id": "your-internal-user-id"
  },
  "currency": "USD",
  "idempotency_key": "unique-string-per-attempt",
  "reference": "your-internal-transaction-id",
  "items": [
    {
      "id": "item-id-in-your-system",
      "title": "1,000 Gold Coins",
      "description": "Bundle of Gold",
      "amount": "9.99",
      "image_url": "https://yourgame.com/items/gold-coins.png"
    }
  ]
}

Include a unique idempotency_key per payment attempt to prevent duplicate processing if a request is retried.

The optional reference field accepts a string up to 100 characters (a UUID works well). Pass your own transaction or order ID here and Forte will echo it back in all webhooks for that payment, making reconciliation straightforward without needing to map Forte’s payment_intent_id to your own records.

Response

A 201 response indicates the intent was created successfully.

{
  "data": {
    "flow": "PAYMENT",
    "error_code": null,
    "payment_intent_id": "440b0e4e-ae70-4886-ad6b-1521cc22cbca",
    "widget_data": "eyJhY2Nlc3NfdG9rZW4i...",
    "notes": []
  }
}

Handle both status codes

Status	Meaning
`201`	Intent created. Use `payment_intent_id` to track webhooks.
`200`	Request succeeded but no intent was created (e.g. user is banned or sanctioned). Initialize the widget anyway — it will display the appropriate message. No `payment_intent_id` is returned.

Pass the full data object to initFortePaymentsWidget — see Integrate Widget.

Redirect Mode

Use redirect mode to send users to a Forte-hosted payment page instead of embedding the widget directly.

Endpoint

POST /payments/v2/intent/redirect
Authorization: Bearer {{access_token}}

The request body is identical to widget mode above.

Response

{
  "data": {
    "redirect_url": "https://payments.forte.io/0f7660c1-a106-481f-acf9-1848e98a7230?redirect_token=eyJhbGci..."
  }
}

Redirect the user’s browser to the redirect_url.

The redirect URL is valid for 30 seconds and can only be accessed once. If the user revisits the same URL, they will see a 401 authentication error.

Client-side widget events are not available in redirect mode. Use webhooks to track payment status in both modes.

Error Codes

If error_code is non-null in the response, the widget will display the appropriate message to the user automatically. Common codes:

Code	Meaning
`ERR01`	Customer is banned
`ERR03`	Request originates from a sanctioned country
`ERR06`	Customer must complete KYC — widget will display the KYC gate
`ERR15`	Customer’s wallet address is flagged (KYW check failed)

Next Steps

Integrate Widget

Embed and initialize the Forte Payments widget with the response data

Get Started

Integration Guide

Forte Payments

Forte Compliance

Create Payment Intent

Widget Mode

Endpoint

Request Body

Response

Redirect Mode

Endpoint

Response

Error Codes

Next Steps

Integrate Widget

​Widget Mode

​Endpoint

​Request Body

​Response

​Redirect Mode

​Endpoint

​Response

​Error Codes

​Next Steps

Integrate Widget

Widget Mode

Endpoint

Request Body

Response

Redirect Mode

Endpoint

Response

Error Codes

Next Steps