Purchase

This endpoint initiates a payment order.

The transaction lifetime is 5 minutes from the start of the purchase request. If the process is not completed within this time, the transaction status will be changed to "EXPIRED" and a notification will be sent to you.

note

The transaction may proceed with 3DS or non-3DS authentication, depending on the issuing bank.

3DS Payment

After a successful purchase request, the response message will include a redirectUrl parameter. Proceed to complete the 3DS verification by accessing this URL.

Once the 3DS verification is finalized, you will be redirected to the URL you specified as successUrl or failUrl in the request body, depending on the result of the process. This redirect URL will be called with referenceNo parameter.

3ds

Non-3DS Payment

In this flow, the result of the response will include the transaction's final status of whether the request was successful or not.

non-3ds

Hash Calculation

To enhance data security during communication, generate a unique SHA-256 hash value of the request body and include it as the "hash" field. This hash value helps the server verify that the request data remains intact and untampered during transit.

POST - Sandbox

https://sandbox.fingenom.com/fn-execute/payment/purchase

POST - Production

https://api.fingenom.com/fn-execute/payment/purchase

Header Parameters

Parameter	Description	Type	R/O
`Authorization`	Authorization header containing your Secret Key	string	R
`mid`	mid header containing your merchant ID	string	O

Body Parameters

Parameter	Description	Type	R/O
`referenceNo`	The unique number provided by the merchant is used to track transactions. (max. 32 characters)	string	R
`amount`	Amount to charge, in the minor unit of your selected currency. All currencies are standardized to 100 units. For example, an amount of 100 in EUR is equal to 1€	number	R
`currency`	Code of the currency. Must consist of 3 capital letters.	string	R
`creditCard`	An object that contains credit card data.	object	R
`holder`	Cardholder name.	string	R
`number`	Cardholder number. Must be between 13 and 19 characters long.	string	R
`expiryMonth`	Expiry month of the card. Should be either 1 or 2 characters long.	string	R
`expiryYear`	Expiry year of the card. Should be either 2 or 4 characters long.	string	R
`cvv`	Card Verification Value (CVV) usually displayed on the back of the card.	string	R
`firstName`	Customer first name	string	R
`lastName`	Customer last name	string	R
`email`	Customer email	string	R
`phone`	Customer phone number. Must contain from 8 to 15 characters.	string	R
`country`	Customer country code. Should be 2 or 3 characters long.	string	R
`state`	Customer state.	string	O
`street`	Customer street	string	R
`city`	Customer city	string	R
`zip`	Customer zip	string	R
`ip`	Customer ip	string	R
`dateOfBirth`	Customer date of birth. (YYYY-MM-DD)	string	R
`successUrl`	URL for user return after success payment	string	R
`failUrl`	URL for user return after fail payment	string	R
`notifyUrl`	URL to send notifications when the transaction status changes	string	R
`deviceId`	Device fingerprint	string	R
`hash`	The unique SHA-256 hash value of the request body	string	R
`browserUserAgent`	A browser user agent is a string of characters that identifies the browser	string	R
`language`	The language of the browser UI	string	R
`colorDepth`	The color depth of the screen	number	R
`screenHeight`	The height of the screen in pixels	number	R
`screenWidth`	The width of the screen in pixels	number	R
`browserTZ`	The browser time zone	number	R
`javaEnabled`	The property that indicated whether the browser had support for Java applets	boolean	R
`acceptHeader`	A HTTP header field that specifies the types of content the browser can accept from the server	string	R

{
    "referenceNo": "d43aaaca80e842a890f5dfad095f456",
    "amount": 1000,
    "currency": "EUR",
    "creditCard": {
      "holder": "Alex Fox",
      "number": "4111111157537193",
      "expiryMonth": "1",
      "expiryYear": "2025",
      "cvv": "123"
  },
  "customer": {
      "firstName": "Alex",
      "lastName": "Fox",
      "email": "some_mail@mail.com",
      "phone": "15551234567",
      "country": "USA",
      "state": "NJ",
      "street": "2495 Lake Road",
      "city": "Merchantville",
      "zip": "08109",
      "ip": "192.168.1.1",
      "dateOfBirth": "2000-08-24"
    },
    "browserInfo": {
      "browserUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
      "language": "en-US",
      "colorDepth": 24,
      "screenHeight": 939,
      "screenWidth": 1255,
      "browserTZ": 0,
      "javaEnabled": false,
      "acceptHeader": "/"
    },
    "successUrl": "https://example.com/success",
    "failUrl": "https://example.com/fail",
    "notifyUrl": "https://example.com",
    "deviceId": "2c6e4d88965723adf0d5a72832aaa3da",
    "hash": "9cbd219ef45d7957262bca36c080b383ca7cdfb08e9f1fcc0dec0bfe4d97ac4b"
}

Responses

Response 3DS payment

200

{
  "status": "successful",
  "code": "2002",
  "messagetype": "acquirerRes",
  "message": {
    "referenceNo": "d43aaaca80e842a890f5dfad095f456",
    "message": "Redirect required",
    "amount": 1171,
    "currency": "USD",
    "redirectUrl": "https://sandbox.fingenom.com/fn-execute/payment/purchase-3dsv/d43aaaca80e842a890f5dfad234/c01e34c12a33dedfbf1049097ea7ba9c",
    "status": "REDIRECTED_TO_3DS",
    "transactionId": "d43aaaca80e842a890f5dfad234"
  }
}

