API Reference

Authentication

The Paebs API uses API keys to authenticate requests. You can view and manage your API keys in your Dashboard. Authentication is performed via HTTP Bearer auth. Provide your API key as the bearer token value.

Authentication Header

Authorization: Bearer sk_live_4eC39HqLyjWDarjtT1zdp7dc

Keep your API keys secure! Do not share them in public repositories or client-side code.

Errors

Paebs uses conventional HTTP response codes to indicate success or failure. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`402`	Payment Required - Card declined
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Server Error - Something went wrong

Pagination

All list endpoints support pagination using limit and starting_after parameters. The response includes a has_more boolean indicating if more results exist.

GET /v1/payments?limit=10&starting_after=pay_abc123

List with pagination

Request Body

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "url": "/v1/payments"
}

Payments

Payment objects represent a single payment attempt. Create a Payment to charge a card. You can retrieve individual payments or list all payments.

Create a Payment

POST /v1/payments

Create a new payment

Request Body

{
  "amount": 2500,
  "currency": "gbp",
  "source": "tok_visa",
  "description": "Order #12345",
  "metadata": {
    "order_id": "12345"
  }
}

Response

{
  "id": "pay_1NqL9JABC123def456",
  "object": "payment",
  "amount": 2500,
  "currency": "gbp",
  "status": "succeeded",
  "source": {
    "id": "card_1NqL9JABC789",
    "brand": "visa",
    "last4": "4242"
  },
  "created": 1693425365,
  "description": "Order #12345"
}

Retrieve a Payment

GET /v1/payments/{id}

Retrieve a payment by ID

Response

{
  "id": "pay_1NqL9JABC123def456",
  "object": "payment",
  "amount": 2500,
  "currency": "gbp",
  "status": "succeeded",
  "created": 1693425365
}

List all Payments

GET /v1/payments

List all payments with optional filters

Response

{
  "object": "list",
  "data": [
    {
      "id": "pay_1NqL9JABC123def456",
      "amount": 2500,
      "status": "succeeded"
    }
  ],
  "has_more": true
}

Capture a Payment

POST /v1/payments/{id}/capture

Capture an authorized payment

Request Body

{
  "amount": 2000
}

Response

{
  "id": "pay_1NqL9JABC123def456",
  "status": "succeeded",
  "captured": true,
  "amount_captured": 2000
}

Cancel a Payment

POST /v1/payments/{id}/cancel

Cancel an uncaptured payment

Response

{
  "id": "pay_1NqL9JABC123def456",
  "status": "canceled"
}

Refunds

Refund objects allow you to refund a payment that has been previously created. Funds are returned to the customer's card.

Create a Refund

POST /v1/refunds

Create a full or partial refund

Request Body

{
  "payment": "pay_1NqL9JABC123def456",
  "amount": 1000,
  "reason": "requested_by_customer"
}

Response

{
  "id": "re_1NqMAABC123xyz789",
  "object": "refund",
  "amount": 1000,
  "currency": "gbp",
  "payment": "pay_1NqL9JABC123def456",
  "status": "succeeded",
  "created": 1693426000
}

Retrieve a Refund

GET /v1/refunds/{id}

Retrieve a refund by ID

Response

{
  "id": "re_1NqMAABC123xyz789",
  "object": "refund",
  "amount": 1000,
  "status": "succeeded"
}

List all Refunds

GET /v1/refunds

List all refunds

Response

{
  "object": "list",
  "data": [...],
  "has_more": false
}

Customers

Customer objects allow you to save payment methods and track payments across multiple sessions.

Create a Customer

POST /v1/customers

Create a new customer

Request Body

{
  "email": "customer@example.com",
  "name": "John Smith",
  "phone": "+447123456789",
  "metadata": {
    "internal_id": "usr_123"
  }
}

Response

{
  "id": "cus_1NqNBBBC456abc",
  "object": "customer",
  "email": "customer@example.com",
  "name": "John Smith",
  "created": 1693427000
}

Retrieve a Customer

GET /v1/customers/{id}

Retrieve a customer by ID

Response

{
  "id": "cus_1NqNBBBC456abc",
  "object": "customer",
  "email": "customer@example.com",
  "name": "John Smith"
}

Update a Customer

PATCH /v1/customers/{id}

Update customer details

Request Body

{
  "email": "newemail@example.com"
}

Response

{
  "id": "cus_1NqNBBBC456abc",
  "email": "newemail@example.com"
}

Delete a Customer

DELETE /v1/customers/{id}

Delete a customer

Response

{
  "id": "cus_1NqNBBBC456abc",
  "object": "customer",
  "deleted": true
}

List all Customers

GET /v1/customers

List all customers

Response

{
  "object": "list",
  "data": [...],
  "has_more": true
}

Cards

Card objects represent a customer's payment card. You can save cards to customers for future payments.

Create a Card

POST /v1/customers/{customer_id}/cards

Add a card to a customer

Request Body

{
  "source": "tok_visa"
}

Response

