Sign in
Payments

Create a payment challenge

Changed on

Create an x402 payment challenge (the payee side of a payment). The pay_to address is resolved server-side from your registered default payout address for the network, never from the request. The response carries the nonce_binding and payment_requirements the payer needs to sign; hand the whole challenge object to the payer (for example in an email reply). Amounts are in token base units (USDC has 6 decimals, so "10000" is 0.01 USDC).

post/x402/challenges

Request

  • Base URL: https://api.primitive.dev/v1
  • URL: https://api.primitive.dev/v1/x402/challenges
  • Auth: HTTP bearer

Request body

amountstring required

Amount to collect, in token base units. USDC has 6 decimals, so "10000" is 0.01 USDC.

network'base' | 'base-sepolia' required
payer_orgstring uuid

The org id allowed to pay this challenge (on-net binding). Optional.

expires_ininteger

Seconds until the challenge expires. Defaults to 3600.

resourcestring uri

Optional URL identifying what is being paid for. Defaults to a synthetic x402:challenge:<id> identifier.

descriptionstring

Optional human-readable description of the payment.

Response

Challenge created

successboolean required

Example response

{
  "data": {
    "payment_requirements": {
      "scheme": "exact"
    }
  }
}

Changes

  • 52138fa51360Revision changes
    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

  • 22d1dfc68434Revision changes
    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status