List Payment Purpose Codes (Atlas)

Overview

The GET /banking/ibans/v2/payments/purpose-codes endpoint retrieves standardized regulatory purpose codes. Many jurisdictions and clearing networks (e.g. UAE Central Bank, Reserve Bank of India, Bank of England) require a designated purpose code for cross-border or local payment clearance.

Use this endpoint to populate dropdowns in payment checkout flows and ensure transactions include valid regulatory categorization.

Resource Access

• HTTP Method: GET
• Endpoint: /banking/ibans/v2/payments/purpose-codes
• Authentication: Bearer token required
• Permissions: Client access

Query Parameters

Parameter	Type	Required	Description	Example
currency	string	Yes	3-letter currency code for the payment route.	USD
type	string	Yes	Scope of document classification: LOCAL or GLOBAL.	LOCAL
id	string | array	No	Specific document type ID or array of IDs.	1
purpose	string	No	Enum: "true" (returns only purpose category types) or "false" (returns non-purpose types).	true
entityType	string	No	Target entity category: business or individual.	business
paymentDirection	string	No	Direction of fund flow: Inbound, Outbound, or Cards.	Outbound

---

Response

Success Response (200 OK)

{
  "documentTypes": [
    {
      "id": 1,
      "category": "Payment Purpose",
      "title": "Purchase of Professional Service(s)",
      "subCategory": "Consulting & Legal",
      "entityType": "business",
      "provider": null,
      "paymentDirection": "Outbound",
      "isArchived": false,
      "createdAt": "2023-01-15T10:30:00Z",
      "updatedAt": "2023-06-20T14:45:00Z"
    },
    {
      "id": 2,
      "category": "Payment Purpose",
      "title": "Payroll/Personnel Payment",
      "subCategory": "Salary",
      "entityType": "business",
      "provider": null,
      "paymentDirection": "Outbound",
      "isArchived": false,
      "createdAt": "2023-01-15T10:30:00Z",
      "updatedAt": "2023-06-20T14:45:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
documentTypes	array	List of purpose code objects.
documentTypes[].id	integer	Unique identifier to pass in purposeId on payment requests.
documentTypes[].category	string	Regulatory category (e.g. Payment Purpose, Identity Document).
documentTypes[].title	string	Display label for user selection.
documentTypes[].subCategory	string	Detailed classification group.
documentTypes[].entityType	string	Entity type (business or individual).
documentTypes[].paymentDirection	string	Flow direction (Inbound, Outbound, Cards).
documentTypes[].isArchived	boolean	Indicates whether the code has been deprecated.

---

Code Examples

cURL

curl -X GET "https://api.ahrvo.network/banking/ibans/v2/payments/purpose-codes?currency=USD&type=LOCAL&paymentDirection=Outbound&purpose=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

JavaScript (Fetch)

const params = new URLSearchParams({
  currency: 'USD',
  type: 'LOCAL',
  paymentDirection: 'Outbound',
  purpose: 'true'
});

const response = await fetch(`https://api.ahrvo.network/banking/ibans/v2/payments/purpose-codes?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log('Available purpose codes:', data.documentTypes);

Python (requests)

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/payments/purpose-codes"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
params = {
    "currency": "USD",
    "type": "LOCAL",
    "paymentDirection": "Outbound",
    "purpose": "true"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

---

Interactive API Console

Test the endpoint directly in your browser: