Creating Purchases

Create a payment and get a checkout URL for the customer.

Endpoint

POST /api/purchases/create/

Request Body

Provide exactly one of email_address or ref_id. Include application in every request. This identifier is safe to send as the tenant selector; requests still must be signed with that application's API_SECRET.

Signing Requests

Code

purchases/create and purchases/cancel both require a signed request, verified against your API_SECRET.

// Bun
import { createHmac } from 'crypto';

const timestamp = Math.floor(Date.now() / 1000);
const body = `application=${APPLICATION_REF}&sku=${sku}&ref_id=${uid}&timestamp=${timestamp}`;
const sig  = createHmac('sha512', API_SECRET).update(body).digest('hex');

await fetch('https://pay.with.pink/api/purchases/create/', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/x-www-form-urlencoded',
		'X-PWP-Signature': sig,
	},
	body,
});

Details

The body must include a timestamp (unix seconds) within five minutes of server time and use application/x-www-form-urlencoded. JSON requests are rejected before signature verification. PWP signs the exact raw body bytes, so serialize the body once, sign that string, and send it without re-encoding. The signature uses your application's API_SECRET.

PWP also uses X-PWP-Signature for outbound webhooks, but those use the separate IPN_SECRET and are signed by PWP. Do not use the webhook secret to sign API requests.

API_SECRET isn't generated automatically for an application that existed before this signing requirement was added. Ask PWP to generate one from the admin if requests fail with API authentication not configured (500).

Response

{
  "id": "abc123",
  "invoice": "https://pay.with.pink/purchases/abc123/",
  "location": "https://www.paypal.com/checkoutnow?token=...",
  "status": "PENDING"
}

Contract change (2026-07): location used to always carry the PayPal checkout URL for USD purchases. It now carries the requested gateway URL, or the invoice URL when no processor was requested and payment is still pending. Use invoice as the stable customer-facing URL; location is null for purchases that are already paid, such as $0 products.

Status Lifecycle

• PENDING — awaiting customer payment
• PAID — payment captured; recurring purchases create or extend a subscription, while one-time purchases complete without one
• CANCELED — customer cancelled at checkout
• EXPIRED — payment window expired

Free Products ($0)

Products priced at $0 are resolved immediately without a payment gateway. The response will have status: "PAID" and location: null. A one-time $0 product is still a completed purchase and emits purchase.completed to the configured IPN URL.

When a product has multiple prices in the same currency, pass the matching subscription_type (MONTH, YEAR, or ONE_TIME) to select the intended price. In particular, use ONE_TIME when choosing a one-time price alongside recurring prices. When this field is omitted, PWP keeps the existing first matching price behavior for compatibility.

A tenant can turn free subscriptions off (application.free_subscriptions = 0, admin-only toggle — see .taskflow/notes/free-subscriptions.md). Once off, purchases/create refuses every new $0 purchase for that tenant with a 403 (see Errors below); existing $0 subscriptions are unaffected until their current term ends (they wind down via subscription.expired, not retroactively canceled — see Webhooks).

Errors

Cancelling Purchases

POST /api/purchases/cancel/ cancels every ACTIVE subscription for the given account and product. It requires the same Signing Requests scheme as purchases/create.

Include application in every request. The account must already exist — this endpoint never creates one. An unknown account or a sku with no matching product both return the same uniform error, to avoid leaking which accounts exist.

{
  "subscriptions": 1
}