Getting Started with Xace

Welcome to the Xace API

This guide will help you get started with our API. You can retrieve financial data, create payments, and manage webhooks. The Xace API covers the following resources:

Transactions: Retrieve transaction details and create payments.
Accounts: Access account information, including balances and account types.
Payees: Manage and retrieve payee details.
Payment Approvals: Process and manage payment approvals.
Webhooks: Register and receive webhooks for real-time payment notifications.

📝 Prerequisites

Before getting started, ensure you have the following:

API Key and Secret: Contact Xace support to obtain your API key/secret.
Environment: Our API supports both sandbox and only production environment for now. Make sure you have the correct environment URL.
OAuth 2.0: You will need to authenticate using OAuth 2.0 with your client credentials. Ensure your client ID and secret are ready for the authentication process.

🚦 Connecting to the API

Once you have your client id and secret, you can connect to Xace with the following code.

Connecting with NodeJS

Get all accounts

Codetext

const axios = require('axios');
const qs = require('qs');

async function getAccessToken() {
  const tokenUrl = 'https://xace-prod.uk.auth0.com/oauth/token';

  const data = qs.stringify({
    client_id: 'YOUR_CLIENT_KEY',
    client_secret: 'YOUR_CLIENT_SECRET',
    audience: 'https://customer-api.prod.xace.io',
    grant_type: 'client_credentials',
  });

  try {
    const response = await axios.post(tokenUrl, data, {
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
    });

    return response.data.access_token;
  } catch (error) {
    console.error('Error fetching access token:', error.response?.data || error.message);
    throw error;
  }
}

async function callCustomerApi(accessToken) {
  const apiUrl = 'https://customer-api.prod.xace.io/accounts';

  try {
    const response = await axios.get(apiUrl, {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    });

    console.log('API Response:', response.data);
  } catch (error) {
    console.error('Error calling customer API:', error.response?.data || error.message);
  }
}

(async () => {
  try {
    const accessToken = await getAccessToken();
    await callCustomerApi(accessToken);
  } catch (err) {
    process.exit(1);
  }
})();

Connecting with Curl

Get all accounts

Step 1: Obtain the OAuth 2.0 Token

Codetext

curl --location 'https://xace-prod.uk.auth0.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=YOUR_CLIENT_KEY' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'audience=https://customer-api.prod.xace.io' \
--data-urlencode 'grant_type=client_credentials'

Step 2: Use the Token to Fetch Accounts

Codetext

curl -X GET "https://customer-api.prod.xace.io/accounts" \
     -H "Authorization: YOUR_ACCESS_TOKEN"

Error Handling

In case of errors, the API returns HTTP status codes and descriptive error messages. Common status codes include:

401 Unauthorized: Invalid or expired token.
403 Forbidden: You don't have access to this resource.
404 Not Found: The requested resource doesn’t exist.
500 Internal Server Error: Something went wrong on our end.