Create a payment

Create a payment for an exact amount and get a hosted checkout URL for it.

Returns 201 with the new payment and its hosted checkout at url. When reference already names a live payment for the same amount and currency, it returns 200 with that payment instead, so a retried create never makes a second one.

Body

amount string Required

The price as a decimal string in currency, with at most two decimal places: "49.00" with USD is $49.00, and "49.5" and "49" are accepted too. A JSON number returns 400 invalid_request. From the equivalent of $1.00 up to 1,000,000.00 in the currency.
currency string

USD, EUR, GBP, CAD, AUD. Defaults to USD.
reference string

Your ID for the payment, such as an order number, up to 64 characters. It names one live payment: one that isn't canceled or expired.
description string

Shown in the checkout's details and on the receipt, up to 300 characters.
customer_email string

Links the payment to the customer with this email, adding one if needed. Without it, customer_id stays null until checkout collects an email.
success_url string

Where checkout sends the customer after paying, with payment_id added to its query. Use https://; http:// works only for localhost and 127.0.0.1. Defaults to the redirect in your checkout settings, then the receipt.
cancel_url string

Where to send the customer if they leave without paying. Use https://; http:// works only for localhost and 127.0.0.1.
expires_at timestamp

From 15 minutes to 30 days after 402pay receives the request, so give a 15-minute expiry a few seconds' margin. Defaults to 24 hours.
metadata object

Up to 20 string pairs of your own. Keys are up to 40 letters, digits, _, . or -. See metadata.
fee_payer string

business or customer. Defaults to your checkout settings.

Errors

400 invalid_request

A field is missing or out of range. field names it.
400 invalid_email

customer_email isn't a valid email address.
409 reference_in_use

The reference names a live payment for another amount or currency, or one that already received funds.
403 business_suspended

402pay suspended your business, so it can't take new payments.
409 not_accepting

Your business has no wallet yet, so it can't take payments.

Any request can also fail on its key or its body. See errors.

Request

curl -X POST "https://api.402pay.co/api/v1/payments" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.00",
    "currency": "USD",
    "reference": "order_1042",
    "description": "Pro plan, monthly",
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cart",
    "metadata": {
      "order_id": "1042"
    }
  }'

const response = await fetch("https://api.402pay.co/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.00",
    currency: "USD",
    reference: "order_1042",
    description: "Pro plan, monthly",
    success_url: "https://example.com/thanks",
    cancel_url: "https://example.com/cart",
    metadata: {
      order_id: "1042"
    }
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.402pay.co/api/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
    json={
        "amount": "49.00",
        "currency": "USD",
        "reference": "order_1042",
        "description": "Pro plan, monthly",
        "success_url": "https://example.com/thanks",
        "cancel_url": "https://example.com/cart",
        "metadata": {
            "order_id": "1042"
        }
    },
)
data = response.json()["data"]

Response201 Created

{
  "data": {
    "id": "pmt_QI02vLdJGd48hBbg",
    "kind": "payment",
    "status": "pending",
    "amount": "49.00",
    "currency": "USD",
    "fee_payer": "business",
    "customer_fee": "0.00",
    "amount_received": "0.00",
    "reporting": {
      "currency": "USD",
      "amount": "49.00",
      "fee": "0.00",
      "transaction_fee": "0.00",
      "customer_fee": "0.00",
      "net": "0.00"
    },
    "fee_rate_bps": 0,
    "method": {
      "rail": "crypto",
      "asset": null,
      "network": null,
      "amount": null,
      "expected_amount": null,
      "overpaid_amount": null,
      "from_address": null,
      "tx_hash": null,
      "explorer_url": null
    },
    "settlement": {
      "destination": "wallet",
      "asset": "USDC",
      "network": "ethereum",
      "amount": "0.00",
      "wallet_id": null,
      "address": null,
      "tx_hash": null,
      "explorer_url": null
    },
    "customer_id": null,
    "link_id": null,
    "url": "https://checkout.402pay.co/checkout/2jrsrcxv7k",
    "reference": "order_1042",
    "metadata": {
      "order_id": "1042"
    },
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cart",
    "expires_at": "2026-09-27T21:22:47.038Z",
    "canceled_at": null,
    "checkout_id": null,
    "description": "Pro plan, monthly",
    "country": "",
    "failure_code": null,
    "failure_message": null,
    "confirmed_at": null,
    "created_at": "2026-09-26T21:22:47.038Z",
    "updated_at": "2026-09-26T21:22:47.038Z",
    "events": [
      {
        "type": "created",
        "created_at": "2026-09-26T21:22:47.038Z",
        "data": null
      }
    ]
  }
}