Angala Payment Gateway API Docs

Introduction

The Angala Payment Gateway API provides a comprehensive set of endpoints for managing digital payments, customer information, and wallet operations. This documentation covers all available endpoints with detailed information on how to integrate them into your applications.

Base URL: https://pg-api.payrail.co/

API Version: 1.0.0

Format: All requests and responses are in JSON format

Getting Started

To begin using the Angala Payment Gateway API, follow these steps:

Sign up for an account on the Angala Developer Portal
Obtain your API keys from the dashboard
Review the authentication section for how to include your API key in requests
Start with the Customer API to create and manage customer profiles
Use the Wallet API to handle financial transactions
Implement the Checkout API for payment processing

Authentication

To ensure the security and integrity of every request, the Angala Payment Gateway uses an API key-based authentication system. Each request must include a valid authentication key passed in the request header as x-api-key. This key uniquely identifies and authorizes the client application, preventing unauthorized access and ensuring all transactions are securely validated before processing. Developers must obtain their API key from the Angala developer dashboard or admin panel and keep it confidential at all times.

x-api-key: RSK-4kFvmdkoRN5Tle28rtI5kyZqbJOmutknrxR6j0xBqv3esSk91gEWLXA

You can obtain your API keys from the Angala Developer Dashboard. We provide both test and live keys for development and production respectively.

Security Best Practices

Never expose your secret keys in client-side code
Rotate your keys periodically (every 90 days recommended)
Use environment variables to store API keys
Implement request rate limiting in your application
Use HTTPS for all API requests

Customer API

The Customer API provides endpoints for managing customer information, wallet operations, and authentication. This API handles customer data retrieval, wallet management, and secure access using API key authentication. All endpoints require API key authentication via the x-api-key header.

GET fetch-countries

GET /api/v1/customer/fetch-countries

Retrieves a list of countries supported by the Angala Payment Gateway.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️

Response Example

{
      "status": "success",
      "data": [
        {
          "countryId": "NG",
          "name": "Nigeria",
        },
      ]
    }

GET fetch-customer-type

GET /api/v1/customer/fetch-customer-type

Retrieves available customer types (e.g., individual, business, agent).

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️

Response Example

{
          "status": "success",
          "data": [
            {
              "customer_id": "Corporate",
              "name": "Corporate",
            },
          ]
        }

POST create-customer

POST /api/v1/customer/create-customer

Creates a new customer account in the system. This endpoint registers a new customer, generates necessary identifiers, and sets up the initial customer profile.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️
Content-Type	application/json	✔️

Request Body

{
              "firstName": "Mark",
              "lastName": "John",
              "middleName": "",
              "emailAddress": "mark.john@gmail.com",
              "mobileNumber": "070653354741",
              "dob": "1955-05-20",
              "customerType": "Corporate",
              "address": "100 Charity Street, Garki",
              "city": "Abuja",
              "country": "NG"
            }

POST verify-customer-bvn

POST /api/v1/customer/verify-customer-bvn

Verifies a customer's Bank Verification Number (BVN) against official records. This endpoint performs real-time BVN validation to ensure customer identity authenticity and compliance with financial regulations. BVN verification is essential for higher transaction limits and full account functionality.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️
Content-Type	application/json	✔️

Request Body

{
  "customerId": "91f169df-bdc8-11f0-a7cf-0274f77d4a81",
  "bvn": "12345678901"
}

GET fetch-customer-byid

GET /api/v1/customer/fetch-customer-byid?customerId=91f169df-bdc8-11f0-a7cf-0274f77d4a81

Retrieves customer information using the customer's unique identifier. This endpoint returns complete customer profile details.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️

Query Parameters

Parameter	Description	Required
customerId	The unique identifier of the customer	✔️

Wallet API

The Angala Wallet Services provide a secure and flexible digital wallet system that enables users to store, send, receive, and manage funds conveniently within the Angala Payment Gateway ecosystem. It serves as the financial backbone of the platform, allowing seamless integration between user accounts, merchants, and payment operations.

With the Angala Wallet, developers and businesses can create and manage wallets for customers or agents, automate wallet funding through bank transfers or payment gateways, and perform instant peer-to-peer transfers. The service supports both personal and business wallets, ensuring scalability for a wide range of financial applications.

GET get-wallet-byid

GET /api/v1/wallet/get-wallet-byid

Retrieves wallet information by wallet ID.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️

Query Parameters

Parameter	Description	Required
walletId	The unique identifier of the wallet	✔️

GET get-wallet-by-account-number

GET /api/v1/wallet/get-wallet-by-account-number

Retrieves wallet information by account number.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️

Query Parameters

Parameter	Description	Required
accountNumber	The wallet account number	✔️

GET fetch-currencies

GET /api/v1/wallet/fetch-currencies

Retrieves supported currencies for wallet operations.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️

POST create-wallet

POST /api/v1/wallet/create-wallet

Creates a new wallet for a customer.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️
Content-Type	application/json	✔️

Request Body

{
              "customerId": "f52a8540-c47d-11f0-a7cf-0274f77d4a81",
              "currencyId": "NGN",
              "name": "Chidis Tolas",
              "phoneNumber": "071173354741",
              "customerType": "Individual"
            }

Checkout API

The Checkout API provides endpoints for creating and managing checkout sessions for payment processing.

POST create-checkout-wallet

POST /api/v1/checkout/create-checkout-wallet

Creates a checkout session for wallet-based payments.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️
Content-Type	application/json	✔️

Request Body

{
              "amount": 200,
              "duration": 30
            }

GET checkout-wallet-transactions

GET /api/v1/checkout/checkout-wallet-transactions

Retrieves transaction history for a checkout wallet.

Headers

Header	Description	Required
x-api-key	Your API authentication key	✔️

Query Parameters

Parameter	Description	Required
walletId	The unique identifier of the checkout wallet	✔️
startDate	Start date for filtering transactions (YYYY-MM-DD)	❌
endDate	End date for filtering transactions (YYYY-MM-DD)	❌

Webhooks

Receive real-time notifications about payment events in your application. Configure webhook endpoints in your dashboard to receive these events.

POST /webhooks/notify

Supported Events:

payment.success payment.failed refund.processed charge.disputed customer.created wallet.created wallet.funded checkout.completed

Webhook Payload Example

{
  "event": "payment.success",
  "data": {
    "transactionId": "txn_abc123def456",
    "amount": 150000,
    "currency": "NGN",
    "customerId": "91f169df-bdc8-11f0-a7cf-0274f77d4a81",
    "timestamp": "2023-10-15T14:31:22Z"
  },
  "signature": "abc123def456ghi789"
}

Error Codes

Standard HTTP status codes are returned along with detailed error messages in the response body.

Code	Description	Resolution
200	Success	Request completed successfully
201	Created	Resource successfully created
400	Bad Request	Check request parameters
401	Unauthorized	Verify API key is valid and included
402	Payment Failed	Check payment details and funds
404	Not Found	Resource does not exist
422	Unprocessable Entity	Validation failed for request data
429	Too Many Requests	Rate limit exceeded
500	Server Error	Contact support if persistent

Code Examples

Example: Create Customer

Using cURL:

curl --request POST "https://api.angala.com/v1/customer/create-customer" \
--header "x-api-key: YOUR_API_KEY_HERE" \
--header "Content-Type: application/json" \
--data '{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "+2348012345678",
  "address": "123 Main Street, Lagos",
  "dateOfBirth": "1990-01-15",
  "customerType": "individual"
}'

Using JavaScript (Fetch API):

const API_KEY = 'YOUR_API_KEY_HERE';

async function createCustomer() {
  try {
    const response = await fetch("https://api.angala.com/v1/customer/create-customer", {
      method: "POST",
      headers: {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        firstName: "John",
        lastName: "Doe",
        email: "john.doe@example.com",
        phoneNumber: "+2348012345678",
        address: "123 Main Street, Lagos",
        dateOfBirth: "1990-01-15",
        customerType: "individual"
      })
    });
    
    const data = await response.json();
    
    if (response.ok) {
      console.log("Customer created:", data);
      return data.customerId;
    } else {
      console.error("Failed to create customer:", data);
      throw new Error(data.message || "Customer creation failed");
    }
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

Example: Create Wallet

Using Python (Requests library):

import requests
import json

api_key = "YOUR_API_KEY_HERE"
url = "https://api.angala.com/v1/wallet/create-wallet"

headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json"
}

payload = {
    "customerId": "91f169df-bdc8-11f0-a7cf-0274f77d4a81",
    "currency": "NGN",
    "walletType": "personal"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print("Status Code:", response.status_code)
print("Response:", response.json())

Example: Verify BVN

curl --request POST "https://api.angala.com/v1/customer/verify-customer-bvn" \
--header "x-api-key: YOUR_API_KEY_HERE" \
--header "Content-Type: application/json" \
--data '{
  "customerId": "91f169df-bdc8-11f0-a7cf-0274f77d4a81",
  "bvn": "12345678901"
}'

Angala API Docs

Angala Payment Gateway API Documentation

Introduction

Getting Started

Authentication

Security Best Practices

Customer API

GET fetch-countries

Headers

Response Example

GET fetch-customer-type

Headers

Response Example

POST create-customer

Headers

Request Body

POST verify-customer-bvn

Headers

Request Body

GET fetch-customer-byid

Headers

Query Parameters

Wallet API

GET get-wallet-byid

Headers

Query Parameters

GET get-wallet-by-account-number

Headers

Query Parameters

GET fetch-currencies

Headers

POST create-wallet

Headers

Request Body

Checkout API

POST create-checkout-wallet

Headers

Request Body

GET checkout-wallet-transactions

Headers

Query Parameters

Webhooks

Supported Events:

Webhook Payload Example

Error Codes

Code Examples

Example: Create Customer

Example: Create Wallet

Example: Verify BVN