Alternative payment methods

ProcessOut lets you accept payments from alternative payment methods (APMs) as well as cards. These include well-known services like PayPal and also cryptocurrency systems such as CoinPayments.

Alternative payment methods flow

Card payment methods are generally synchronous, which means that you get confirmation of the success or failure of a payment directly after it happens. APMs, on the other hand, are generally asynchronous because they involve a redirection to the Payment Service Provider (PSP) web page from your own page or mobile app. As a result, the only way you can usually get confirmation of a successful payment is by listening for an update message from the PSP. This is inconvenient for the design of your app because it is harder to inform the customer of success within the normal payment flow.

ProcessOut processes APMs transactions by opening a new window for the payment page after redirection. When payment is complete, our code closes this window and returns the payment token to your original window or app screen using a callback function. This means that the structure of your code is very similar to the code you would use to handle a synchronous payment.

The following code sample demonstrates how the ProcessOut API passes control to the APM in a separate window and then regains control after the payment is complete. Note that the invoice ID used in the code is pre-generated on our server for demonstration purposes. The sections below explain how to create the invoice in your own code and accept payment on it.

<div class="container">
  <form action="" method="POST" id="apms-form">
    <div id="results">
      <div id="errors"></div>
      <div id="success"></div>
      <div id="loading">Loading...</div>
      <input id="success-token" class="hidden" />
    </div>
  </form>
</div>
/*! PocketGrid 1.1.0
* Copyright 2013 Arnaud Leray
* MIT License
*/
* {
  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
  font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
}

/* Clearfix */
.block-group {
  *zoom: 1;
}
.block-group:before, .block-group:after {
  display: table;
  content: "";
  line-height: 0;
}
.block-group:after {
  clear: both;
}

.block-group {
  /* ul/li compatibility */
  list-style-type: none;
  padding: 0;
  margin: 0;
}

/* Nested grid */
.block-group > .block-group {
  clear: none;
  float: left;
  margin: 0 !important;
}

/* Default block */
.block {
  float: left;
  width: 100%;
}
.b75 {
  width: 74%;
}
.b25 {
  width: 24%;
  margin-left: 2%;
}

html, body {
  background: #ECEFF1;
  font-size: 16px;
}

.container {
  width: 100%;
  max-width: 400px;
  background: white;
  margin: 3em auto;
  padding: 1em;
  border-radius: 4px;
  box-shadow: 0 5px 7px rgba(50, 50, 93, 0.04), 0 1px 3px rgba(0, 0, 0, 0.03);
}

input {
  border: 1px solid #ECEFF1;
  border-radius: 4px;
  box-shadow: 0 5px 7px rgba(50, 50, 93, 0.04), 0 1px 3px rgba(0, 0, 0, 0.03);
  padding: 0.5em;
  width: 100%;
  margin-bottom: 1em;
  font-size: 14px;
  min-height: 2em;
}

.button {
  margin: 0; margin-bottom: 1em;
  padding: 0.75em;
  text-align: center;
  box-shadow: 0 5px 7px rgba(50, 50, 93, 0.04), 0 1px 3px rgba(0, 0, 0, 0.03);
  background: #3F51B5;
  color: white;
  border-radius: 4px;
  border: 1px solid #303F9F;
  cursor: pointer;
}

.hidden {
  display: none;
}
#errors, #success, #loading {
  margin-bottom: 1em;
  text-align: center;
  font-size: 0.9em;
  color: #D84315;
}
#success {
  color: #4CAF50;
}
#loading {
  color: #bdc3c7;
}
document.addEventListener("DOMContentLoaded", function() {
  var client = new ProcessOut.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x");
  client.fetchGatewayConfigurations({
    invoiceID: "iv_tIWEiBcrXIFHzJeXcZzqyp8EpY0xwmuT",
    filter:    "alternative-payment-methods"
  }, processoutAPMsReady, function(err) {
    document.getElementById("loading").className = "hidden";
    document.getElementById("errors").innerHTML = "Woops, couldn't fetch APMs: "+err;
  });

  function processoutAPMsReady(confs) {
    document.getElementById("loading").className = "hidden";
    var formWrapper = document.getElementById("apms-form");
    for (var conf of confs) {
      var el = document.createElement("div");
      el.className = "button";
      el.innerHTML = "Pay with " + conf.gateway.display_name;

      conf.hookForInvoice(el, function(token) {
        document.getElementById("errors").innerHTML = "";
        document.getElementById("success").innerHTML = "Your user went through the entire APM payment flow. Use the token below to verify the payment in your backend.";
        document.getElementById("success-token").value = token;
        document.getElementById("success-token").className = "";
      }, function(err) {
        document.getElementById("errors").innerHTML = err.message;
        document.getElementById("success").innerHTML = "";
        document.getElementById("success-token").className = "hidden";
      });

      // Inject our APM element in the form
      formWrapper.appendChild(el);
    }
  }
});