{
  "id": "card_1NqOCCCC789xyz",
  "object": "card",
  "brand": "visa",
  "last4": "4242",
  "exp_month": 12,
  "exp_year": 2025,
  "customer": "cus_1NqNBBBC456abc"
}

Retrieve a Card

GET /v1/customers/{customer_id}/cards/{id}

Retrieve a card

Response

{
  "id": "card_1NqOCCCC789xyz",
  "brand": "visa",
  "last4": "4242"
}

Delete a Card

DELETE /v1/customers/{customer_id}/cards/{id}

Delete a card from customer

Response

{
  "id": "card_1NqOCCCC789xyz",
  "deleted": true
}

Tokens

Tokens are used to securely collect card details from your frontend without sensitive data touching your server.

Create a Token

POST /v1/tokens

Create a card token (use with Paebs.js)

Request Body

{
  "card": {
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2025,
    "cvc": "123"
  }
}

Response

{
  "id": "tok_1NqPDDDD123abc",
  "object": "token",
  "card": {
    "brand": "visa",
    "last4": "4242"
  },
  "created": 1693428000,
  "used": false
}

Retrieve a Token

GET /v1/tokens/{id}

Retrieve a token

Response

{
  "id": "tok_1NqPDDDD123abc",
  "object": "token",
  "used": false
}

Accounts

Account objects represent your Paebs account. Manager accounts can create sub-accounts.

Retrieve Account

GET /v1/account

Retrieve your account details

Response

{
  "id": "acct_1NqQEEEE456xyz",
  "object": "account",
  "business_name": "Acme Ltd",
  "email": "admin@acme.com",
  "type": "manager",
  "iban": "GB82PAEB60913100123456",
  "created": 1693400000
}

Update Account

PATCH /v1/account

Update account settings

Request Body

{
  "business_name": "Acme Corporation Ltd",
  "support_email": "help@acme.com"
}

Response

{
  "id": "acct_1NqQEEEE456xyz",
  "business_name": "Acme Corporation Ltd"
}

Sub-Accounts

Sub-accounts are created under manager accounts to manage payments for clients or team members.

Create a Sub-Account

POST /v1/subaccounts

Create a new sub-account

Request Body

{
  "name": "John Design Studio",
  "email": "john@studio.com",
  "payout_schedule": "weekly"
}

Response

{
  "id": "sub_1NqRFFFF789abc",
  "object": "subaccount",
  "name": "John Design Studio",
  "email": "john@studio.com",
  "status": "active",
  "created": 1693429000
}

Retrieve a Sub-Account

GET /v1/subaccounts/{id}

Retrieve sub-account details

Response

{
  "id": "sub_1NqRFFFF789abc",
  "name": "John Design Studio",
  "balance": 12450
}

Update a Sub-Account

PATCH /v1/subaccounts/{id}

Update sub-account settings

Request Body

{
  "payout_schedule": "daily"
}

Response

{
  "id": "sub_1NqRFFFF789abc",
  "payout_schedule": "daily"
}

Deactivate a Sub-Account

POST /v1/subaccounts/{id}/deactivate

Deactivate a sub-account

Response

{
  "id": "sub_1NqRFFFF789abc",
  "status": "inactive"
}

List all Sub-Accounts

GET /v1/subaccounts

List all sub-accounts

Response

{
  "object": "list",
  "data": [...],
  "has_more": false
}

Transfers

Transfer funds between your manager account and sub-accounts.

Create a Transfer

POST /v1/transfers

Transfer funds to a sub-account

Request Body

{
  "amount": 5000,
  "currency": "gbp",
  "destination": "sub_1NqRFFFF789abc",
  "description": "March payout"
}

Response

{
  "id": "tr_1NqSGGGG123xyz",
  "object": "transfer",
  "amount": 5000,
  "currency": "gbp",
  "destination": "sub_1NqRFFFF789abc",
  "status": "completed",
  "created": 1693430000
}

Retrieve a Transfer

GET /v1/transfers/{id}

Retrieve transfer details

Response

{
  "id": "tr_1NqSGGGG123xyz",
  "amount": 5000,
  "status": "completed"
}

Balance

Retrieve your current balance including available and pending funds.

Retrieve Balance

GET /v1/balance

Get current balance

Response

{
  "object": "balance",
  "available": [
    {
      "amount": 124892,
      "currency": "gbp"
    }
  ],
  "pending": [
    {
      "amount": 24156,
      "currency": "gbp"
    }
  ]
}

Payouts

Send funds from your Paebs balance to your bank account.

Create a Payout

POST /v1/payouts

Create a payout to your bank

Request Body

{
  "amount": 50000,
  "currency": "gbp",
  "method": "instant"
}

Response

{
  "id": "po_1NqTHHHH456abc",
  "object": "payout",
  "amount": 50000,
  "currency": "gbp",
  "status": "in_transit",
  "arrival_date": 1693516800,
  "created": 1693431000
}

Retrieve a Payout

GET /v1/payouts/{id}

Retrieve payout details

