## How it works

This reference organizes the payment-facing HTTP resources. Send api-key on server requests and select the shop when a route requires shop scope.

## Implementation

Use the endpoint tables below for payments, customers, methods, refunds, disputes, subscriptions, products, invoices, payouts and webhook deliveries. Payment amounts are integers in minor units. Prefer retrieved resources and signed webhooks when reconciling asynchronous operations. Endpoint and optional-field availability follow the deployed SpicePay release; the public API should be tested in a properly configured sandbox before shipping an integration.

## Authentication

| Key | Starts with | Use |
| --- | --- | --- |
| Secret key | `prd_` | Server-side only; never in a browser or app |
| Publishable key | `pk_prd_` | Browser-side, with the payment's `client_secret` |

## Payments

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/payments` | Create a payment or hosted checkout |
| `GET` | `/payments/{payment_id}` | Retrieve; `?force_sync=true` asks the processor first |
| `POST` | `/payments/{payment_id}` | Update before confirmation |
| `POST` | `/payments/{payment_id}/confirm` | Confirm with a payment method |
| `POST` | `/payments/{payment_id}/capture` | Capture an authorization |
| `POST` | `/payments/{payment_id}/cancel` | Cancel or release an authorization |
| `POST` | `/payments/list` | Filter and page through payments |
| `GET` | `/payments/{payment_id}/attempts` | Processor attempts and their errors |
| `GET` | `/payments/{payment_id}/status-history` | Status timeline |
| `GET` | `/payments/{payment_id}/lines` | Product lines and refundable balances |
| `GET` | `/payments/{payment_id}/routing-decisions` | Why a connector was chosen |

## Customers and saved methods

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/customers` | Create a customer |
| `GET` | `/customers/list` | List customers |
| `GET` | `/customers/{customer_id}` | Retrieve |
| `POST` | `/customers/{customer_id}` | Update |
| `DELETE` | `/customers/{customer_id}` | Redact personal data and delete saved methods |
| `GET` | `/customers/{customer_id}/payment-methods` | List saved methods |
| `POST` | `/customers/{customer_id}/payment-methods/{payment_method_id}/default` | Set the default method |
| `DELETE` | `/payment-methods/{payment_method_id}` | Delete a saved method |
| `GET` | `/customers/{customer_id}/mandates` | List a customer's mandates |
| `GET` | `/mandates/{mandate_id}` | Retrieve a mandate |
| `GET` | `/mandates/list` | List mandates |
| `POST` | `/mandates/revoke/{mandate_id}` | Revoke a mandate |

## Refunds and disputes

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/refunds` | Refund fully, partly or by product line |
| `GET` | `/refunds/{refund_id}` | Retrieve; `?force_sync=true` asks the processor first |
| `POST` | `/refunds/{refund_id}` | Update `reason` or `metadata` |
| `POST` | `/refunds/list` | Filter refunds |
| `GET` | `/disputes/list` | List disputes |
| `GET` | `/disputes/{dispute_id}` | Retrieve a dispute |
| `POST` | `/disputes/accept/{dispute_id}` | Accept a dispute |
| `POST` | `/files` | Upload an evidence file |
| `PUT` | `/disputes/evidence` | Attach an evidence file |
| `GET` | `/disputes/evidence/{dispute_id}` | List attached evidence |
| `DELETE` | `/disputes/evidence` | Remove attached evidence |
| `POST` | `/disputes/evidence` | Submit evidence |
| `GET` | `/disputes/paypal/cases` | List PayPal seller cases |
| `POST` | `/disputes/paypal/import` | Import PayPal cases |
| `GET` | `/disputes/paypal/cases/{case_id}` | Retrieve a PayPal case |
| `GET` | `/disputes/paypal/cases/{case_id}/history` | A PayPal case's history |
| `GET` / `POST` | `/disputes/paypal/cases/{case_id}/actions` | List or take actions on a PayPal case |

## Subscriptions

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/subscriptions/create` | Create for the buyer to confirm on the hosted checkout |
| `POST` | `/subscriptions` | Create and confirm in one call |
| `POST` | `/subscriptions/{subscription_id}/confirm` | Confirm a created subscription |
| `GET` | `/subscriptions/{subscription_id}` | Retrieve |
| `GET` | `/subscriptions/list` | List |
| `GET` | `/subscriptions/{subscription_id}/capabilities` | Actions the processor supports |
| `POST` | `/subscriptions/{subscription_id}/pause` | Pause |
| `POST` | `/subscriptions/{subscription_id}/resume` | Resume |
| `POST` | `/subscriptions/{subscription_id}/cancel` | Cancel now or later |
| `PUT` | `/subscriptions/{subscription_id}/update` | Change plan |
| `GET` | `/subscriptions/{subscription_id}/invoices` | Billing cycles |
| `POST` | `/subscriptions/{subscription_id}/sync` | Refresh from the processor |
| `GET` | `/subscriptions/items` | Processor plans and add-ons |
| `GET` | `/subscriptions/estimate` | Preview a processor plan's charge |
| `POST` | `/subscriptions/adopt` | Adopt a subscription created at the processor |
| `POST` | `/subscriptions/import/preview` | Preview subscriptions to adopt |
| `POST` | `/subscriptions/import/apply` | Adopt the reviewed subscriptions |

