Payment Methods

Our API allows merchants to process and manage transactions for alternative payment methods (PMs).

To browse all the alternative PMs we support, see Supported Payment Methods.

For more information on alternative payment methods, see our main article.

This is a mandatory request used to initiate a alternative PM transaction. It’s used to advise the payment method of the details of a new transaction and to retrieve the necessary information required to facilitate authentication.

The request must contain the following URLs, which need to be set up in your application or website:

• Return URL - The endpoint to which the customer should be redirected after a payment was attempted or successfully completed on the payment method's site.
• Status URL - The endpoint that receives payment-status messages. This includes the result of the transaction or any updates to the transaction status. For certain asynchronous PMs, these notifications may come hours or days after the initial authorization.

The other standard integration elements for alternative PMs are:

• Payment Method
• Descriptor
• Country Code
• Account Holder Name

First, we set up a SOFORT transaction. The response will contain the URL the customer must be redirected to in order to authenticate and authorize the transaction.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="payment-set" timestamp="20180613173251">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <amount currency="EUR">1001</amount>
  <autosettle flag="1"/>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <paymentmethod>sofort</paymentmethod>
  <paymentmethoddetails>
    <returnurl>https://www.example.com/returnUrl</returnurl>
    <statusupdateurl>https://www.example.com/statusUrl</statusupdateurl>
    <descriptor>Test Transaction</descriptor>
    <country>DE</country>
    <accountholdername>James Mason</accountholdername>
  </paymentmethoddetails>
  <comments>
     <comment id="1">comment one</comment>
     <comment id="2">comment two</comment>
  </comments>
 <accountholdername>James Mason</accountholdername>
  <sha1hash>82f3d22c04292f8673bc1e0fb8ecf0c54e38065c</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Sample response

<response timestamp="20180731152924">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <pasref>14963290674458276</pasref>
  <paymentmethod>sofort</paymentmethod>
  <result>01</result>
  <message>PENDING</message>
  <paymentmethoddetails>
    <bankaccount/>
    <accountholdername>James Mason</accountholdername>
    <country>DE</country>
    <redirecturl>https://www.paymentMethod.com/pay</redirecturl>
    <statusupdateurl>https://www.example.com/statusUr</statusupdateurl>
    <paymentpurpose>37TC6LD Test Transaction</paymentpurpose>
  </paymentmethoddetails>
  <sha1hash>878fb286d966c70655494fa40558cdd9fc80ce4b</sha1hash>
</response>

Response syntax

Following a successful Initiate request, the next step is to redirect the customer to the alternative PM for authentication and authorization. This can be achieved, for example, using a simple JavaScript redirect.

Next, we redirect the customer to the value returned in the Redirect URL element of the Initiate response with JavaScript.

Sample redirect code

<!DOCTYPE html>
<html>
   <head>
      <title>Sample Alternative PM Redirect</title>
      <meta charset="UTF-8">
   </head>
   <body>
      <script>
         window.location = "https://www.paymentMethod.com/pay";
      </script>
   </body>
</html>

Once the customer completes their transaction with the alternative PM, they are redirected to the URL provided in the Return URL part of the Initiate request. The current status of the transaction is also returned. The transaction variables will be URL-encoded, and the message is limited to 2,048 characters. Once the character limit is reached, no more values are included. That means your application won’t receive any truncated transaction variables.

Depending on the PM used, the message sent to the Return URL might not indicate the final status of the transaction. In the example below, the current result message is PENDING, and the fund status is WAITING. The final transaction status will be sent to the Status URL provided in the Initiate request. In the case of some PMs, this message to the Status URL is sent at almost exactly the same time that the customer is redirected to your Return URL.

In the case of asynchronous payment methods, the Return URL should be treated as an interim step. Your application might put the customer on hold for a few seconds while it checks to see if the Status URL was sent a final update. You can then redirect the customer to a final success or failure page. In the event of the Status URL not receiving the final status update within your determined time limit, you can display a message to the customer informing them that their order will be processed when the final status is received.

Sample return URL parameters

The response will contain a hashed string (sha1hash) made up of key transaction variables, including the Order ID, Result Code, and Timestamp. Your application must construct and check this to ensure the response wasn’t tampered with. For more information, see the Check the Response hash section.

Before you update your application, check that the Order ID and other transaction variables can be definitively linked with the original transaction request and order created in your application.

sha1hash=0aa43f1d647819efd238e46fe3301d80076a8648&
timestamp=20181016103012&
merchantid=Merchant ID&
account=internet&
merchanttransactionid=f48856d1c7e4492eb7594e68e2fc682c&
orderid=N6qsk4kYRZihmPrTXWYS6g&
result=01&
Amount=100&
message=PENDING&
paymentpurpose=37TC6LD Test Transaction&
paymentmethod=sofort&
fundstatus=WAITING&
pasref=14627849160897986&
country=DE

Return URL parameters syntax

As we mentioned previously, depending on the payment method being used, the Return URL provided in the payment-set request might not receive the final transaction status.

The Status URL receives the final status. The format of the message is the same as the Return URL. Again, depending on the PM used, this can happen at the same time as the customer is redirected to your Return URL, moments after — or, potentially, the final status update might come days later. So, the Return URL acts as an interim processing page, waiting for the final update.

For payment methods in which you expect the final status update to come days later, your Status URL will need to accept the message sent by us, find the correct order in your application, and update the status accordingly. You may want to inform the customer at this point that their payment was finally accepted. You can also initiate the dispatch of items.

In summary, the Status URL needs to be an endpoint in your application capable of accepting an HTTP message. This will inform your application of the final status of a transaction. Upon receipt, you can validate the response, check the details against what your application has stored, and update accordingly.

Sample Status URL parameters

sha1hash=0aa43f1d647819efd238e46fe3301d80076a8648&
timestamp=20181016103012&
merchantid=Merchant ID&
account=internet&
merchanttransactionid=f48856d1c7e4492eb7594e68e2fc682c&
orderid=N6qsk4kYRZihmPrTXWYS6g&
result=01&
Amount=100&
message=PENDING&
paymentpurpose=37TC6LD Test Transaction&
paymentmethod=sofort&
fundstatus=WAITING&
pasref=14627849160897986&
country=DE

Return URL parameters syntax

This request allows you to fully or partially refund a successful transaction. You must use the same Order ID as the original initiate request in addition to the following elements:

• Payments Reference — Must be the one returned in the Initiate response.
• Refund Password — Hashed with the SHA-1 algorithm and included in the Refund element.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="payment-credit" timestamp="20160103174525">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <amount currency="EUR">1999</amount>
  <orderid>wZLVqHNnbZKBJhbeiW</orderid>
  <pasref>95427846660897986</pasref>
  <paymentmethod>sofort</paymentmethod>
  <paymentmethoddetails>
    <returnurl>https://www.example.com/returnUrl</returnurl>
    <statusupdateurl>https://www.example.com/statusUrl</statusupdateurl>
    <country>DE</country>
  </paymentmethoddetails>
  <comments>
     <comment id="1">comment one</comment>
     <comment id="2">comment two</comment>
  </comments>
  <refundhash>8347589234572387502457230459827345</refundhash>
</request>

Request syntax

Sample response

<response timestamp="20180731180503">
  <merchantid>realexsandbox</merchantid>
  <account>internet</account>
  <orderid>wZLVqHNnbZKBJhbeiW</orderid>
  <pasref>18634718560685523</pasref>
  <paymentmethod>sofort</paymentmethod>
<paymentmethoddetails>
    <returnurl>https://www.example.com/returnUrl</returnurl>
    <country>DE</country>
    <accountholdername>James Mason</accountholdername>
    <paymentpurpose>Testing purposes</paymentpurpose>
    <Account>Testing purposes</paymentpurpose>
  </paymentmethoddetails>  
<result>00</result>
  <message>SUCCESS</message>
  <!-- Error Message if present <errmsg></errmsg> -->
  <sha1hash>4c513cabeaaee5fa0714f304ca9a40da350747b5</sha1hash>
  <merchantrefundid>f48856d1c7e4492eb7594e68e2fc682c</merchantrefundid>
</response>

Response syntax

To test your integration, we provide a simple simulator application to test redirecting the customer to a particular payment method along with your Return and Status Update URLs. By setting the payment method as testpay in the Initiate request, your application can then redirect the customer to the simulator.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="payment-set" timestamp="20180613173251">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <amount currency="EUR">1001</amount>
  <autosettle flag="1"/>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <paymentmethod>testpay</paymentmethod>
  <paymentmethoddetails>
    <returnurl>https://www.example.com/returnUrl</returnurl>
    <statusupdateurl>https://www.example.com/statusUrl</statusupdateurl>
    <descriptor>Test Transaction</descriptor>
    <country>DE</country>
    <accountholdername>James Mason</accountholdername>
  </paymentmethoddetails>
  <sha1hash>82f3d22c04292f8673bc1e0fb8ecf0c54e38065c</sha1hash>
</request>

The Simulator page provides a range of messages to send to the Return and Status URLs. The delay selection determines when the Status URL receives the final status update. You can test PMs in which the final status is sent moments, hours, or even days after the transaction is completed by the customer.

The final status might also be sent at the same time as the redirection and message to the Return URL (No Delay). The responses returned by the simulator will be the same format of those outlined in the other steps in this guide.

The response and delay selections are outlined below.

The GET /payments endpoint can also be used for querying payment reports based on the parameters below. The required fields are merchantTransactionID and/or startDateTime and endDateTime; if absent, a BAD-REQUEST response (400) is returned.

Other fields, such as accountId or transactionState are used to add more filters to the result list. If you send merchantTransactionID, you will get back a list of one transaction. You can also pass in other optional fields as search query parameters to fetch a list of transactions meeting that search criteria. As an example, you could pass in startDateTime and endDateTime to fetch a list of transactions within a date range.

GET request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C)—dependent on another field or regional requirement.

Response syntax - GET call successfully executed

Response syntax - payment initiation failed

This endpoint can also be used to retrieve a list of refunds based on search criteria. It accepts search criteria as query parameters. The table below contains request fields that can be used for a search. You must use merchantRefundID or OrderId or the startDateTime and endDateTime for the query.

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field or regional requirement.

Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Build the request hash

Use the tabs below to follow the steps for a certain request type: Initiate or Refund.

Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Check the Response hash

Use the tabs below to follow the steps for a certain request type: Initiate, Refund, Redirect to APM, or Status Update.

Our Postman collection for alternative payment methods is available for downloading. You can use this collection to test transactions for all of our alternative and local supported payment methods via the XML API.

The zip file below contains the following files:

• LPM Postman Collection — A JSON file that contains Hosted Payment Page (HPP), XML, and JSON calls
• LPM Environment — A JSON file for use with the HPP and JSON calls

To download the collection (.zip file), click the button below:


Download File