Response

{
  "id": "po_1NqTHHHH456abc",
  "amount": 50000,
  "status": "paid"
}

Cancel a Payout

POST /v1/payouts/{id}/cancel

Cancel a pending payout

Response

{
  "id": "po_1NqTHHHH456abc",
  "status": "canceled"
}

List all Payouts

GET /v1/payouts

List all payouts

Response

{
  "object": "list",
  "data": [...],
  "has_more": true
}

Balance Transactions

Balance transactions represent funds moving in and out of your Paebs account.

Retrieve a Transaction

GET /v1/balance_transactions/{id}

Retrieve transaction details

Response

{
  "id": "txn_1NqUIIII789xyz",
  "object": "balance_transaction",
  "amount": 2500,
  "fee": 55,
  "net": 2445,
  "type": "payment",
  "created": 1693432000
}

List Balance Transactions

GET /v1/balance_transactions

List all balance transactions

Response

{
  "object": "list",
  "data": [...],
  "has_more": true
}

Webhooks

Webhooks allow you to receive real-time notifications about events in your Paebs account.

Create a Webhook Endpoint

POST /v1/webhook_endpoints

Create a new webhook endpoint

Request Body

{
  "url": "https://example.com/webhooks/paebs",
  "events": [
    "payment.succeeded",
    "payment.failed",
    "refund.created"
  ]
}

Response

{
  "id": "we_1NqVJJJJ123abc",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/paebs",
  "status": "enabled",
  "secret": "whsec_abc123...",
  "created": 1693433000
}

List Webhook Endpoints

GET /v1/webhook_endpoints

List all webhook endpoints

Response

{
  "object": "list",
  "data": [...],
  "has_more": false
}

Delete a Webhook Endpoint

DELETE /v1/webhook_endpoints/{id}

Delete a webhook endpoint

Response

{
  "id": "we_1NqVJJJJ123abc",
  "deleted": true
}

Events

Events represent actions that have occurred in your account. You can retrieve individual events or list recent events.

Retrieve an Event

GET /v1/events/{id}

Retrieve event details

Response

{
  "id": "evt_1NqWKKKK456xyz",
  "object": "event",
  "type": "payment.succeeded",
  "data": {
    "object": {
      "id": "pay_1NqL9JABC123def456",
      "amount": 2500
    }
  },
  "created": 1693434000
}

List all Events

GET /v1/events?type=payment.succeeded

List events with optional type filter

Response

{
  "object": "list",
  "data": [...],
  "has_more": true
}

Disputes

Dispute objects are created when a cardholder questions a charge with their bank.

Retrieve a Dispute

GET /v1/disputes/{id}

Retrieve dispute details

Response

{
  "id": "dp_1NqXLLLL789abc",
  "object": "dispute",
  "amount": 2500,
  "payment": "pay_1NqL9JABC123def456",
  "reason": "fraudulent",
  "status": "needs_response",
  "evidence_due_by": 1694038800,
  "created": 1693435000
}

Submit Dispute Evidence

POST /v1/disputes/{id}

Submit evidence for a dispute

Request Body

{
  "evidence": {
    "customer_name": "John Smith",
    "customer_email": "john@example.com",
    "shipping_tracking_number": "1Z999AA10123456784",
    "uncategorized_text": "Customer received and used the product."
  },
  "submit": true
}

Response

{
  "id": "dp_1NqXLLLL789abc",
  "status": "under_review"
}

Close a Dispute

POST /v1/disputes/{id}/close

Accept and close a dispute

Response

{
  "id": "dp_1NqXLLLL789abc",
  "status": "lost"
}

List all Disputes

GET /v1/disputes

List all disputes

Response

{
  "object": "list",
  "data": [...],
  "has_more": false
}

Getting Started

Core Resources

Manager Accounts

Payouts & Balance

Other

Authentication

Errors

Pagination

Payments

Create a Payment

Retrieve a Payment

List all Payments

Capture a Payment

Cancel a Payment

Refunds

Create a Refund

Retrieve a Refund

List all Refunds

Customers

Create a Customer

Retrieve a Customer

Update a Customer

Delete a Customer

List all Customers

Cards

Create a Card

Retrieve a Card

Delete a Card

Tokens

Create a Token

Retrieve a Token

Accounts

Retrieve Account

Update Account

Sub-Accounts

Create a Sub-Account

Retrieve a Sub-Account

Update a Sub-Account

Deactivate a Sub-Account

List all Sub-Accounts

Transfers

Create a Transfer

Retrieve a Transfer

Balance

Retrieve Balance

Payouts

Create a Payout

Retrieve a Payout

Cancel a Payout

List all Payouts

Balance Transactions

Retrieve a Transaction

List Balance Transactions

Webhooks

Create a Webhook Endpoint

List Webhook Endpoints

Delete a Webhook Endpoint

Events

Retrieve an Event

List all Events

Disputes

Retrieve a Dispute

Submit Dispute Evidence

Close a Dispute

List all Disputes

Ready to integrate?