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.

The process begins when a User sends a POST request to the Agentic Services /start_job endpoint with their input data.
The Agentic Service then initiates payment processing by sending a POST request to the Payment Services /payment endpoint.
The Payment Service generates and returns a Payment Identifier to the Agentic Service.
The Agentic Service responds to the User with both the Payment Identifier and a Job Identifier (a unique ID generated by the Agentic Service).
The User then makes a payment on the Blockchain using the provided Payment Identifier.
Meanwhile, the Masumi Payment Service actively monitors the Blockchain to check the payment status.
Once the Blockchain confirms the payment, it notifies the Masumi Payment Service.
The Agentic Service checks the payment status by sending a GET request to MasumiPaymentService's /payment endpoint.
The Payment Service responds with a "success" status.
Upon receiving the success status, the Agentic Service begins processing the actual job.
The User can check the job's progress by sending GET requests to the Agentic Services /status endpoint using their Job Identifier.
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.
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

Get information about a payment request. (admin access required)

get

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

Authorizations

Query parameters

limitnumber · min: 1 · max: 100Optional

The number of payments to return

Default: 10

cursorIdstringOptional

Used to paginate through the payments. If this is provided, cursorId is required

networkstring · enumRequired

The network the payments were made on

Possible values:

filterSmartContractAddressstring | nullableOptional

The smart contract address of the payment source

includeHistorystringOptional

Whether to include the full transaction and status history of the payments

Default: false

Responses

200

Payment status

application/json

400

Bad Request (possible parameters missing or invalid)

401

Unauthorized

500

Internal Server Error

get

GET /?network=Preprod HTTP/1.1
Host: payment
token: YOUR_API_KEY
Accept: */*

{
  "status": "success",
  "data": {
    "Payments": [
      {
        "id": "cuid_v2_auto_generated",
        "blockchainIdentifier": "blockchain_identifier",
        "createdAt": "1970-01-20T20:00:36.260Z",
        "updatedAt": "1970-01-20T20:00:36.260Z",
        "submitResultTime": "0",
        "unlockTime": "0",
        "externalDisputeUnlockTime": "0",
        "lastCheckedAt": null,
        "cooldownTime": 0,
        "payByTime": null,
        "cooldownTimeOtherParty": 0,
        "collateralReturnLovelace": null,
        "requestedById": "requester_id",
        "resultHash": "result_hash",
        "onChainState": null,
        "inputHash": "input_hash",
        "NextAction": {
          "requestedAction": "AuthorizeRefundRequested",
          "errorType": null,
          "errorNote": null,
          "resultHash": null
        },
        "CurrentTransaction": null,
        "TransactionHistory": [],
        "RequestedFunds": [
          {
            "amount": "10000000",
            "unit": ""
          }
        ],
        "PaymentSource": {
          "id": "payment_source_id",
          "network": "Preprod",
          "smartContractAddress": "address",
          "policyId": "policy_id",
          "paymentType": "Web3CardanoV1"
        },
        "WithdrawnForSeller": [],
        "WithdrawnForBuyer": [],
        "BuyerWallet": null,
        "SmartContractWallet": null,
        "metadata": null
      }
    ]
  }
}

Create a new payment request. (admin access required +PAY)

post

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

Authorizations

Body

inputHashstring · max: 250Required

The hash of the input data of the payment, should be sha256 hash of the input data, therefore needs to be in hex string format

networkstring · enumRequired

The network the payment will be received on

Possible values:

agentIdentifierstring · min: 57 · max: 250Required

The identifier of the agent that will be paid

paymentTypestring · enumRequired

The type of payment contract used

Possible values:

payByTimeany ofOptional

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

Default: 1970-01-01T12:00:00.000Z

string · dateOptional

string · date-timeOptional

submitResultTimeany ofOptional

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

Default: 1970-01-01T12:00:00.000Z

string · dateOptional

string · date-timeOptional

unlockTimeany ofOptional

The time after which the payment will be unlocked

string · dateOptional

string · date-timeOptional

externalDisputeUnlockTimeany ofOptional

The time after which the payment will be unlocked for external dispute

string · dateOptional

string · date-timeOptional

metadatastringOptional

Metadata to be stored with the payment request

identifierFromPurchaserstring · min: 14 · max: 26Required

The a unique nounce from the purchaser. Required to be in hex format

Responses

200

Payment request created

application/json

400

Bad Request (possible parameters missing or invalid)

401

Unauthorized

500

Internal Server Error

post

POST / HTTP/1.1
Host: payment
token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 371

{
  "agentIdentifier": "agent_identifier",
  "network": "Preprod",
  "inputHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "payByTime": "1970-01-20T20:00:26.260Z",
  "metadata": "(private) metadata to be stored with the payment request",
  "paymentType": "Web3CardanoV1",
  "submitResultTime": "1970-01-20T20:00:36.260Z",
  "identifierFromPurchaser": "aabbaabb11221122aabb"
}

{
  "status": "success",
  "data": {
    "id": "cuid_v2_auto_generated",
    "inputHash": "input_hash",
    "blockchainIdentifier": "blockchain_identifier",
    "createdAt": "1970-01-20T20:00:36.260Z",
    "updatedAt": "1970-01-20T20:00:36.260Z",
    "payByTime": "0",
    "submitResultTime": "0",
    "unlockTime": "0",
    "externalDisputeUnlockTime": "0",
    "lastCheckedAt": null,
    "requestedById": "requester_id",
    "resultHash": "result_hash",
    "onChainState": null,
    "NextAction": {
      "requestedAction": "AuthorizeRefundRequested",
      "errorType": null,
      "errorNote": null,
      "resultHash": null
    },
    "RequestedFunds": [
      {
        "amount": "10000000",
        "unit": ""
      }
    ],
    "PaymentSource": {
      "id": "payment_source_id",
      "policyId": "policy_id",
      "network": "Preprod",
      "smartContractAddress": "address",
      "paymentType": "Web3CardanoV1"
    },
    "BuyerWallet": null,
    "SmartContractWallet": null,
    "metadata": null,
    "WithdrawnForSeller": [],
    "WithdrawnForBuyer": []
  }
}

PreviousWallets NextPurchases

Last updated 5 months ago

Was this helpful?