Hosted API

This document provides a comprehensive guide to integrate with the Pay Agency. The Hosted API allows non-seamless payment processing without using card details. The API endpoint and payload details are provided below, along with examples in multiple programming languages.

API Endpoint

POST https://backend.pay.agency/api/v1/live/hosted/card

Parameters

Parameter	Type	Description	Required
`first_name`	String	First name of the cardholder	Yes
`last_name`	String	Last name of the cardholder	Yes
`email`	String	Email address of the user	Yes
`address`	String	Billing address	Yes
`country`	String	Country code (ISO 3166-1 alpha-3 format)	Yes
`city`	String	City of the cardholder	Yes
`state`	String	State of the cardholder	Yes
`zip`	String	ZIP or postal code	Yes
`ip_address`	String	IP address of the user	Yes
`phone_number`	String	Phone number of the cardholder	Yes
`amount`	Number	Transaction amount in smallest currency unit	Yes
`currency`	String	Currency code (ISO 4217 format)	Yes
`redirect_url`	String	URL to redirect users after payment	Yes
`webhook_url`	String	URL for server-to-server webhook notifications	NO
`order_id`	String	Unique order from merchant side	NO
`terminal_id`	String	Connector unique terminal_id (It's usefull when you want to bypass all routing and cascading logic)	NO

Payload

The payload should be sent in JSON format. Below is the structure of the payload:

{
  "first_name": "James",
  "last_name": "Dean",
  "email": "james@gmail.com",
  "address": "64 Hertingfordbury Rd",
  "country": "GB",
  "city": "Newport",
  "state": "GB",
  "zip": "TF10 8DF",
  "ip_address": "127.0.0.1",
  "phone_number": "7654233212",
  "amount": 100,
  "currency": "GBP",
  "redirect_url": "https://pay.agency",
  "webhook_url": "https://pay.agency/webhook",
  "order_id": "12524AGSDF34DS"
}

Example Responses

Success Response

{
  "status": "REDIRECT",
  "message": "Please redirect user to complete the payment.",
  "redirect_url": "https://backend.pay.agency/api/v1/test/card/hosted//PA0186280974141637",
  "data": {
    "amount": 100,
    "currency": "GBP",
    "order_id": null,
    "transaction_id": "PA0186280974141637",
    "customer": {
      "first_name": "James",
      "last_name": "Dean",
      "email": "james@gmail.com"
    },
    "refund": {
      "status": false,
      "refund_date": null
    },
    "chargeback": {
      "status": false,
      "chargeback_date": null
    }
  }
}

Error Response

{
  "status": "FAILED",
  "message": "The Card is not suported for testing.",
  "data": {
    "amount": 100,
    "currency": "GBP",
    "order_id": null,
    "transaction_id": "FS0279243486998947",
    "customer": {
      "first_name": "James",
      "last_name": "dean",
      "email": "james@gmail.com"
    },
    "refund": {
      "status": false,
      "refund_date": null
    },
    "chargeback": {
      "status": false,
      "chargeback_date": null
    }
  }
}

Integration Examples

Below are examples of how to integrate with the API using different languages.

const { randomBytes, createCipheriv } = require("crypto");
const axios = require("axios");
 
// AES Encryption function
function encryptData(data, key) {
  const iv = randomBytes(16);
  const cipher = createCipheriv(
      "aes-256-cbc",
      Buffer.from(key, "utf-8"),
      iv
  );
  let encrypted = cipher.update(data, "utf-8");
  encrypted = Buffer.concat([encrypted, cipher.final()]);
  return iv.toString("hex") + ":" + encrypted.toString("hex");
}
const payload = {
  first_name: "James",
  last_name: "dean",
  email: "dean@gmail.com",
  address: "64 Hertingfordbury Rd",
  country: "GB",
  city: "Newport",
  state: "Newport",
  zip: "TF10 8DF",
  ip_address: "127.0.0.1",
  phone_number: "7654233212",
  amount: 100,
  currency: "GBP",
  redirect_url: "https://pay.agency",
  webhook_url: "https://webhook.site/40be94f4-293e-4d84-a747-8c934557c0e3",
};
 
// Encryption key (replace with your actual key)
const encryptionKey = process.env.ENCRYPTION_KEY || "2542b322a40ada01489c5491fe379512";
 
// Encrypt the payload
const encryptedPayload = encryptData(JSON.stringify(payload), encryptionKey);
 
// API request
const url = "https://backend.pay.agency/api/v1/live/card";
axios
    .post(
        url,
        { payload: encryptedPayload },
        {
          headers: {
              "Content-Type": "application/json",
              "Authorization":"Bearer FS_TEST_62d221bba3bbeb4281ec48c70e3446bce31562c860eeb9dbc02f42ee"
          },
        }
    )
    .then((response) => {
        console.log("API Response:", response.data);
    })
    .catch((error) => {
        console.error("Error:", error.response);
    });

Encryption Key in Settings

The encryption key, used for securing sensitive data, can be found on the Settings page. This key is essential for encryption and decryption processes, ensuring data confidentiality. Make sure to store it securely and avoid sharing it with unauthorized users.

Hosted API

On this page