Initiate APM

Initiation is the first request of every alternative payment. It creates the order and returns what the customer needs to pay: a link to the method’s payment page, a payment-button script, or payment details such as a QR code, voucher, or deep link.

Use this page to choose the request that fits the sale, prepare the fields each method needs, and decide whether to reuse the payment for later charges.

How initiation works

Request types

Choose the request by where the price comes from. All three use the same endpoint, and payment_method selects the method.

Product-based and subscription requests do not take an amount. The billing plan comes from the product, so do not send future_usage.billing_period with a product for Klarna, Pix Automático, or UPI, or future_usage.billing_amount for Klarna. For Pix Automático and UPI subscription requests, billing_period results in a validation error. future_usage.max_amount stays optional and sets a custom authorization ceiling.

Init future payment

Guide
Understand APM categories, subtypes, payment flows, and billing logics before you compare methods in Choose APM. Billing logic defines who initiates a payment and whether the customer is present: a single purchase (one-time), a later purchase the customer starts without entering details again (1-click), charges on a fixed schedule (recurring), or charges you start when needed (unscheduled).

Payment type is the API value in future_usage.payment_type . The value can differ from the billing-logic label. unscheduled is a superset of Unscheduled, Recurring, and 1-click when the provider does not restrict token use. When a method supports both a native type and unscheduled , send the native type.

PayPal does not use future_usage. It stores a reusable token through a Guide
A billing agreement lets you charge the customer's PayPal account later without a new login for each follow-up payment. billing agreement.

API

Init payment API v1 , create page API v1 , create link API v1 or init payment form Guide with future_usage object
Use this flow to define intent for subsequent use of the customer's payment credentials, token-based future charges.
It ensures compliance with scheme rules, reduces declines on future payments, and improves success rates.

future_usage

object

Required

Description

Defines the usage of stored payment credentials.

Should be provided either future_usage or product_id.

Example

1 2 3 4 5

{ "future_usage": { "payment_type": "recurring" } }

payment_type

string

Required

Description

Type of the token usage scenario.

• one-time no token created, for one-off use.
  Maps only to One-time billing logic.
• 1-click token for future customer-initiated payments without re-entering details.
  Maps only to 1-click billing logic.
• recurring token for fixed scheduled merchant-initiated charges, for subscriptions.
  Maps only to Recurring billing logic.
• unscheduled token for unscheduled or variable merchant-initiated charges, for auto-top-up.
  Maps to Unscheduled, Recurring, and 1-click when the provider does not restrict token use.

Billing period and amount ceiling

Methods that keep a mandate limit how often and how much you can charge. Set these limits in the first request, or in the Solidgate product for product-based and subscription requests. The method page holds the full rules.

Init future payment calculation

Send at least payment_type or product_id. If only product_id is sent, the intent is the product type. Compatible requests use payment_type when it is present.