## Products

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/products` | Create a product with its prices |
| `GET` | `/products/list` | List the shop's catalog |
| `GET` / `POST` / `DELETE` | `/products/{product_id}` | Retrieve, update or delete |
| `POST` | `/products/{product_id}/archive` | Take off sale |
| `POST` | `/products/{product_id}/restore` | Put back on sale |
| `POST` | `/products/images` | Upload a product image |
| `POST` | `/products/{product_id}/prices` | Add a price |
| `POST` | `/products/{product_id}/prices/{price_id}` | Change a price's nickname, metadata or default flag |
| `POST` | `/products/{product_id}/prices/{price_id}/archive` | Archive a price |
| `POST` | `/products/{product_id}/addon-groups` | Add an add-on group |
| `POST` / `DELETE` | `/products/{product_id}/addon-groups/{group_id}` | Replace or remove an add-on group |
| `POST` | `/products/{product_id}/bundle` | Set a bundle's components |
| `GET` | `/products/{product_id}/sales` | Sales and refunds of one product |
| `GET` | `/products/categories/list` | List categories |
| `POST` | `/products/categories` | Create a category |
| `POST` | `/products/import/preview` | Preview an import from a processor |
| `POST` | `/products/import/apply` | Apply the reviewed import |
| `GET` | `/products/provider-accounts` | Catalog actions per connected processor account |

## Invoices

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/invoices` | Create from a payment or billing cycle |
| `GET` | `/invoices` | List invoices and credit notes |
| `GET` / `PATCH` / `DELETE` | `/invoices/{invoice_id}` | Retrieve, edit or delete a draft |
| `POST` | `/invoices/{invoice_id}/finalize` | Issue and render the PDF |
| `POST` | `/invoices/{invoice_id}/void` | Void an issued invoice |
| `POST` | `/invoices/{invoice_id}/credit-note` | Create a credit note |
| `GET` | `/invoices/{invoice_id}/pdf` | Download the PDF |
| `POST` | `/invoices/{invoice_id}/share-link` | Create a link for the buyer |
| `GET` / `PUT` | `/invoice-settings` | Merchant defaults |
| `GET` / `PUT` | `/invoice-settings/profiles/{profile_id}` | Shop overrides |
| `GET` / `PUT` | `/invoice-settings/tax-rules` | Merchant tax rules |
| `GET` / `PUT` / `DELETE` | `/invoice-settings/profiles/{profile_id}/tax-rules` | Shop tax rules |
| `POST` | `/invoice-settings/tax-rules/evaluate` | Preview which tax rule applies to a buyer |

## Payouts

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/payouts/create` | Create a payout |
| `GET` / `PUT` | `/payouts/{payout_id}` | Retrieve or update |
| `POST` | `/payouts/{payout_id}/confirm` | Confirm |
| `POST` | `/payouts/{payout_id}/cancel` | Cancel |
| `POST` | `/payouts/{payout_id}/fulfill` | Fulfil |
| `GET` | `/payouts/list` | List payouts |
| `POST` | `/payouts/list` | Filter payouts |

## Webhook deliveries

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/events/{merchant_id}` | List events |
| `GET` | `/events/{merchant_id}/{event_id}/attempts` | Delivery attempts of an event |
| `POST` | `/events/{merchant_id}/{event_id}/retry` | Send an event again |

## Related guides

- [Errors](/docs/payment-api/error-codes/)
- [Test and live payments](/docs/general/test-and-live/)
- [Accept payments](/docs/payment-api/accept-payments/)
- [Hosted checkout](/docs/payment-api/hosted-checkout/)
- [Customers & saved methods](/docs/payment-api/customers/)

## Request examples

```bash
curl https://api.spicepay.net/payments/pay_xxxxx \
  -H 'api-key: YOUR_API_KEY'
```