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