Below is a sequence diagram that shows the flow for an APM. The following sectionsexplain the steps in more detail.

Creating the resources on your back-end to start a payment

As usual, you must create an invoice as the first step in receiving payment. The main difference with an APM-compatible invoice is the return_url field.

For mobile apps, this contains an iOS Universal Link or Android App Link or a deep link for the screen you want to return to after the APM payment page closes. You must provide the return_url to enable our code to pass control back to your app.

For in-browser payments, the return_url is optional. ProcessOut.js will trigger an event once the customer has returned from the APM site.

📘

Note

Some browsers such as Samsung Internet Browser and Facebook iOS browsers (eg, Messenger and Instagram) do not support redirection back to your web page after payment with an APM.

The code sample below shows how to create the Invoice with thereturn_url. See the page about setting up your environment to learn how to install our SDK for your language and access it using the client object.

curl https://api.processout.com/invoices \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB \
    -d name="Amazing item" \
    -d amount="9.99" \
    -d currency=USD \
    -d return_url="https://www.super-merchant.com/return" \
    # or, if you're integrating with a deep link on mobile:
    -d return_url="your.application.id://processout/return"
client.newInvoice().create({
    name:       "Amazing item",
    amount:     "4.99",
    currency:   "USD",
    return_url: "https://www.super-merchant.com/return",
    // Or, if you're integrating with a deep link on mobile:
    return_url: "your.application.id://processout/return"
}).then(function(invoice) {
    //

}, function(err) {
    // An error occurred
});
invoice = client.new_invoice().create({
    "name":       "Amazing item",
    "amount":     "4.99",
    "currency":   "USD",
    "return_url": "https://www.super-merchant.com/return",
    # Or, if you're integrating with a deep link on mobile:
    "return_url": "your.application.id://processout/return"
})
invoice = client.invoice.create(
    name:       "Amazing item",
    amount:     "4.99",
    currency:   "USD",
    return_url: "https://www.super-merchant.com/return",
    # Or, if you're integrating with a deep link on mobile:
    return_url: "your.application.id://processout/return"
)
$invoice = $client->newInvoice()->create(array(
    "name"       => "Amazing item",
    "amount"     => "4.99",
    "currency"   => "USD",
    "return_url" => "https://www.super-merchant.com/return",
    // Or, if you're integrating with a deep link on mobile:
    "return_url" => "your.application.id://processout/return",
));
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"),
        // Or, if you're integrating with a deep link on mobile:
        ReturnURL: processout.String("your.application.id://processout/return"),
    },
})
if err != nil {
    panic(err)
}

List the available APMs and redirect

You can have several APMs configured for use with ProcessOut at the same time (go to Dashboard › Payment providers to see the available APMs or configure new ones). However, this does not mean that all of them will be available for a particular purchase. For example, some APMs might not operate in every country. The ProcessOut API lets you find the set of APMs that are available for an invoice so that you can list them for your customer to choose from.

The code sample below shows how you can use ProcessOut.fetchGatewayConfigurations() to retrieve a list of available APMs for your invoice and use them to generate payment links (ProcessOut.shared.gatewayConfigurations.all() in iOS mobile SDK and ProcessOut.instance.gatewayConfigurations.fetch() in Android mobile SDK). The callback function (eg, the parameter supplied to client.handleInvoiceActionAdditionalData() in the web version) receives the token that the APM payment generates. You should send this back to your server for capture within the callback.

client.fetchGatewayConfigurations({
  invoiceID: "iv_tIWEiBcrXIFHzJeXcZzqyp8EpY0xwmuT",
  filter:    "alternative-payment-methods"
}, processoutAPMsReady, function(err) {
  console.log("Woops, couldn't fetch APMs: "+err);
});

var configFunctions = [];

