API Reference

Complete REST API documentation for Booloopay.

Generate an API key in the dashboard to authenticate your requests. Generate API key →

Authentication

Every request must include your API key as a Bearer token in the Authorization header.

Example request

Authorization: Bearer bpay_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Responses: All responses are JSON. Successful responses wrap data in a data field. Errors include an error field.

Base URL: https://test.booloopay.com/api/v1

Customers

Manage your customers via the API. Customers can be linked to payment and signature requests.

GET /api/v1/customers List all customers

Returns a list of all customers in your organization.

Query parameters

Name	Type	Required	Description
search	string	Optional	Filter by name, company, or email.

Example request

curl https://test.booloopay.com/api/v1/customers \
  -H "Authorization: Bearer bpay_xxxx"

Example response

{
  "data": [
    {
      "id": 1,
      "first_name": "Alice",
      "last_name": "Martin",
      "email": "alice@example.com",
      "company": "Acme Corp",
      "phone": "+33 6 00 00 00 00",
      "address": "12 rue de la Paix, Paris",
      "inserted_at": "2026-06-01T10:00:00Z"
    }
  ]
}

POST /api/v1/customers Create a customer

Creates a new customer.

Request body

Name	Type	Required	Description
first_name	string	Required	First name.
last_name	string	Required	Last name.
email	string	Required	Email address.
phone	string	Optional	Phone number.
company	string	Optional	Company name.
address	string	Optional	Full address.

Example request

curl -X POST https://test.booloopay.com/api/v1/customers \
  -H "Authorization: Bearer bpay_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Alice","last_name":"Martin","email":"alice@example.com"}'

Example response

HTTP 201 Created

{
  "data": {
    "id": 1,
    "first_name": "Alice",
    "last_name": "Martin",
    "email": "alice@example.com",
    "company": null,
    "phone": null,
    "address": null,
    "inserted_at": "2026-06-18T14:00:00Z"
  }
}

GET /api/v1/customers/:id Retrieve a customer

Retrieves a specific customer by ID.

Example request

curl https://test.booloopay.com/api/v1/customers/1 \
  -H "Authorization: Bearer bpay_xxxx"

PUT /api/v1/customers/:id Update a customer

Updates one or more fields of a customer.

Request body

Name	Type	Required	Description
first_name	string	Optional	First name.
last_name	string	Optional	Last name.
email	string	Optional	Email address.
phone	string	Optional	Phone number.
company	string	Optional	Company name.
address	string	Optional	Full address.

Example request

curl -X PUT https://test.booloopay.com/api/v1/customers/1 \
  -H "Authorization: Bearer bpay_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"company":"Acme Corp"}'

DELETE /api/v1/customers/:id Delete a customer

Permanently deletes a customer. Returns 204 with no body.

Example request

curl -X DELETE https://test.booloopay.com/api/v1/customers/1 \
  -H "Authorization: Bearer bpay_xxxx"

Payment Requests

Create and manage payment requests. Each request generates a unique payment link.

GET /api/v1/payment_requests List all payment requests

Query parameters

Name	Type	Required	Description
search	string	Optional	Filter by description.
status	string	Optional	pending · paid · expired · cancelled

Example request

curl "https://test.booloopay.com/api/v1/payment_requests?status=pending" \
  -H "Authorization: Bearer bpay_xxxx"

Example response

{
  "data": [
    {
      "id": 42,
      "public_id": "pr_abc123",
      "description": "Invoice #2026-01",
      "amount_cents": 15000,
      "currency": "EUR",
      "status": "pending",
      "due_date": "2026-07-01",
      "customer_id": 1,
      "pay_url": "https://yourapp.com/pay/pr_abc123",
      "inserted_at": "2026-06-18T10:00:00Z",
      "updated_at": "2026-06-18T10:00:00Z"
    }
  ]
}

POST /api/v1/payment_requests Create a payment request

Request body

Name	Type	Required	Description
description	string	Required	A short description of the payment.
amount_cents	integer	Required	Amount in the smallest currency unit (e.g. 1500 = 15.00 EUR).
currency	string	Optional	ISO 4217 currency code. Defaults to your organization currency.
due_date	string	Optional	Expiry date in YYYY-MM-DD format.
customer_id	integer	Optional	ID of an existing customer to link.

Example request

curl -X POST https://test.booloopay.com/api/v1/payment_requests \
  -H "Authorization: Bearer bpay_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"description":"Invoice #2026-01","amount_cents":15000,"currency":"EUR","due_date":"2026-07-01"}'

Example response

HTTP 201 Created

{
  "data": {
    "id": 42,
    "public_id": "pr_abc123",
    "description": "Invoice #2026-01",
    "amount_cents": 15000,
    "currency": "EUR",
    "status": "pending",
    "due_date": "2026-07-01",
    "customer_id": null,
    "pay_url": "https://yourapp.com/pay/pr_abc123",
    "inserted_at": "2026-06-18T10:00:00Z",
    "updated_at": "2026-06-18T10:00:00Z"
  }
}

GET /api/v1/payment_requests/:id Retrieve a payment request

