POST
/
payments
/
register
curl --request POST \
  --url https://api.magebank.ai/payments/register \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "senderagentid": "<string>",
  "receiveragentid": "<string>",
  "paymentdetails": {
    "amount": 123,
    "currency": "<string>",
    "method": "<string>"
  },
  "name": "<string>",
  "contactdetails": {
    "email": "<string>",
    "phoneNumber": "<string>"
  },
  "tags": [
    {}
  ]
}'
{
  "id": "payee_wDG5cavUCoK53uvFzTvkey",
  "name": "Vendor XYZ Payment",
  "type": "EXTERNAL",
  "status": "New",
  "approvalstatus": "Waiting",
  "approvalRequired": true,
  "createdat": "2025-04-17T10:28:18.512792",
  "txHash": null
}

Agent Transactions: Create payments between agents with automatic application of approval rules based on the sender’s configuration.

​
Request Headers

​
x-api-key
string
required

Your API key for authentication

​
Request Body

​
senderagentid
string
required

ID of the agent sending the payment

​
receiveragentid
string
required

ID of the agent receiving the payment

​
paymentdetails
object
required
​
name
string
required

Name or description of the payment

​
contactdetails
object
​
tags
array

Tags or categories for the payment

​
Response

​
id
string

Unique payment identifier in short ID format

​
name
string

Name or description of the payment

​
type
string

Type of payment (EXTERNAL or INTERNAL)

​
status
string

Current status of the payment (New, Pending, or Confirmed)

​
createdat
string

Timestamp when the payment was created

​
approvalRequired
boolean

Whether this payment requires approval

​
approvalstatus
string

Current approval status (Waiting, Pending, Approved, or Decline)

​
txHash
string

Transaction hash on the blockchain (if processed immediately)

{
  "id": "payee_wDG5cavUCoK53uvFzTvkey",
  "name": "Vendor XYZ Payment",
  "type": "EXTERNAL",
  "status": "New",
  "approvalstatus": "Waiting",
  "approvalRequired": true,
  "createdat": "2025-04-17T10:28:18.512792",
  "txHash": null
}

​
Status Codes

Status CodeDescription
200Payment registered successfully
400Bad Request - Invalid parameters or insufficient balance
401Unauthorized - Invalid or missing API key
404Not Found - Agent not found
500Internal Server Error

Payment Limits: The payment will fail if it exceeds the sender agent’s transaction or daily limits.

Payment Types: Use “EXTERNAL” for payments to recipients outside your agent network and “INTERNAL” for payments between your own agents.

Approval Flow: Payments requiring approval will need to be approved using the Approve Payment endpoint before they are processed.