Alternative payment methods (server version)

We recommend that you use our client API to support Alternative Payment Methods (APMs) but you can also access the relevant information on your server (to generate a web page with static APM links, say). See the client API page for a description of the asynchronous payment flow that APMs use.

Fetch a list of available APMs

The first step is to generate a list of available APMs for the user to choose from. The relevant information about the APMs is kept in the GatewayConfiguration objects that represent them. There are gateway configurations for all payment methods but you can filter the list to include only APMs, as shown in the example below. Once you have the list, you can iterate over it to present the options in any way you like. For example, on a web page, you might create a menu or a list of links for the APMs.

You will probably find it useful to expand the gateway field of the GatewayConfiguration objects when you list them because the Gateway object contains the APM’s name, logo and other details you might want to display.

You should design your UI to send the gateway configuration id field of the chosen APM back to your server. You will need this ID to redirect the customer to the APM’s payment page.

cURL Python Ruby PHP Go Node.js

curl https://api.processout.com/gateway-configurations?filter=alternative-payment-methods&expand_merchant_accounts=true \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB

client.newGatewayConfiguration().all({
    filter:                   "alternative-payment-methods",
    expand_merchant_accounts: true
}).then(function(confs) {
    // Iterate over the available confs and display them

}, function(err) {
    // An error occured

});

confs = client.new_gateway_configuration().create({
    "filter":                   "alternative-payment-methods",
    "expand_merchant_accounts": True
})
# Iterate over the available confs and display them

confs = client.gateway_configuration.new().all(
    filter:                   "alternative-payment-methods",
    expand_merchant_accounts: true
)
# Iterate over the available confs and display them

$confs = $client->newGatewayConfiguration()->all(array(
    "filter":                   "alternative-payment-methods",
    "expand_merchant_accounts": true
));
// Iterate over the available confs and display them

confs, err := client.NewGatewayConfiguration().All(processout.GatewayConfigurationAllParameters{
    ExpandMerchantAccounts: true,
    Options: &processout.Options{
        Filter: "alternative-payment-methods",
    },
})
if err != nil {
    panic(err)
}
// Iterate over the available confs and display them

Creating the invoice

You must include a return_url in your invoice as you would when you accept an APM payment with the client API (see the page for the client API to learn more about this). This is so that the APM’s page can redirect back to your app. However, on the server, you should also add a skip_processoutjs field to the invoice’s metadata, to avoid executing any redundant client-side JavaScript.

cURL Python Ruby PHP Go Node.js

curl https://api.processout.com/invoices \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB \
    -d name="Awesome invoice" \
    -d amount="9.99" \
    -d currency=USD \
    -d return_url="https://www.super-merchant.com/return" \
    -d metadata[skip_processoutjs]=true

client.newInvoice().create({
    name:       "Amazing item",
    amount:     "4.99",
    currency:   "USD",
    return_url: "https://www.super-merchant.com/return",
    metadata: {
      skip_processoutjs: "true"
    }
}).then(function(invoice) {
    //

}, function(err) {
    // An error occured

});

invoice = client.new_invoice().create({
    "name":       "Amazing item",
    "amount":     "4.99",
    "currency":   "USD",
    "return_url": "https://www.super-merchant.com/return",
    "metadata": {
      "skip_processoutjs": "true"
    }
})

invoice = client.invoice.create(
    name:       "Amazing item",
    amount:     "4.99",
    currency:   "USD",
    return_url: "https://www.super-merchant.com/return",
    metadata: {
      skip_processoutjs: "true"
    }
)

$invoice = $client->newInvoice()->create(array(
    "name"       => "Amazing item",
    "amount"     => "4.99",
    "currency"   => "USD",
    "return_url" => "https://www.super-merchant.com/return",
    "metadata": array(
      "skip_processoutjs" => "true"
    )
));

iv, err := client.NewInvoice().Create(processout.InvoiceCreateParameters{
    Invoice: &processout.Invoice{
        Name:      processout.String("Amazing item"),
        Amount:    processout.String("4.99"),
        Currency:  processout.String("USD"),
        ReturnURL: processout.String("https://www.super-merchant.com/return"),
        Metadata:  &map[string]string{
          "skip_processoutjs": "true",
        },
    },
})
if err != nil {
    panic(err)
}

Redirecting your customer to the APM

When you have the invoice ID and the chosen gateway configuration ID, you should redirect the customer to a special URL that passes them on to the APM page. This URL has the following format:

https://checkout.processout.com/<project_id>/<invoice_id>/redirect/<gateway_configuration_id>.apmname<?optional_parameters>

For example:

https://checkout.processout.com/test-proj_hgnt3R60AojpA3D4ZAFeYQuNRAtT1FDr/iv_ctBHCuUrbxfySdiivnJFdbZXuSaaeNyh/redirect/gway_conf_bqg2oivqet5d5rl7lm70fubyko6h7edk.adyenideal?additional_data[issuer_code]=1121

Capturing payment after the APM returns

After the customer has authenticated their payment on the APM page, they will be redirected back to the return_url you set in the invoice. This URL will have a GET parameter, which contains the payment token for the APM.

https://www.super-merchant.com/return?token=gway_req_V2UncmUgaGlyaW5nIQ==

You can then use the token to capture a payment on your server in the handler that is activated by this URL. From this point on, the capture process is exactly the same as for a card payment. See the page about capturing a payment for full details.