Retrieves a specific payment request by ID.

Example request

curl https://test.booloopay.com/api/v1/payment_requests/42 \
  -H "Authorization: Bearer bpay_xxxx"

PUT /api/v1/payment_requests/:id Update a payment request

Updates one or more fields of a payment request.

Request body

Name	Type	Required	Description
description	string	Optional	A short description of the payment.
amount_cents	integer	Optional	Amount in the smallest currency unit.
due_date	string	Optional	Expiry date in YYYY-MM-DD format.
customer_id	integer	Optional	ID of a customer to link.

Example request

curl -X PUT https://test.booloopay.com/api/v1/payment_requests/42 \
  -H "Authorization: Bearer bpay_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":20000}'

DELETE /api/v1/payment_requests/:id Cancel a payment request

Cancels a payment request. Returns 204 with no body.

Example request

curl -X DELETE https://test.booloopay.com/api/v1/payment_requests/42 \
  -H "Authorization: Bearer bpay_xxxx"

Signature Requests

Send documents for e-signature and track their signing status.

GET /api/v1/signature_requests List all signature requests

Query parameters

Name	Type	Required	Description
search	string	Optional	Filter by title or signer name.
status	string	Optional	pending · signed · declined

Example request

curl "https://test.booloopay.com/api/v1/signature_requests?status=pending" \
  -H "Authorization: Bearer bpay_xxxx"

Example response

{
  "data": [
    {
      "id": 7,
      "public_id": "sig_xyz789",
      "title": "NDA — Acme Corp",
      "signer_name": "Bob Smith",
      "signer_email": "bob@example.com",
      "status": "pending",
      "message": "Please review and sign.",
      "expires_at": "2026-07-18T00:00:00Z",
      "signed_at": null,
      "sign_url": "https://yourapp.com/sign/sig_xyz789",
      "customer_id": 1,
      "document_id": 3,
      "inserted_at": "2026-06-18T10:00:00Z"
    }
  ]
}

POST /api/v1/signature_requests Create a signature request

Request body

Name	Type	Required	Description
title	string	Required	Title of the document to sign.
signer_name	string	Required	Full name of the signer.
signer_email	string	Required	Email address of the signer.
message	string	Optional	A message shown to the signer.
expires_in_days	integer	Optional	Number of days before the signing link expires.
customer_id	integer	Optional	ID of an existing customer to link.
document_id	integer	Optional	ID of an uploaded document to reference.

Example request

curl -X POST https://test.booloopay.com/api/v1/signature_requests \
  -H "Authorization: Bearer bpay_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"NDA — Acme Corp","signer_name":"Bob Smith","signer_email":"bob@example.com","expires_in_days":30}'

Example response

HTTP 201 Created

{
  "data": {
    "id": 7,
    "public_id": "sig_xyz789",
    "title": "NDA — Acme Corp",
    "signer_name": "Bob Smith",
    "signer_email": "bob@example.com",
    "status": "pending",
    "message": null,
    "expires_at": "2026-07-18T00:00:00Z",
    "signed_at": null,
    "sign_url": "https://yourapp.com/sign/sig_xyz789",
    "customer_id": null,
    "document_id": null,
    "inserted_at": "2026-06-18T10:00:00Z"
  }
}

GET /api/v1/signature_requests/:id Retrieve a signature request

Retrieves a specific signature request by ID.

Example request

curl https://test.booloopay.com/api/v1/signature_requests/7 \
  -H "Authorization: Bearer bpay_xxxx"

DELETE /api/v1/signature_requests/:id Delete a signature request

Deletes a signature request. Returns 204 with no body.

Example request

curl -X DELETE https://test.booloopay.com/api/v1/signature_requests/7 \
  -H "Authorization: Bearer bpay_xxxx"

Guarantees

Create and manage security deposits (cautions). A guarantee authorizes a hold on the customer's card via Stripe; you can later capture or release it.

GET /api/v1/guarantees List all guarantees

Query parameters

Name	Type	Required	Description
status	string	Optional	all · draft · pending · authorized · captured · released · cancelled
search	string	Optional	Filter by customer name, email or reason.

Example request

curl "https://test.booloopay.com/api/v1/guarantees?status=authorized" \
  -H "Authorization: Bearer bpay_xxxx"

Example response

{
  "data": [
    {
      "id": 1,
      "public_id": "g_abc123",
      "status": "authorized",
      "guarantee_type": "deposit",
      "customer_name": "Alice Martin",
      "customer_email": "alice@example.com",
      "customer_phone": "+33 6 00 00 00 00",
      "reason": "Caution location appartement",
      "reference": "REF-2026-001",
      "amount_cents": 150000,
      "currency": "EUR",
      "captured_amount_cents": null,
      "expiration_date": "2027-06-01",
      "stripe_payment_intent_id": "pi_xxx",
      "renewal_count": 0,
      "guarantee_url": "https://yourapp.com/guarantee/g_abc123",
      "inserted_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-01T10:00:00Z"
    }
  ]
}

GET /api/v1/guarantees/stats Get statistics

