Alternative payment method buttons expand your payment options and increase conversion by offering familiar, secure checkouts.

Button configuration is passed during form initialization alongside formParams. For future payments, include future_usage in paymentIntent. Track lifecycle through payment form events.

When using init payment API v1 , do not create multiple buttons with the same order_id at once. If you are already using a host-to-host APM button, disable it so orders are created and processed automatically by the payment form.

If you have not set up an APM button for your channels, contact us.


Setup workflow

Every APM button follows the same three-step setup.

  1. Configure the payment method.
  2. Build the paymentIntent with the fields below. Add method-specific objects from your method tab.
Choose your payment scenario to see the fields it requires. Payment amount integer >=0 Required

Description

Order amount in minor units. For example, 1020 means 10 EUR and 20 cents.

Example

1020

Product-based payment product_id string 36 Required

Description

Identifier of the predefined product in UUID v4 format.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

customer_account_id string 100 Required

Description

Customer ID in the merchant’s system.

Example

4dad42f878

Subscription payment product_price_id string 36 Required

Description

Price ID of the predefined product. Use get product prices to obtain it.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

customer_account_id string 100 Required

Description

Customer ID in the merchant’s system.

Example

4dad42f878

order_id string 255 Required

Description

Order ID, which must be unique, is specified in the merchant system.

Example

123456

currency string 3 Required

Description

Currency in three-letter code per the ISO-4217 Wiki standard. Each APM enforces its own supported currency. See the method tab below.

Example

EUR

order_description string 255 Required

Description

Order description in your system and for bank processing.

Highly recommended to keep the description brief to improve the clarity of payment processing, ideally not exceeding 100 characters. It is used in the email receipt sent to the customer.

Example

Premium package

future_usage object Required*

Description

Defines the usage of stored payment credentials.

Required for Bizum, Cash App Pay, MB WAY, Pix Automático. payment_type string Required

Description

Type of the token usage scenario.

  • one-time no token created, for one-off use
  • recurring creates a recurring mandate

Example

one-time

billing_period object Required*

Description

Defines the interval for recurring charges.

Required for Pix Automático. unit string Required

Description

Billing interval unit for Pix Automático recurring charges.

Allowed values:

  • day
  • week
  • month
  • year

Example

month

value integer Required

Description

Billing interval value for the selected

unit .

Only these unit + value pairs are allowed:

  • day + 7
  • week + 1
  • month + 1, 3, 6, 12
  • year + 1

Example

1

max_amount integer Required*

Description

Maximum allowed amount in minor units for each recurring charge.

Required for Pix Automático.

Example

10000

payment_type_data object

Description

Additional customer data to process payments in specific locations.

Required for Pix QR, Pix Automático, SmartPix. brazil_cpf numeric [0-9]{11}

Description

CPF (Cadastro de Pessoas Físicas) Brazilian individual taxpayer registry identification.

The last two digits are verifiers. If not provided, it is collected on the payment form.

Example

12345678901

customer_email string 100

Description

Customer email.

If not provided, it is collected on the payment form.

For PayPal, an autogenerated email may initialize the order, which the customer enters while logging into their PayPal account.

Example

test@solidgate.com

customer_first_name string 100

Description

Customer’s first name.

Example

John

customer_last_name string 100

Description

Customer’s last name.

Example

Snow

customer_phone string 18

Description

Customer’s phone number.

Should be provided in international format E.164 Wiki , starting with the plus + sign.

Recommended format ^\+[1-9]\d{1,14}$

Example

+34911012345

ip_address string 50

Description

Public IP address of the customer. Both IPv4 and IPv6 are supported.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) result in an ‘Invalid IP’ error.

Example

8.8.8.8

geo_country string 3

Description

Customer country subject to ISO-3166 Wiki alpha-3.

Recommended for region-locked APMs. Expected codes are listed in each method tab.

Example

ESP

platform string 3

Description

Customer platform at the moment of payment.

  • WEB - desktop
  • MOB - mobile version
  • APP - application
If this parameter is not provided, it is automatically inferred from the header.

Example

WEB

language string [2..3]

Description

Customer language settings for the translation of Payment Form fields and the language of email receipts sent for successful payments.

Example

en

retry_attempt integer >=0

Description

Number of payment retries.

Should be provided for the subscription workflow.

Example

1

order_metadata object

Description

Metadata is useful for storing additional, structured information about an object, consisting of up to 10 key-value pairs with a validation limit of 380 characters per field.

The callback notification returns an order_metadata from the order in each state.

Example

{"coupon_code": "NY2025", "partner_id": "123989"}

success_url string 255

Description

Provide this URL if you want to redirect a customer to your own Success Screen.

Without it, Solidgate uses the default Success Screen.

Example

https://merchant.example/success

fail_url string 255

Description

Provide this URL if you want to redirect a customer to your own Fail Screen.

Without it, Solidgate uses the default Fail Screen.

Example

https://merchant.example/fail


  1. Pass the method params object to PaymentFormSdk.init with enabled true . Without containerId, the button renders above the form. A non-existent containerId produces a console error.
PaymentFormSdk.init template 
const data = {
  merchantData: {
    merchant: "<-your data->",
    signature: "<-your data->",
    paymentIntent: "<-your data->",
  },
  // Replace with your method's params object: bizumButtonParams, blikButtonParams,
  // cashAppButtonParams, mbwayButtonParams, paypalButtonParams,
  // pixAutomaticoButtonParams, pixQrButtonParams, or pixButtonParams (SmartPix).
  bizumButtonParams: {
    enabled: true,
    containerId: "your-custom-container-id"
  }
};

let form = PaymentFormSdk.init(data);

Subscribe to the mounted event to know when a button is rendered. Entity names follow bizumbtn , pixautomaticobtn , smartpixbtn , etc.


Method-specific configuration

Select your APM to see its paymentIntent payload, button params, and init snippet.

DISPLAYED BY DEFAULT Bizum · Cash App Pay · PayPal · SmartPix OPT-IN REQUIRED  ·  enabled true Blik · MB WAY · Pix Automático · Pix QR Bizum

Bizum is a Spanish peer-to-peer bank payment.

  • currency EUR
  • geo_country ESP
  • future_usage Required
One-time 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "EUR",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "one-time"
  },
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+34911012345",
  "ip_address": "8.8.8.8",
  "geo_country": "ESP",
  "platform": "WEB",
  "language": "es",
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
Recurring 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "EUR",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "recurring",
    "billing_period": {
      "unit": "month",
      "value": 1
    }
  },
  "customer_account_id": "4dad42f808",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+34911012345",
  "ip_address": "8.8.8.8",
  "geo_country": "ESP",
  "platform": "WEB",
  "language": "es",
  "retry_attempt": 1,
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
enabled boolean

Description

Displays the Bizum button.

Pass this field with false to hide the Bizum button.

Default

true

Example

false

containerId string

Description

Identifier of the container where the Bizum button is placed.

Default

Button is displayed above the form.

Example

bizum-button-container

PaymentFormSdk.init 
<div id="yourCustomContainerId"></div>
<script>
    PaymentFormSdk.init({
        ...restData,
        bizumButtonParams: {
            enabled: true,
            containerId: 'yourCustomContainerId'
        }
    });
</script>
Blik

Blik is a Polish mobile payment with one-time authorization codes.

  • currency PLN
  • geo_country POL
One-time 
{
  "order_id": "123456",
  "amount": 5000,
  "currency": "PLN",
  "order_description": "Premium package",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "ip_address": "8.8.8.8",
  "geo_country": "POL",
  "platform": "WEB",
  "language": "pl",
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
enabled boolean

Description

Displays the Blik button.

If you do not pass this field with true , the Blik button is hidden.

Default

false

Example

true

containerId string

Description

Identifier of the container where the Blik button is placed.

Default

Button is displayed above the form.

Example

blik-button-container

theme string

Description

Theme of the Blik button.

  • light
  • dark

Default

dark

Example

light

resetEnabled boolean

Description

When true, the modal’s close “✕” button remains visible after the form is submitted. Clicking it emits a

resetRequested event.

When false or omitted, the close “✕” button is hidden once the form is submitted.

Default

false

Example

true

PaymentFormSdk.init 
<div id="yourCustomContainerId"></div>
<script>
    PaymentFormSdk.init({
        ...restData,
        blikButtonParams: {
            enabled: true,
            containerId: 'yourCustomContainerId',
            theme: 'light',
            resetEnabled: true
        }
    });
</script>
Cash App Pay

Cash App Pay is a US digital wallet.

  • currency USD
  • geo_country USA Required
  • future_usage Required
  • success_url Required
  • fail_url Required
One-time 
{
  "order_id": "123456",
  "amount": 2500,
  "currency": "USD",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "one-time"
  },
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
Recurring 
{
  "order_id": "123456",
  "amount": 2500,
  "currency": "USD",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "recurring"
  },
  "customer_account_id": "4dad42f808",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "retry_attempt": 1,
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
enabled boolean

Description

Displays the Cash App Pay button.

Pass this field with false to hide the Cash App Pay button.

Default

true

Example

false

containerId string

Description

Identifier of the container where the Cash App Pay button is placed.

Default

Button is displayed above the form.

Example

cashapp-button-container

PaymentFormSdk.init 
<div id="yourCustomContainerId"></div>
<script>
    PaymentFormSdk.init({
        ...restData,
        cashAppButtonParams: {
            enabled: true,
            containerId: 'yourCustomContainerId'
        }
    });
</script>
MB WAY

MB WAY is a Portuguese mobile payment.

  • currency EUR
  • geo_country PRT
  • future_usage Required
One-time 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "EUR",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "one-time"
  },
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+351912345678",
  "ip_address": "8.8.8.8",
  "geo_country": "PRT",
  "platform": "WEB",
  "language": "pt",
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
Recurring 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "EUR",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "recurring"
  },
  "customer_account_id": "4dad42f808",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+351912345678",
  "ip_address": "8.8.8.8",
  "geo_country": "PRT",
  "platform": "WEB",
  "language": "pt",
  "retry_attempt": 1,
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
enabled boolean

