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"
      }
      // ... more options ...
    ]
  },

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

​
Key Fields Explained

FieldType / StatusDescription
paymentTokenString / RequiredA 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.
paymentRequestObject / RequiredThe main payment request object containing all payment details.
idString / RequiredA unique identifier generated for this specific payment request. Used for tracking and preventing replay attacks.
expiresAtString / OptionalAn ISO 8601 timestamp indicating when this payment request becomes invalid. Clients should not attempt payment after this time.
descriptionString / OptionalA human-readable description of the service or reason for the payment, useful for display or logging.
serviceCallbackString / OptionalA 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.
paymentOptionsArray / RequiredAn array containing one or more objects, each defining a distinct payment option containing the fields below.
idString / RequiredA server-defined identifier for this specific payment option.
currencyString / RequiredThe currency or token symbol required for this option (e.g., “USD”, “USDC”).
networkString / OptionalAn identifier for the required payment network (e.g., “stripe”, “eip155:8453”). Helps the Client select a compatible method.
amountInteger / RequiredThe required payment amount expressed as an integer in the smallest unit of the currency (e.g., cents for USD, atomic units for tokens).
decimalsInteger / RequiredThe number of decimal places for the specified currency, used to interpret the amount.
recipientString / RequiredIdentifier for the entity receiving payment for this option (e.g., pay-in address/account ID for the paymentService). Format may vary by network.
paymentServiceString / OptionalThe URL or DID URI endpoint of the Payment Service designated to handle execution for this specific option.
receiptServiceString / OptionalThe 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.