Returns aggregate counts and total authorized amount for the organization.

Example request

curl https://test.booloopay.com/api/v1/guarantees/stats \
  -H "Authorization: Bearer bpay_xxxx"

Example response

{
  "data": {
    "total": 12,
    "authorized": 8,
    "draft": 2,
    "captured": 1,
    "released": 1,
    "total_authorized_cents": 1200000
  }
}

POST /api/v1/guarantees Create a guarantee

Request body

Name	Type	Required	Description
guarantee_type	string	Required	deposit · rental · other
customer_name	string	Required	Full name of the customer.
customer_email	string	Required	Email address of the customer.
customer_phone	string	Optional	Phone number of the customer.
reason	string	Required	Purpose of the guarantee (e.g. "Caution location").
reference	string	Optional	Your internal reference number.
amount_cents	integer	Required	Amount to hold, in the smallest currency unit (e.g. 150000 = €1 500).
currency	string	Optional	ISO 4217 code. Defaults to EUR.
expiration_date	string	Required	ISO 8601 date when the guarantee expires (e.g. "2027-06-01").
channels	array	Optional	Notification channels. Defaults to ["email"].
customer_id	integer	Optional	ID of an existing customer to link.

Example request

curl -X POST https://test.booloopay.com/api/v1/guarantees \
  -H "Authorization: Bearer bpay_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"guarantee_type":"deposit","customer_name":"Alice Martin","customer_email":"alice@example.com","reason":"Caution location","amount_cents":150000,"expiration_date":"2027-06-01"}'

Example response

HTTP 201 Created

{
  "data": {
    "id": 1,
    "public_id": "g_abc123",
    "status": "draft",
    "guarantee_type": "deposit",
    "customer_name": "Alice Martin",
    "customer_email": "alice@example.com",
    "customer_phone": null,
    "reason": "Caution location appartement",
    "reference": null,
    "amount_cents": 150000,
    "currency": "EUR",
    "captured_amount_cents": null,
    "expiration_date": "2027-06-01",
    "stripe_payment_intent_id": null,
    "renewal_count": 0,
    "guarantee_url": "https://yourapp.com/guarantee/g_abc123",
    "inserted_at": "2026-06-18T14:00:00Z",
    "updated_at": "2026-06-18T14:00:00Z"
  }
}

GET /api/v1/guarantees/:id Retrieve a guarantee

Retrieves a specific guarantee by ID.

Example request

curl https://test.booloopay.com/api/v1/guarantees/1 \
  -H "Authorization: Bearer bpay_xxxx"

POST /api/v1/guarantees/:id/send Send a guarantee

Sends the guarantee link to the customer by email. The guarantee must be in draft status.

Example request

curl -X POST https://test.booloopay.com/api/v1/guarantees/1/send \
  -H "Authorization: Bearer bpay_xxxx"

POST /api/v1/guarantees/:id/renew Renew a guarantee

Extends an authorized guarantee with a new expiration date and notifies the customer.

Request body

Name	Type	Required	Description
expiration_date	string	Required	New expiration date in ISO 8601 format.

Example request

curl -X POST https://test.booloopay.com/api/v1/guarantees/1/renew \
  -H "Authorization: Bearer bpay_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"expiration_date":"2028-06-01"}'

POST /api/v1/guarantees/:id/release Release a guarantee

Cancels the Stripe authorization and releases the hold on the customer's card. The guarantee must be authorized.

Example request

curl -X POST https://test.booloopay.com/api/v1/guarantees/1/release \
  -H "Authorization: Bearer bpay_xxxx"

POST /api/v1/guarantees/:id/capture Capture a guarantee

Captures (charges) the held amount from the customer's card. You can capture a partial amount by passing the amount field. The guarantee must be authorized.

Request body

Name	Type	Required	Description
amount	number	Optional	Amount to capture in the account currency (e.g. 800.00 for €800). Defaults to the full guaranteed amount.

Example request

curl -X POST https://test.booloopay.com/api/v1/guarantees/1/capture \
  -H "Authorization: Bearer bpay_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 800.00}'

GET /api/v1/guarantees/:id/proof Get proof of guarantee

Returns the guarantee object along with the full audit trail of events (creation, send, authorization, capture, release).

Example request

curl https://test.booloopay.com/api/v1/guarantees/1/proof \
  -H "Authorization: Bearer bpay_xxxx"

Error codes

The API uses standard HTTP status codes.

Code	Status	Meaning
`200`	OK	Request succeeded.
`201`	Created	Resource created successfully.
`204`	No Content	Resource deleted. No body returned.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	The resource exists but belongs to another organization.
`404`	Not Found	The resource does not exist.
`422`	Unprocessable	Validation failed. Check the errors field in the response.
`500`	Server Error	Something went wrong on our end.

Validation error example

HTTP 422 Unprocessable Entity

{
  "error": "Validation failed",
  "errors": {
    "first_name": ["can't be blank"],
    "email": ["has invalid format"]
  }
}

Authentication error example

HTTP 401 Unauthorized

{
  "error": "Invalid or missing API key"
}

Booloopay API · Back to dashboard