Skip to main content
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.

​
Widget Mode

​
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",
  "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.

​
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
StatusMeaning
201Intent created. Use payment_intent_id to track webhooks.
200Request 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:
CodeMeaning
ERR01Customer is banned
ERR03Request originates from a sanctioned country
ERR06Customer must complete KYC — widget will display the KYC gate
ERR15Customer’s wallet address is flagged (KYW check failed)

​
Next Steps

Integrate Widget

Embed and initialize the Forte Payments widget with the response data