Create Merchant

Overview

The Create Merchant API allows you to create a new customer account for merchant operations. This account is required before you can create recipients or process payments.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/iban/api/account/v2/create
• Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
Content-Type	application/json	Yes	Request body content type

Request Body

The request body should contain a JSON object with the following structure:

{
  "email": "merchant@clientname.com",
  "phone_no": "4112338066",
  "phone_prefix": "+1",
  "partner_user_id": "ClientCustomerID123"
}

Request Fields

Field	Type	Required	Description
email	string	Yes	Email address of the merchant
phone_no	string	Yes	Phone number without country code
phone_prefix	string	Yes	Country code prefix (e.g., "+1", "+44")
partner_user_id	string	Yes	Your unique identifier for this customer

Response

Success Response (201 Created)

{
  "customer_id": "CUST_12345678",
  "email": "merchant@clientname.com",
  "phone_no": "4112338066",
  "phone_prefix": "+1",
  "partner_user_id": "ClientCustomerID123",
  "status": "active",
  "created_at": "2026-01-13T10:00:00.000Z"
}

Response Fields

Field	Type	Description
customer_id	string	Unique customer ID assigned by the system
email	string	Email address of the merchant
phone_no	string	Phone number without country code
phone_prefix	string	Country code prefix
partner_user_id	string	Your unique identifier for this customer
status	string	Account status (active, pending, suspended)
created_at	string (date-time)	Creation timestamp

Error Responses

• 400 Bad Request: Invalid input data (invalid email format, missing required fields)
• 401 Unauthorized: Invalid or missing authentication token
• 409 Conflict: Customer with this email or partner_user_id already exists
• 500 Internal Server Error: Server error occurred

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/iban/api/account/v2/create' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "merchant@clientname.com",
    "phone_no": "4112338066",
    "phone_prefix": "+1",
    "partner_user_id": "ClientCustomerID123"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/account/v2/create"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "email": "merchant@clientname.com",
    "phone_no": "4112338066",
    "phone_prefix": "+1",
    "partner_user_id": "ClientCustomerID123"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.networking/iban/api/account/v2/create';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  email: 'merchant@clientname.com',
  phone_no: '4112338066',
  phone_prefix: '+1',
  partner_user_id: 'ClientCustomerID123'
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• The customer_id returned should be used in subsequent API calls
• The partner_user_id must be unique across all your customers
• Email addresses must be valid and unique
• Phone numbers should include only digits (no spaces or special characters)
• The phone prefix must include the '+' symbol
• Store the customer_id securely for future reference

Next Steps

After creating a merchant account:

1. Upload any required verification documents using the File Upload API
2. Create recipients for payment processing
3. Process payments to your recipients

Interactive API Explorer