APM buttons

Sign in Hub
Get help
APM buttons
Add alternative payment method buttons to your payment form with customizable styling, placement, and method-specific display conditions

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

Button configuration is passed during Guide
Initialize the payment form by providing the init object and form parameters. form initialization alongside formParams. For Guide
Handle APM payment operations from initiation through settlement using consistent patterns for captures, refunds, and void actions. future payments, include future_usage in paymentIntent. Track lifecycle through payment form Guide
Subscribe to payment form lifecycle events to track user interactions, validate input, handle errors, and respond to payment completion. events.

When using init payment API , 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
anchor

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.

  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.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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 Guide
Subscribe to payment form lifecycle events to track user interactions, validate input, handle errors, and respond to payment completion. event to know when a button is rendered. Entity names follow bizumbtn , pixautomaticobtn , smartpixbtn , etc.


Method-specific configuration
anchor

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 is a Spanish peer-to-peer bank payment.

  • currency EUR
  • geo_country ESP
  • future_usage Required 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

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

  • currency PLN
  • geo_country POL 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

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

Cash App Pay is a US digital wallet.

  • currency USD
  • geo_country USA Required
  • future_usage Required
  • success_url Required
  • fail_url Required 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

MB WAY is a Portuguese mobile payment.

  • currency EUR
  • geo_country PRT
  • future_usage Required 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

PayPal is a worldwide multi-currency wallet checkout.

  • customer_email autogenerated if missing, confirmed on PayPal login
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

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 is a BCB-regulated recurring mandate in Brazil. The button initiates the mandate and first charge.

The mandate must follow allowed Guide
Allowed billing intervals for Pix Automático mandates per BCB rules. billing periods and respect the Guide
How max_amount and product_id define the per-charge authorization limit. 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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<div id="yourCustomContainerId"></div>
<script>
    PaymentFormSdk.init({
        ...restData,
        pixButtonParams: {
            enabled: true,
            containerId: 'yourCustomContainerId',
            resetEnabled: true
        }
    });
</script>
Looking for help? Contact us
Stay informed with Changelog