Server to Server: Hosted Payment Page

We recommend that you use our client SDKs 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 SDK 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 <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

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, it might look like this:

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

Redirecting your customer to the APM using a customer token

You can create a customer_token for APM transactions to re-use the payment method for multiple transactions. To learn more on APM tokenization and tokenized APM payments see Tokenizing Alternative Payment methods.

Some payment gateways require the customer to confirm the payment for Customer Initiated Transactions (CITs), even after having tokenized the customer details. To use a customer_token for these payments, you will have to build the URL in the following format:

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

An example URL would look like this:

Completing the payment when the customer 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 receive a POST parameter, which contains the payment token for the APM.

token=gway_req_V2UncmUgaGlyaW5nIQ==

From this point on, the payment process is similar to a card payment. You can use the token to capture the payment on your server in the handler that is activated by this URL. If the gateway supports authorizations, you can use the same token to authorize the payment before capturing it.

See the pages about authorizing a payment and capturing a payment for full details.