Parameter	Description	Type
`status`	Response status	string
`code`	Response code	string
`messagetype`	Response message type	string
`message`	Response message	object

Response Non-3DS payment

200

{
  "status": "successful",
  "code": "2002",
  "messagetype": "acquirerRes",
  "message": {
    "referenceNo": "d43aaaca80e842a890f5dfad095f456",
    "message":"SUCCESS",
    "amount": 1171,
    "currency": "USD",
    "status": "SUCCESS",
    "transactionId": "d43aaaca80e842a890f5dfad234"
  }
}

Parameter	Description	Type
`status`	Response status	string
`code`	Response code	string
`messagetype`	Response message type	string
`message`	Response message	object

Failure response

The format of the response differs based on the encountered error.

400

{
  "status": "failure",
  "code": "1021",
  "messagetype": "purchase",
  "message": {
      "referenceNo": "d43aaaca80e842a890f5dfad095fc143",
      "message": "Required Parameter(s) Missing",
      "status": "error"
  }
}

Parameter	Description	Type
`status`	Response status	string
`code`	Response code	string
`messagetype`	Response message type	string
`message`	Response message	object

Example Code

An example code of full integration on the React

import * as React from "react";
import sha256 from "crypto-js/sha256";

const months = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
const years = ["2023", "2024", "2025", "2026", "2027", "2028", "2029", "2030"];

const formStyle = {
  display: "flex",
  flexDirection: "column",
  gap: "6px",
};

export default function App() {
  const generateReferenceNo = (length) => {
    const characters = "0123456789abcdefghijklmnopqrstuvwxyz";
    let result = "";

    for (let i = 0; i < length; i++) {
      const randomIndex = Math.floor(Math.random() * characters.length);
      result += characters.charAt(randomIndex);
    }

    return result;
  };

  const handleSubmit = (event) => {
    event.preventDefault();
    const formData = new FormData(event.target);
    const creditCard = {};

    for (let [name, value] of formData) {
      creditCard[name] = value;
    }

    const customer = {
      firstName: "Test",
      lastName: "User",
      email: "some_mail@mail.com",
      phone: "12312",
      country: "USA",
      state: "NJ",
      street: "2495 Lake Road",
      city: "Merchantville",
      zip: "08109",
      ip: "192.168.1.1",
      dateOfBirth: "2000-08-24",
    };

    const browserInfo = {
      browserUserAgent: navigator.userAgent,
      language: navigator.language,
      colorDepth: window.screen.colorDepth,
      screenHeight: window.screen.height,
      screenWidth: window.screen.width,
      browserTZ: new Date().getTimezoneOffset(),
      javaEnabled: navigator.javaEnabled(),
      acceptHeader: "/",
    };

    const data = {
      referenceNo: generateReferenceNo(32),
      amount: 1000,
      currency: "EUR",
      creditCard: creditCard,
      customer: customer,
      browserInfo: browserInfo,
      successUrl: "https://example.com/success",
      failUrl: "https://example.com/fail",
      notifyUrl: "https://example.com",
      deviceId: "2c6e4d88965723adf0d5a72832aaa3da",
    };

    data.hash = hashBody(data);

    startPayment(data);
  };

  const startPayment = async (data) => {
    try {
      const response = await fetch("https://sandbox.fingenom.com/fn-execute/payment/purchase", {
        method: "POST",
        body: JSON.stringify(data),
        headers: {
          Authorization: "f35a331c-1ce9-4d33-b5f6-5633bd9bd320", // Your Secret Key
          mid: "657b1e06f4abbd002c528bd0", // Merchant ID
          Accept: "application/json",
          "Content-Type": "application/json",
        },
      });

      const result = await response.json();
      if (result.message.error) {
        alert(result.message.error);
        return;
      }
      const redirectUrl = result.message?.redirectUrl;
      if (redirectUrl) {
        window.location.href = result.message.redirectUrl;
      }
    } catch (error) {
      console.error("Error:", error);
    }
  };

  const hashBody = (body) => {
    return sha256(JSON.stringify(body)).toString();
  };

  return (
    <div>
      <form style={formStyle} onSubmit={handleSubmit}>
        <input value="Alex" placeholder="Card Holder" name="holder" />
        <input value="4001919257537193" type="tel" placeholder="Card Number" name="number" />
        <select name="expiryMonth" value="1">
          {months.map((month) => (
            <option key={month} value={month}>
              {month}
            </option>
          ))}
        </select>
        <select name="expiryYear" value="2025">
          {years.map((year) => (
            <option key={year} value={year}>
              {year}
            </option>
          ))}
        </select>
        <input value="123" placeholder="CVV" name="cvv" />
        <input type="submit" value="Submit" />
      </form>
    </div>
  );
}

Test cards

Number	CVV	Date	Description
4286 4829 7043 0895	Any 3 digits	Any future date	NON-3DS successful payment
4286 4888 5945 3346	Any 3 digits	Any future date	NON-3DS failure payment
4299 5092 9968 3351	Any 3 digits	Any future date	3DS payment

Purchase

3DS Payment​

Non-3DS Payment​

Hash Calculation​

Header Parameters​

Body Parameters​

Responses​

Response 3DS payment​

Response Non-3DS payment​

Failure response​

Example Code​

Test cards​