Quickstart

This guide walks you through a full payment flow with the API Store: create a payment link, send your customer to checkout, and confirm the payment.

Prerequisites

A PapelShip account with at least one store
An API key (psa_...), its numeric API Key ID, and your 12-character Store Hash ID

You can find all three values in the PapelShip dashboard under your store’s API settings.

Create a payment link

Send the order amount to the payment links endpoint. Add an Idempotency-Key header so retries never create duplicate invoices.

curl -X POST https://app.papelship.com/api/api-store/payment-links \
  -H "Authorization: Bearer psa_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b9e8f1a-3c2d-4e5f-6a7b-8c9d0e1f2a3b" \
  -d '{
    "storeHashId": "0bHQn0bU2dei",
    "apiKeyId": 42,
    "amount": 49.99,
    "currency": "USD",
    "customer_email": "buyer@example.com",
    "description": "Order #1042",
    "redirect_url": "https://yourdomain.com/checkout/success"
  }'

const res = await fetch("https://app.papelship.com/api/api-store/payment-links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPELSHIP_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    storeHashId: "0bHQn0bU2dei",
    apiKeyId: 42,
    amount: 49.99,
    currency: "USD",
    customer_email: "buyer@example.com",
    redirect_url: "https://yourdomain.com/checkout/success",
  }),
});
const { invoice, checkout_url } = await res.json();

import os, uuid, requests

res = requests.post(
    "https://app.papelship.com/api/api-store/payment-links",
    headers={
        "Authorization": f"Bearer {os.environ['PAPELSHIP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "storeHashId": "0bHQn0bU2dei",
        "apiKeyId": 42,
        "amount": 49.99,
        "currency": "USD",
        "customer_email": "buyer@example.com",
        "redirect_url": "https://yourdomain.com/checkout/success",
    },
)
data = res.json()

Redirect your customer

The response contains a checkout_url. Send your customer there to pay by card, Papara, bank transfer, or crypto.

Response

{
  "success": true,
  "invoice": {
    "id": "aB9xK12Lp9012345678901234",
    "amount": 49.99,
    "currency": "USD",
    "status": "awaiting_method",
    "expires_at": "2026-08-09T02:18:00.000Z"
  },
  "checkout_url": "https://app.papelship.com/checkout-gateway/aB9xK12Lp9012345678901234"
}

Store invoice.id with your order. You need it to check the payment.

Confirm the payment

When the customer returns to your redirect_url, verify the payment on your server. Never trust the redirect alone.

curl "https://app.papelship.com/api/api-store/v1/payment-links/check?invoiceId=aB9xK12Lp9012345678901234" \
  -H "Authorization: Bearer psa_your_api_key"

Fulfill the order only when payment.is_paid is true.

Keep your API key on your server. Never ship it in browser code, mobile apps, or desktop clients.

Get started

Core concepts

Prerequisites

Next steps

Crypto invoices

API Store reference

​Prerequisites

​Next steps

Crypto invoices

API Store reference

Prerequisites

Next steps