Developers · Reference

API reference

The Paytab API is organised around REST. It has predictable resource-oriented URLs, accepts form-encoded or JSON request bodies, and returns JSON-encoded responses with standard HTTP status codes.

Authentication Code examples

Payments

POST/v1/payments

Create a payment

Charge a customer's payment method. Returns a PaymentIntent you can confirm on the client.

Parameters

amountintegerRequired
Amount in the smallest currency unit (e.g. pence).
currencystringRequired
Three-letter ISO code, e.g. gbp.
customerstring
ID of an existing customer to charge.
descriptionstring
Arbitrary string shown on the merchant dashboard.
metadataobject
Up to 50 key-value pairs of your own data.

Request

curl https://api.paytab.co.uk/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -d amount=2500 \
  -d currency=gbp \
  -d "description=Order #4102"

Response

{
  "id": "pay_1P4kJ9L2c...",
  "object": "payment",
  "amount": 2500,
  "currency": "gbp",
  "status": "requires_confirmation",
  "client_secret": "pay_1P4kJ9L2c..._secret_x",
  "created": 1751824512,
  "livemode": false
}

GET/v1/payments/{id}

Retrieve a payment

Fetch the current state of a payment by its ID.

Request

curl https://api.paytab.co.uk/v1/payments/pay_1P4kJ9L2c \
  -H "Authorization: Bearer sk_test_..."

Response

{
  "id": "pay_1P4kJ9L2c...",
  "amount": 2500,
  "currency": "gbp",
  "status": "succeeded",
  "amount_received": 2500,
  "created": 1751824512
}

POST/v1/payments/{id}/refund

Refund a payment

Refund a payment in full or in part. Fees are returned proportionally.

Parameters

amountinteger
Partial amount to refund. Omit for full refund.
reasonstring
duplicate, fraudulent or requested_by_customer.

Request

curl https://api.paytab.co.uk/v1/payments/pay_1P4kJ9L2c/refund \
  -H "Authorization: Bearer sk_test_..." \
  -d amount=1000

Response

{
  "id": "re_1P4kL8L2c...",
  "payment": "pay_1P4kJ9L2c...",
  "amount": 1000,
  "currency": "gbp",
  "status": "succeeded"
}

Customers

POST/v1/customers

Create a customer

Store a customer to reuse payment methods, receipts and subscriptions.

Parameters

emailstring
Customer email address.
namestring
Full name of the customer.
phonestring
E.164 phone number.

Request

curl https://api.paytab.co.uk/v1/customers \
  -H "Authorization: Bearer sk_test_..." \
  -d email="ada@example.com" \
  -d name="Ada Lovelace"

Response

{
  "id": "cus_NffrFeUf...",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "created": 1751824512
}

Payment links

POST/v1/payment_links

Create a payment link

Generate a shareable hosted URL that accepts payments without any code on your side.

Parameters

line_itemsarrayRequired
Products and quantities to charge.
after_completionobject
Where to redirect after checkout.

Request

curl https://api.paytab.co.uk/v1/payment_links \
  -H "Authorization: Bearer sk_test_..." \
  -d "line_items[0][price]=price_1P..." \
  -d "line_items[0][quantity]=1"

Response

{
  "id": "plink_1P4k...",
  "url": "https://buy.paytab.co.uk/test_aEU...",
  "active": true
}

Webhooks

GET/v1/events

List events

Paginated feed of every event on your account for the last 30 days.

Request

curl "https://api.paytab.co.uk/v1/events?limit=10" \
  -H "Authorization: Bearer sk_test_..."

Response

{
  "object": "list",
  "has_more": true,
  "data": [
    { "id": "evt_1P...", "type": "payment.succeeded", "created": 1751824512 }
  ]
}