Create Payment Request (Atlas)

Overview

The POST /banking/ibans/v2/payments/create endpoint creates a standardized payment request. It dynamically validates required fields according to the specified paymentType:

1. WALLET_PAYOUT: Transfers funds from a wallet to an external beneficiary bank account (targetAccountId).
2. WALLET_TO_BUSINESS: Transfers funds from a wallet directly to another platform business entity (targetCompanyId).
3. TRANSFER_WITHIN_WALLETS: Moves funds between two wallets belonging to your own company (targetWalletId).

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/payments/create
• Authentication: Bearer token required
• Permissions: Client:Make Payment To Account:write, Client:Make Payment To Another Business:write

Request Headers

Header	Value	Required	Description
Authorization	Bearer {access_token}	Yes	JWT Bearer access token
Content-Type	application/json	Yes	Request payload format
Accept	application/json	Yes	Response payload format

Request Payloads by Type

1. WALLET_PAYOUT (Bank Account Payout)

Field	Type	Required	Description
paymentType	string	Yes	Must be "WALLET_PAYOUT".
sourceWalletId	string	Yes	Unique identifier of the funding wallet.
sourceAmount	number	Yes	Float amount to transfer (minimum 0.01).
targetAccountId	string	Yes	Beneficiary bank account ID registered in Atlas.
purposeId	string	Yes	Purpose code identifier (obtained from /payments/purpose-codes).
customPaymentReference	string	No	Custom memo or invoice reference displayed on statements.
paymentId	string	No	Unique client-generated UUID for idempotent request handling.
supportingDocS3Key	string	No	S3 key returned by /documents/generate-upload-link if required.
scheduledDate	string	No	ISO 8601 UTC timestamp for future execution.
recurFrequency	string	No	Recurrence frequency: ONE_TIME, WEEKLY, MONTHLY.
sender	object	No	Underlying customer details when paying on behalf of an end-user.

Example: WALLET_PAYOUT

{
  "paymentType": "WALLET_PAYOUT",
  "sourceWalletId": "12345",
  "sourceAmount": 1000.50,
  "targetAccountId": "67890",
  "purposeId": "1",
  "customPaymentReference": "Invoice payment #12345",
  "paymentId": "550e8400-e29b-41d4-a716-446655440000"
}

2. WALLET_TO_BUSINESS (Transfer to Another Business)

Field	Type	Required	Description
paymentType	string	Yes	Must be "WALLET_TO_BUSINESS".
sourceWalletId	string	Yes	Funding wallet ID.
sourceAmount	number	Yes	Float amount to transfer.
targetCompanyId	string	Yes	Target company identifier on the platform.
purposeId	string	Yes	Purpose code identifier.
customPaymentReference	string	No	Custom memo or invoice reference.
paymentId	string	No	Unique idempotency UUID.

Example: WALLET_TO_BUSINESS

{
  "paymentType": "WALLET_TO_BUSINESS",
  "sourceWalletId": "12345",
  "sourceAmount": 500.00,
  "targetCompanyId": "comp-98765",
  "purposeId": "2",
  "customPaymentReference": "Service settlement Q3"
}

3. TRANSFER_WITHIN_WALLETS (Inter-Wallet Sweep)

Field	Type	Required	Description
paymentType	string	Yes	Must be "TRANSFER_WITHIN_WALLETS".
sourceWalletId	string	Yes	Source wallet ID.
sourceAmount	number	Yes	Float amount to sweep.
targetWalletId	string	Yes	Destination wallet ID.
customPaymentReference	string	No	Custom reference.
paymentId	string	No	Unique idempotency UUID.

Example: TRANSFER_WITHIN_WALLETS

{
  "paymentType": "TRANSFER_WITHIN_WALLETS",
  "sourceWalletId": "12345",
  "sourceAmount": 250.00,
  "targetWalletId": "67890",
  "customPaymentReference": "Liquidity top-up"
}

---

Response

Success Response (201 Created)

{
  "reference": "TO-29072023-114",
  "type": "WALLET_PAYOUT",
  "state": "REQUESTED"
}

Response Fields

Field	Type	Description
reference	string	Unique Atlas tracking reference (e.g. TO-29072023-114).
type	string	Standardized payment type: WALLET_PAYOUT, WALLET_TO_BUSINESS, TRANSFER_WITHIN_WALLETS, CONVERT_WITHIN_WALLETS, CONVERT_WALLET_PAYOUT.
state	string	Current lifecycle state: REQUESTED, DISPUTED, COMPLETED, REFUNDED, CANCELLED, ARCHIVED, SCHEDULED.

---

Code Examples

cURL

curl -X POST "https://api.ahrvo.network/banking/ibans/v2/payments/create" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentType": "WALLET_PAYOUT",
    "sourceWalletId": "12345",
    "sourceAmount": 1000.50,
    "targetAccountId": "67890",
    "purposeId": "1",
    "customPaymentReference": "Invoice #12345"
  }'

JavaScript (Fetch)

const response = await fetch('https://api.ahrvo.network/banking/ibans/v2/payments/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentType: 'WALLET_PAYOUT',
    sourceWalletId: '12345',
    sourceAmount: 1000.50,
    targetAccountId: '67890',
    purposeId: '1',
    customPaymentReference: 'Invoice #12345'
  })
});

const result = await response.json();
console.log('Payment Reference:', result.reference, 'State:', result.state);

Python (requests)

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/payments/create"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "paymentType": "WALLET_PAYOUT",
    "sourceWalletId": "12345",
    "sourceAmount": 1000.50,
    "targetAccountId": "67890",
    "purposeId": "1",
    "customPaymentReference": "Invoice #12345"
}

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

---

Interactive API Console

Test the endpoint directly in your browser: