Hosted payment pages

Hosted payment pages are a simple way to start accepting payments without requiring any front-end development experience. With hosted payment pages, your customer is redirected to IXOPAY platform's secure hosted payment page to enter their payment details. After the payment is complete, the customer is redirected back to your website.

Reference

For more details on hosted payment pages, check out the in-depth article on hosted payment pages in the reference.

How to use hosted payment pages

Step 1: Initialize a transaction

The first step is to initialize a new transaction on the IXOPAY platform from your backend system. To create a transaction send a POST request to gateway.ixopay.com.

Here we choose a Debit transaction, which when successful, will immediately transfer funds. Depending on your business model a Preauthorize transaction - followed by a Capture transaction - might be more appropriate.

Authentication

For details on how to authenticate API calls to the IXOPAY platform, see Authentication.

tip

This is a minimal example. Include as much information as possible in the customer field. This reduces friction and provides the most benefit for risk checks, 3D-secure authentication and other validations.

curl

curl --request POST -sL \
  --url "https://gateway.ixopay.com/api/v3/transaction/${API_KEY}/debit" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Basic $(echo -n "$USERNAME:$PASSWORD" | base64)" \
  --data-raw '{
    "merchantTransactionId": "your-unique-identifier",
    "description": "Purchase description shown on credit card statement.",
    "amount": "9.99",
    "currency": "EUR",
    "successUrl": "https://shop.example.org/checkout/success",
    "cancelUrl": "https://shop.example.org/checkout/cancelled",
    "errorUrl": "https://shop.example.org/checkout/error"
  }'

Python

import requests
import json
import base64
import os

url = "https://gateway.ixopay.com/api/v3/transaction/{apiKey}/debit".format(
    apiKey=os.environ["API_KEY"]
)
auth = base64.b64encode("%s:%s" % (os.environ["USERNAME"], os.environ["PASSWORD"]))

payload = json.dumps(
    {
        "merchantTransactionId": "your-unique-identifier",
        "description": "Purchase description shown on credit card statement.",
        "amount": "9.99",
        "currency": "EUR",
        "successUrl": "https://shop.example.org/checkout/success",
        "cancelUrl": "https://shop.example.org/checkout/cancelled",
        "errorUrl": "https://shop.example.org/checkout/error"
    }
)
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Basic {auth}".format(auth=auth),
}

response = requests.request("POST", url, headers=headers, data=payload)

PHP

<?php

$curl = curl_init();

$auth = base64_encode("$USERNAME:$PASSWORD");

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://gateway.ixopay.com/api/v3/transaction/$API_KEY/debit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "merchantTransactionId": "your-unique-identifier",
    "description": "Purchase description shown on credit card statement.",
    "amount": "9.99",
    "currency": "EUR",
    "successUrl": "https://shop.example.org/checkout/success",
    "cancelUrl": "https://shop.example.org/checkout/cancelled",
    "errorUrl": "https://shop.example.org/checkout/error"
  }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    "Authorization: Basic $auth"
  ),
));

$response = curl_exec($curl);

curl_close($curl);

Java

OkHttpClient client = new OkHttpClient().newBuilder().build();
RequestBody body = RequestBody.create(
  MediaType.parse("application/json"),
  "{" +
    "\"merchantTransactionId\": \"your-unique-identifier\"," +
    "\"description\": \"Purchase description shown on credit card statement.\"," +
    "\"amount\": \"9.99\"," +
    "\"currency\": \"EUR\"," +
    "\"successUrl\": \"https://shop.example.org/checkout/success\"," +
    "\"cancelUrl\": \"https://shop.example.org/checkout/cancelled\"," +
    "\"errorUrl\": \"https://shop.example.org/checkout/error\"" +
  "}"
);
String auth = Base64.getEncoder().encodeToString(
  "%s:%s".format(System.getenv("USERNAME"), System.getenv("PASSWORD")));
Request request = new Request.Builder()
  .url("https://gateway.ixopay.com/api/v3/transaction/%s/debit"
    .format(System.getenv("API_KEY")))
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Basic %s".format())
  .build();
Response response = client.newCall(request).execute();

Step 2: Redirect your customer

If the IXOPAY platform successfully received your transaction, it will respond with a response containing "returnType": "REDIRECT" and a redirectUrl.

{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20240514-d94c0d72f3a36e21f16e",
  "returnType": "REDIRECT",
  "redirectUrl": "https://gateway.ixopay.com/redirect/d94c0d72f3a36e21f16e/ABCDEF01234567890ABCDEF01234567890",
  "paymentMethod": "Creditcard"
}

You can now redirect the customer to the page in the redirectUrl from your backend.

HTTP

HTTP/1.1 302 Found
Location: https://gateway.ixopay.com/redirect/d94c0d72f3a36e21f16e/ABCDEF01234567890ABCDEF01234567890

Python

self.send_response(302)
self.send_header('Location', response.json()["redirectUrl"])
self.end_headers()

PHP

$redirectUrl = json_decode($response)->redirectUrl;
header("Location: $redirectUrl", true, 302);
exit;

Java

JsonReader jsonReader = Json.createReader(new StringReader(response.body().string()));
JsonObject json = jsonReader.readObject();

resp.setStatus(HttpServletResponse.SC_FOUND);
resp.setHeader("Location", json.getString("redirectUrl"));

For details on how to handle unsuccessful transaction results, see Handling errors.

Step 3: Payment complete

After the payment is complete, the customer will be redirected back to the website specified in successUrl when creating the transaction.

Additionally, if you specify a callbackUrl in the Debit transaction request, the IXOPAY platform will send a callback with the status of the payment. For more information on how to set up and use callbacks, please see the callbacks page.

Next steps

Now that you've integrated IXOPAY platform via a hosted payement page, you can look into …

• … testing your setup to make sure you've set up everything correctly.
• … handling changes to the payments status with callbacks.
• … recurring payments to generate recurring revenue.
• … making your code production ready by handling errors.