function createHandler(i, conf) {
    return function() {
      client.handleInvoiceActionAdditionalData(
        invoiceId,
        conf,
        {"issuer_country": "BE"},
        function(token) {
          // The customer completed the gateway tokenization flow.
          // We can send the token back to our backend to finish the flow
          document.getElementById("success").innerHTML = "Success! Token "+token+" on customer "+document.getElementById('customer-id').value;
        }, function(err) {
          // An error occured during tokenization. This could just be the
          // customer that canceled the tokenization, or an error with
          // the payment gateway.
          document.getElementById("errors").innerHTML = err.message;
        });
    };
  };

function processoutAPMsReady(confs) {
  var formWrapper = document.getElementById("apms-payment-form");
  var elements = [];
  for (var i = 0; i < confs.length; i++) {
    var el = document.createElement("div");
    el.className = "my-apm-link";
    el.innerHTML = "Pay with " + confs[i].gateway.display_name;

    configFunctions[i] = createHandler(i, confs[i]);

    // Inject our APM element in the form
    formWrapper.appendChild(el);

    elements[i] = el;
  }
  for (var i = 0; i < confs.length; i++) {
    (function () {
      var k = i;
      elements[k].addEventListener("click", function() {
        configFunctions[k]();
      });
    }());
  }
}
// 1. List all the available APMs. You could do as proposed below or
//    you can communicate with our API directly from your backend.
let gatewayConfigurationsRequest = POAllGatewayConfigurationsRequest(
    filter: .alternativePaymentMethods
)
let gatewayConfigurations = try await ProcessOut.shared
    .gatewayConfigurations
    .all(request: gatewayConfigurationsRequest)
    .gatewayConfigurations

// 2. Once the user chooses the needed configuration, create a
//    POAlternativePaymentMethodRequest and use
//    POAlternativePaymentMethodViewControllerBuilder to create
//    a view controller that can handle the UI.
let alternativePaymentRequest = POAlternativePaymentMethodRequest(
    invoiceId: "iv_tIWEiBcrXIFHzJeXcZzqyp8EpY0xwmuT",
    gatewayConfigurationId: gatewayConfigurations.first!.id
)

// 3. Create a view controller and present it in any way.
let viewController = POAlternativePaymentMethodViewControllerBuilder()
    .with(returnUrl: ...) // Same return URL that is set in the invoice.
    .with(request: alternativePaymentRequest)
    .with(completion: { result in
        // 4. Dismiss view controller.
        // 5. Finish the charge on your backend with result.gatewayToken
        //    in case of success.
    })
    .build()
// 1. Initialize a Custom Chrome Tabs launcher in the onCreate() method of
//    your Activity or Fragment to register a callback.
private lateinit var customTabLauncher: POAlternativePaymentMethodCustomTabLauncher

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    customTabLauncher = POAlternativePaymentMethodCustomTabLauncher.create(from = this) { result ->
        when (result) {
            is ProcessOutResult.Success -> TODO() // 5. Finish the charge on your backend with
                                                  //    result.value.gatewayToken.
            is ProcessOutResult.Failure -> TODO()
        }
    }
}

// 2. List all the available APMs. You could do as shown below or
//    you can communicate with the ProcessOut API directly from your
//    backend.
val gatewayConfigurationsRequest = POAllGatewayConfigurationsRequest(
    filter = Filter.ALTERNATIVE_PAYMENT_METHODS
)
ProcessOut.instance.gatewayConfigurations.fetch(gatewayConfigurationsRequest).let { result ->
    when (result) {
        is ProcessOutResult.Success -> result.value.gatewayConfigurations
        is ProcessOutResult.Failure -> result.code
    }
}

// 3. Once the user chooses the needed configuration, create a POAlternativePaymentMethodRequest.
val alternativePaymentRequest = POAlternativePaymentMethodRequest(
    invoiceId = "iv_tIWEiBcrXIFHzJeXcZzqyp8EpY0xwmuT",
    gatewayConfigurationId = gatewayConfigurations.first().id
)

// 4. Launch the activity.
customTabLauncher.launch(
    request = alternativePaymentRequest,
    returnUrl = "your.application.id://processout/return"
)

Handle the capture on the server

The callback for the APM response described above should send the new token back to the server along with the invoice ID. After this point, the process that you use to capture the payment on the server is exactly the same as the process for a card payment. See the page about capturing a payment for a full description.


What’s Next