Help Center

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

1. Send an init payment request with the order, customer, and method details. Each method lists its required fields, such as a document number or a phone number, on its page in choose APM.
2. Show the customer the next step from the response: redirect to pay_form.return_url, load the payment button from pay_form.script_url, or display the payment details returned in payment_type_data.
3. Wait for the result. The order stays in processing until the customer completes the payment, and the final status arrives in the updated alternative order Webhook . The same event can arrive more than once, so process it idempotently.
4. If the payment is reused for later charges, store the token from the order and charge it with the recurring API v1 endpoint.

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

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 billing agreement.

Description

Defines the usage of stored payment credentials.

Should be provided either future_usage or product_id.

Example

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

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.

These requests succeed.

These requests are declined.