Description

Displays the MB WAY button.

If you do not pass this field with true , the MB WAY button is hidden.

Default

false

Example

true

containerId string

Description

Identifier of the container where the MB WAY button is placed.

Default

Button is displayed above the form.

Example

mbway-button-container

PaymentFormSdk.init 
<div id="yourCustomContainerId"></div>
<script>
    PaymentFormSdk.init({
        ...restData,
        mbwayButtonParams: {
            enabled: true,
            containerId: 'yourCustomContainerId'
        }
    });
</script>
PayPal

PayPal is a worldwide multi-currency wallet checkout.

  • customer_email autogenerated if missing, confirmed on PayPal login
One-time 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "USD",
  "order_description": "Premium package",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
Subscription 
{
  "order_id": "123456",
  "product_price_id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
  "customer_account_id": "4dad42f808",
  "currency": "USD",
  "order_description": "Premium package",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "retry_attempt": 1,
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
enabled boolean

Description

Displays the PayPal button.

Pass this field with false to hide the PayPal button.

Default

true

Example

false

containerId string

Description

Identifier of the container where the PayPal button is placed.

Default

Button is displayed above the form.

Example

paypal-button-container

color string

Description

Color Reference of the PayPal button.

  • gold
  • blue
  • silver
  • white
  • black

Default

gold

Example

blue

shape string

Description

Shape Reference of the PayPal button.

  • rect
  • pill
  • sharp

Default

pill

Example

sharp

label string

Description

Label Reference displayed on the PayPal button.

  • paypal
  • checkout
  • buynow
  • pay

Default

buynow

Example

checkout

height string [25..55]

Description

Height Reference of the PayPal button.

Default

Button adapts to the size of its container element.

Example

52

disableMaxWidth boolean

Description

Removes the default maximum width constraint of 750px, allowing the PayPal button to expand to the full width of its container.

Default

false

Example

true

PaymentFormSdk.init 
const data = {
  merchantData: {
    merchant: "<-your data->",
    signature: "<-your data->",
    paymentIntent: "<-your data->",
  },
  paypalButtonParams: {
    enabled: true,
    color: "blue",
    shape: "rect",
    label: "checkout",
    height: 52,
    disableMaxWidth: true
  }
};

let form = PaymentFormSdk.init(data);
Pix Automático

Pix Automático is a BCB-regulated recurring mandate in Brazil. The button initiates the mandate and first charge.

The mandate must follow allowed billing periods and respect the authorization ceiling set by future_usage max_amount and product_id .

  • currency BRL
  • geo_country BRA
  • future_usage payment_type recurring Required
  • future_usage max_amount Required
  • future_usage billing_period Required
  • payment_type_data brazil_cpf collected on form if missing
Recurring 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "BRL",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "recurring",
    "max_amount": 10000,
    "billing_period": {
      "unit": "month",
      "value": 1
    }
  },
  "customer_account_id": "4dad42f808",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+5511987654321",
  "ip_address": "8.8.8.8",
  "geo_country": "BRA",
  "platform": "WEB",
  "language": "pt",
  "retry_attempt": 1,
  "payment_type_data": {
    "brazil_cpf": "12345678901"
  },
  "order_metadata": {
    "campaign": "pix_automatico_launch",
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
Subscription 
{
  "order_id": "123456",
  "product_id": "47f95c95-3647-4c5b-ae6d-40fd8d3ac742",
  "customer_account_id": "4dad42f808",
  "currency": "BRL",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "recurring",
    "max_amount": 10000
  },
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+5511987654321",
  "ip_address": "8.8.8.8",
  "geo_country": "BRA",
  "platform": "WEB",
  "language": "pt",
  "retry_attempt": 1,
  "payment_type_data": {
    "brazil_cpf": "12345678901"
  },
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
enabled boolean

Description

Displays the Pix Automático button.

If you do not pass this field with true , the Pix Automático button is hidden.

Default

false

Example

true

containerId string

Description

Identifier of the container where the Pix Automático button is placed.

Default

Button is displayed above the form.

Example

pix-automatico-button-container

resetEnabled boolean

Description

When true, the modal’s close “✕” button remains visible after the form is submitted. Clicking it emits a

resetRequested event.

When false or omitted, the close “✕” button is hidden once the form is submitted.

Default

false

Example

true

PaymentFormSdk.init 
<div id="yourCustomContainerId"></div>
<script>
    PaymentFormSdk.init({
        ...restData,
        pixAutomaticoButtonParams: {
            enabled: true,
            containerId: 'yourCustomContainerId',
            resetEnabled: true
        }
    });
</script>
Pix QR

Pix QR is a single-use Brazilian payment. Solidgate returns a QR code that the customer scans in their banking app.

  • currency BRL
  • geo_country BRA
  • payment_type_data brazil_cpf collected on form if missing
One-time 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "BRL",
  "order_description": "Premium package",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+5511987654321",
  "ip_address": "8.8.8.8",
  "geo_country": "BRA",
  "platform": "WEB",
  "language": "pt",
  "payment_type_data": {
    "brazil_cpf": "12345678901"
  },
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
enabled boolean

Description

Displays the Pix QR button.

If you do not pass this field with true , the Pix QR button is hidden.

Default

false

Example

true

containerId string

Description

Identifier of the container where the Pix QR button is placed.

Default

Button is displayed above the form.

Example

pix-qr-button-container

resetEnabled boolean

Description

When true, the modal’s close “✕” button remains visible after the form is submitted. Clicking it emits a

resetRequested event.

When false or omitted, the close “✕” button is hidden once the form is submitted.

Default

false

Example

true

PaymentFormSdk.init 
<div id="yourCustomContainerId"></div>
<script>
    PaymentFormSdk.init({
        ...restData,
        pixQrButtonParams: {
            enabled: true,
            containerId: 'yourCustomContainerId',
            resetEnabled: true
        }
    });
</script>
SmartPix

SmartPix collects one-time or recurring Brazilian payments via Open Finance bank connections.

  • currency BRL
  • geo_country BRA
  • payment_type_data brazil_cpf collected on form if missing
One-time 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "BRL",
  "order_description": "Premium package",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+5511987654321",
  "ip_address": "8.8.8.8",
  "geo_country": "BRA",
  "platform": "WEB",
  "language": "pt",
  "payment_type_data": {
    "brazil_cpf": "12345678901"
  },
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
Recurring 
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "BRL",
  "order_description": "Premium package",
  "future_usage": {
    "payment_type": "recurring"
  },
  "customer_account_id": "4dad42f808",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+5511987654321",
  "ip_address": "8.8.8.8",
  "geo_country": "BRA",
  "platform": "WEB",
  "language": "pt",
  "retry_attempt": 1,
  "payment_type_data": {
    "brazil_cpf": "12345678901"
  },
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
enabled boolean

Description

Displays the SmartPix button.

Pass this field with false to hide the SmartPix button.

Default

true

Example

false

containerId string

Description

Identifier of the container where the SmartPix button is placed.

Default

Button is displayed above the form.

Example

pix-button-container

resetEnabled boolean

Description

When true, the modal’s close “✕” button remains visible after the form is submitted. Clicking it emits a

resetRequested event.

When false or omitted, the close “✕” button is hidden once the form is submitted.

Default

false

Example

true

PaymentFormSdk.init 
<div id="yourCustomContainerId"></div>
<script>
    PaymentFormSdk.init({
        ...restData,
        pixButtonParams: {
            enabled: true,
            containerId: 'yourCustomContainerId',
            resetEnabled: true
        }
    });
</script>