Payment Request

The JSON Payment Request payload is central to ACK-Pay interactions. Its origin and handling differ slightly depending on the payment sequence:

Server-Initiated Sequence: When payment is required by a Server, it generates and sends this payload structure to the Client to communicate the requirement. This payload is designed to be transport-agnostic: while delivered via the standard 402 status code when HTTP is employed, it can also be delivered over other protocols (e.g., A2A messages, WebSockets) and is not limited to HTTP.
Client-Initiated Sequence: When payment is initiated by a Client based on a known obligation, the Client constructs this payload. The Client might parse unstructured data (like an invoice, user instruction, or web checkout summary) and potentially interact with a Payment Service API to help formulate the standardized payload structure before initiating the payment execution.

In both cases, the structure allows the offering of one or more ways for the Client to fulfill the payment requirement via a designated Payment Service.

Payload Structure

Every Payment Request payload contains essential properties:

{
  "paymentRequest": {
    // Top-level details applying to the overall service request
    "id": "unique-request-id-123",
    "expiresAt": "2025-05-20T23:59:59Z",
    "description": "Premium API access (100 credits)",
    "serviceCallback": "https://service.example.com/webhook/payment-complete",

    // Array of acceptable payment methods offered
    "paymentOptions": [
      {
        // Option 1: USDC on Base network
        "id": "usdc-base",
        "currency": "USDC",
        "network": "eip155:8453",
        "amount": 10000000,
        "decimals": 6,
        "recipient": "eip155:8453:0xRecipientAddressOnBase",
        "paymentService": "https://payments.example.com/base",
        "receiptService": "https://receipts.example.com/base"
      },
      {
        // Option 2: Stripe payment
        "id": "stripe-usd",
        "currency": "USD",
        "network": "stripe",
        "amount": 1000,
        "decimals": 2,
        "recipient": "acct_StripeAccountID",
        "paymentService": "https://payments.example.com/stripe",
        "receiptService": "https://receipts.example.com/stripe"
      },
      {
        // Option 3: USDC on Solana devnet
        "id": "usdc-solana-devnet",
        "currency": "USDC",
        "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
        "amount": 10000000,
        "decimals": 6,
        "recipient": "ExAmPLeSoLaNaAddReSS111111111111111111111111",
        "receiptService": "https://receipts.example.com/solana"
      }
      // ... more options ...
    ]
  },

  // Signed token covering the paymentRequest structure above
  "paymentRequestToken": "signed-representation-of-the-entire-object"
}

Key Fields Explained

Field	Type / Status	Description
`paymentRequestToken`	String / Required	A cryptographic token (e.g., JWT) generated by the Server, signing the `paymentRequest` payload to ensure integrity and authenticity. This token is verified by several participants in the protocol.
`paymentRequest`	Object / Required	The main payment request object containing all payment details.
`id`	String / Required	A unique identifier generated for this specific payment request. Used for tracking and preventing replay attacks.
`expiresAt`	String / Optional	An ISO 8601 timestamp indicating when this payment request becomes invalid. Clients should not attempt payment after this time.
`description`	String / Optional	A human-readable description of the service or reason for the payment, useful for display or logging.
`serviceCallback`	String / Optional	A URL or DID URI that the Payment Service or Receipt Service can use to notify the original Server upon successful payment confirmation. Enables asynchronous workflows.
`paymentOptions`	Array / Required	An array containing one or more objects, each defining a distinct payment option containing the fields below.
`id`	String / Required	A server-defined identifier for this specific payment option.
`currency`	String / Required	The currency or token symbol required for this option (e.g., “USD”, “USDC”).
`network`	String / Optional	An identifier for the required payment network (e.g., “stripe”, “eip155:8453”). Helps the Client select a compatible method.
`amount`	Integer / Required	The required payment amount expressed as an integer in the smallest unit of the currency (e.g., cents for USD, atomic units for tokens).
`decimals`	Integer / Required	The number of decimal places for the specified `currency`, used to interpret the `amount`.
`recipient`	String / Required	Identifier for the entity receiving payment for this option (e.g., pay-in address/account ID for the `paymentService`). Format may vary by network.
`paymentService`	String / Optional	The URL or DID URI endpoint of the Payment Service designated to handle execution for this specific option.
`receiptService`	String / Optional	The URL or DID URI endpoint of the Receipt Service designated to issue/verify receipts for payments made using this option.

Payment Service Abstraction

The paymentOptions listed in a Payment Request define how the designated Payment Service accepts funds from the Client. These options do not necessarily dictate the final currency or settlement account required by the Server Agent receiving the service request. The Payment Service acts as a crucial intermediary. It can offer numerous pay-in options (different currencies, networks, or payment methods) suitable for various Clients. Subsequently, the Payment Service handles the necessary bridging, currency conversions (FX), or other transformations required to settle the payment to the Server Agent in their desired currency and account type. This abstraction provides key benefits:

Server Privacy: The Server does not need to expose its final settlement account details directly to the Client.
Client Flexibility: The Client can pay using a method convenient for it, even if it differs from the Server’s preferred settlement method.

If fees are associated with bridging, FX conversions, or other transformations performed by the Payment Service, these should be communicated transparently to the Client during the payment negotiation or execution process.

ACK Overview

ACK-ID

ACK-Pay

Resources

Payload Structure

Key Fields Explained

Payment Service Abstraction

​Payload Structure

​Key Fields Explained

​Payment Service Abstraction

Payload Structure

Key Fields Explained

Payment Service Abstraction