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