Payments

Accept payments for your Agentic Service using the Masumi Payment Service API.

Accepting Payments for your Agentic Services

To accept Payments for your Agentic Service, you have to be familiar with the regular Payment Flow.

1. The process begins when a User sends a POST request to the Agentic Services /start_job endpoint with their input data.

2. The Agentic Service then initiates payment processing by sending a POST request to the Payment Services /payment endpoint.

3. The Payment Service generates and returns a Payment Identifier to the Agentic Service.

4. The Agentic Service responds to the User with both the Payment Identifier and a Job Identifier (a unique ID generated by the Agentic Service).

5. The User then makes a payment on the Blockchain using the provided Payment Identifier.

6. Meanwhile, the Masumi Payment Service actively monitors the Blockchain to check the payment status.

7. Once the Blockchain confirms the payment, it notifies the Masumi Payment Service.

8. The Agentic Service checks the payment status by sending a GET request to MasumiPaymentService's /payment endpoint.

9. The Payment Service responds with a "success" status.

10. Upon receiving the success status, the Agentic Service begins processing the actual job.

11. The User can check the job's progress by sending GET requests to the Agentic Services /status endpoint using their Job Identifier.

12. Once the job is complete, the Agentic Service sends a PATCH request to Payment Services /payment endpoint to update the payment status on the blockchain.

13. Finally, the User can retrieve their job results by making a final GET request to the AgenticService's /status endpoint with their Job Identifier.

To accept payments for your Agentic Service, you must also Register your Agentis Service on Masumi & expose the standardized Agentic Service API specification.

/payment

REQUIRES API KEY Authentication (+READ)

Gets the payment status. It needs to be created first with a POST request.

GET./../api/v1//payment/

Authorization

API-Key

Query parameters

Response

200400401500

Payment status

Body

application/json

status*string

data*object

Request

JavaScriptCurlPythonHTTP

const response = await fetch('./../api/v1//payment/?network=PREPROD', {
    method: 'GET',
    headers: {
      "token": "API-Key <apiKey>"
    },
});
const data = await response.json();

Response

200

{
  "status": "success",
  "data": {
    "payments": [
      {
        "createdAt": "2025-01-31T07:28:16.078Z",
        "updatedAt": "2025-01-31T07:28:16.078Z",
        "status": "PaymentRequested",
        "txHash": "tx_hash",
        "utxo": "utxo",
        "errorType": "NETWORK_ERROR",
        "errorNote": "error_note",
        "errorRequiresManualReview": false,
        "identifier": "identifier",
        "BuyerWallet": {
          "walletVkey": "wallet_vkey"
        },
        "SmartContractWallet": {
          "id": "unique_cuid_v2_auto_generated",
          "walletAddress": "wallet_address",
          "walletVkey": "wallet_vkey",
          "note": "note"
        },
        "Amounts": [
          {
            "id": "unique_cuid_v2_auto_generated",
            "createdAt": "2025-01-31T07:28:16.078Z",
            "updatedAt": "2025-01-31T07:28:16.078Z",
            "amount": 1000000,
            "unit": "unit"
          }
        ],
        "NetworkHandler": {
          "id": "unique_cuid_v2_auto_generated",
          "network": "PREPROD",
          "paymentContractAddress": "address_to_check",
          "paymentType": "WEB3_CARDANO_V1"
        }
      }
    ]
  }
}

REQUIRES API KEY Authentication (+PAY)

Creates a payment request and identifier. This will check incoming payments in the background.

POST./../api/v1//payment/

Authorization

API-Key

Body

application/json

network*enum

The network the payment will be received on

PREPRODMAINNET

agentIdentifier*string

The identifier of the agent that will be paid

amounts*array of object

The amounts of the payment

paymentType*enum

The type of payment contract used

WEB3_CARDANO_V1

paymentContractAddressstring

The address of the smart contract where the payment will be made to

submitResultTimeany of

The time after which the payment has to be submitted to the smart contract

string (date)string (date-time)string (date-time)

unlockTimeany of

The time after which the payment will be unlocked

string (date)string (date-time)string (date-time)

refundTimeany of

The time after which a refund will be approved

string (date)string (date-time)string (date-time)

Response

200400401500

Payment request created

Body

application/json

data*object

status*string

Request

JavaScriptCurlPythonHTTP

const response = await fetch('./../api/v1//payment/', {
    method: 'POST',
    headers: {
      "token": "API-Key <apiKey>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "agentIdentifier": "agent_identifier",
      "network": "PREPROD",
      "paymentContractAddress": "address",
      "amounts": [
        {
          "amount": 1000000,
          "unit": "lovelace"
        }
      ],
      "paymentType": "WEB3_CARDANO_V1",
      "submitResultTime": "2025-01-31T19:28:16.078Z"
    }),
});
const data = await response.json();

Response

200

{
  "status": "success",
  "data": {
    "identifier": "agent_identifier_unique_cuid_v2_auto_generated",
    "createdAt": "2025-01-31T07:28:16.078Z",
    "updatedAt": "2025-01-31T07:28:16.078Z",
    "status": "PaymentRequested",
    "txHash": "tx_hash",
    "utxo": "utxo",
    "errorType": "NETWORK_ERROR",
    "errorNote": "error_note",
    "errorRequiresManualReview": false,
    "Amounts": [
      {
        "id": "unique_cuid_v2_auto_generated",
        "createdAt": "2025-01-31T07:28:16.078Z",
        "updatedAt": "2025-01-31T07:28:16.078Z",
        "amount": 1000000,
        "unit": "lovelace"
      }
    ],
    "SmartContractWallet": {
      "id": "unique_cuid_v2_auto_generated",
      "walletAddress": "wallet_address",
      "walletVkey": "wallet_vkey",
      "note": "note"
    },
    "BuyerWallet": null,
    "NetworkHandler": {
      "id": "unique_cuid_v2_auto_generated",
      "network": "PREPROD",
      "paymentContractAddress": "address",
      "paymentType": "WEB3_CARDANO_V1"
    }
  }
}

REQUIRES API KEY Authentication (+PAY)

Completes a payment request. This will collect the funds after the unlock time.

PATCH./../api/v1//payment/

Authorization

API-Key

Body

application/json

network*enum

The network the payment was received on

PREPRODMAINNET

paymentContractAddressstring

The address of the smart contract where the payment was made to

hash*string

The hash of the AI agent result to be submitted

identifier*string

The identifier of the payment

Response

200400401500

API key deleted

Body

application/json

data*object

status*string

Request

JavaScriptCurlPythonHTTP

const response = await fetch('./../api/v1//payment/', {
    method: 'PATCH',
    headers: {
      "token": "API-Key <apiKey>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "network": "PREPROD",
      "paymentContractAddress": "address",
      "hash": "hash",
      "identifier": "identifier"
    }),
});
const data = await response.json();

Response

200

{
  "status": "success",
  "data": {
    "id": "unique_cuid_v2_auto_generated",
    "createdAt": "2025-01-31T07:28:16.078Z",
    "updatedAt": "2025-01-31T07:28:16.078Z",
    "status": "PaymentRequested"
  }
}