Guides

This guide includes full reference and real-world examples for every endpoint listed in this documentation. Each section provides an overview of the endpoint, available fields, their meaning, and a working example.

🔐 Authentication

Get OAuth Token

Description Generates an OAuth 2.0 token using client_credentials. Required before making any authenticated requests.

Method & Path POST /oauth/token

Input Parameters

grant_type (required): Must be client_credentials
Provide client_id and client_secret using Basic Auth (base64-encoded)

Request:

curl -X POST https://public-api.alternativepayments.io/oauth/token \
  -H "Authorization: Basic BASE64(client_id:client_secret)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJh...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Header format:

Authorization: Bearer <access_token>

Note: There is no refresh token in the client-credentials flow. If the token expires, request a new one.

👤 Customers

List Customers

Description Retrieves a paginated list of customer records.

Method & Path GET /customers

Input Parameters:

limit (integer): Number of records to return
after (string): Cursor for pagination
company_name (string): Filter by name
created_at (range): Filter by created date

Request:

curl -X GET https://public-api.alternativepayments.io/customers \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "cus_123",
      "name": "Acme Inc.",
      "email": "[email protected]",
      "created_at": "2024-01-01T12:00:00Z"
    }
  ],
  "pagination": {
    "has_next_page": false,
    "end_cursor": null
  }
}

Create Customer

Description Creates a new customer in your account.

Method & Path POST /customers

Input Parameters:

name (string, required): Customer or company name
email (string, required): Billing contact email
external_id (string, optional): Your internal reference ID

Request:

curl -X POST https://public-api.alternativepayments.io/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc.",
    "email": "[email protected]",
    "external_id": "acme-001"
  }'

Response:

{
  "id": "cus_123",
  "name": "Acme Inc.",
  "email": "[email protected]",
  "external_id": "acme-001",
  "created_at": "2024-01-01T12:00:00Z"
}

Retrieve Customer

Description Fetches details of a single customer.

Method & Path GET /customers/{id}

Request:

curl -X GET https://public-api.alternativepayments.io/customers/cus_123 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "cus_123",
  "name": "Acme Inc.",
  "email": "[email protected]",
  "created_at": "2024-01-01T12:00:00Z"
}

Archive Customer

Description Soft-deletes (archives) a customer from your list.

Method & Path DELETE /customers/{id}

Request:

curl -X DELETE https://public-api.alternativepayments.io/customers/cus_123 \
  -H "Authorization: Bearer $TOKEN"

List Customer Users

Description Retrieves users linked to a customer account.

Method & Path GET /customers/{id}/users

Request:

curl -X GET https://public-api.alternativepayments.io/customers/cus_123/users \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "id": "user_001",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "created_at": "2024-01-02T10:00:00Z"
  }
]

Add User to Customer

Description Adds a new user under the given customer.

Method & Path POST /customers/{id}/users

Input Parameters:

email (string)
first_name (string)
last_name (string)

Request:

curl -X POST https://public-api.alternativepayments.io/customers/cus_123/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe"
  }'

Response:

{
  "id": "user_001",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "created_at": "2024-01-02T10:00:00Z"
}

🧾 Invoices

List Invoices

Description Returns all invoices filtered by status, customer, or date.

Method & Path GET /invoices

Input Parameters:

status (e.g., PAID, OVERDUE)
created_at, due_date ranges
customer_id

Request:

curl -X GET https://public-api.alternativepayments.io/invoices?status=PAID \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "inv_123",
      "customer_id": "cus_123",
      "status": "PAID",
      "amount": 150000,
      "currency": "USD",
      "due_date": "2025-09-01"
    }
  ]
}

Create Invoice

Description Creates an invoice with line items.

Method & Path POST /invoices

Input Parameters:

customer_id
currency
due_date
line_items[] with description, amount, quantity

Request:

curl -X POST https://public-api.alternativepayments.io/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "currency": "USD",
    "due_date": "2025-09-01",
    "line_items": [
      {
        "description": "August MSP Fee",
        "amount": 150000,
        "quantity": 1
      }
    ]
  }'

Response:

{
  "id": "inv_123",
  "status": "OPEN",
  "customer_id": "cus_123",
  "amount": 150000,
  "currency": "USD",
  "due_date": "2025-09-01"
}

Retrieve Invoice

Description Returns full details for a specific invoice.

Method & Path GET /invoices/{id}

Request:

curl -X GET https://public-api.alternativepayments.io/invoices/inv_123 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "inv_123",
  "customer_id": "cus_123",
  "status": "PAID",
  "amount": 150000,
  "due_date": "2025-09-01",
  "currency": "USD"
}

Archive Invoice

Description Soft-deletes an invoice.

Method & Path DELETE /invoices/{id}

Request:

curl -X DELETE https://public-api.alternativepayments.io/invoices/inv_123 \
  -H "Authorization: Bearer $TOKEN"

Get Invoice Payment Link

Description Generates a hosted payment link for an invoice.

Method & Path GET /invoices/{id}/payment-link

Request:

curl -X GET https://public-api.alternativepayments.io/invoices/inv_123/payment-link \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "url": "https://checkout.alternativepayments.io/pay/inv_123"
}

Get Invoice PDF

Description Generates a signed URL to download invoice PDF.

Method & Path GET /invoices/{id}/pdf-link

Request:

curl -X GET https://public-api.alternativepayments.io/invoices/inv_123/pdf-link \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "url": "https://cdn.ap.com/invoices/inv_123.pdf"
}

💵 Payment Request

Create Payment Request

Description Creates a payment request (not tied to invoice).

Method & Path POST /payments/request

Input Parameters:

amount, currency, redirect_url, reference_id

Request:

curl -X POST https://public-api.alternativepayments.io/payments/request \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5000",
    "currency": "USD",
    "redirect_url": "https://yourapp.com/success",
    "reference_id": "quote-987"
  }'

Response:

{
  "id": "preq_123",
  "url": "https://checkout.alternativepayments.io/pay/preq_123",
  "status": "PENDING"
}

Get Payment Request by ID

Description Returns details for a payment request.

Method & Path GET /payments/request/{id}

Request:

curl -X GET https://public-api.alternativepayments.io/payments/request/preq_123 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "preq_123",
  "amount": 5000,
  "currency": "USD",
  "status": "PAID",
  "reference_id": "quote-987"
}

💳 Transactions

List Transactions

Description Fetches transactions by filters.

Method & Path GET /payments

Input Parameters:

status, type, payment_method, invoice_id, customer_id

Request:

curl -X GET "https://public-api.alternativepayments.io/payments?status=succeeded&payment_method=standard_ach" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "txn_001",
      "amount": 5000,
      "currency": "USD",
      "status": "succeeded",
      "payment_method": "standard_ach",
      "created_at": "2024-01-03T08:30:00Z"
    }
  ]
}

💸 Payouts

List Payouts

Description Returns list of payout batches.

Method & Path GET /payouts

Request:

curl -X GET https://public-api.alternativepayments.io/payouts \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "pout_123",
      "status": "succeeded",
      "amount": 100000,
      "currency": "USD",
      "created_at": "2024-01-10T15:00:00Z"
    }
  ]
}

Get Payout by ID

Description Returns details for a single payout.

Method & Path GET /payouts/{id}

Request:

curl -X GET https://public-api.alternativepayments.io/payouts/pout_123 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "pout_123",
  "status": "succeeded",
  "currency": "USD",
  "amount": 100000,
  "created_at": "2024-01-10T15:00:00Z"
}

List Payout Transactions

Description Returns all transactions for a specific payout.

Method & Path GET /payouts/{id}/transactions

Request:

curl -X GET https://public-api.alternativepayments.io/payouts/pout_123/transactions \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "transactions": [
    {
      "id": "txn_001",
      "status": "succeeded",
      "amount": 5000,
      "currency": "USD",
      "type": "payment",
      "direction": "inbound"
    }
  ]
}

⚠️Error Handling

All errors return standard HTTP status codes plus a JSON body:

{
  "code": "text",
  "message": "text"
}

Code

When it happens

400

Malformed JSON or missing required field

401

Missing or invalid token

403

Token is valid but lacks permission (rare)

404

Object not found

422

Semantic validation error (e.g., unsupported currency)

429

Rate limit exceeded.

500

Unexpected server error; retry later

PreviousAPI Keys NextWebhooks

Last updated 6 months ago

Was this helpful?

hashtag🔐 Authentication

hashtagGet OAuth Token

hashtag👤 Customers

hashtagList Customers

hashtagCreate Customer

hashtagRetrieve Customer

hashtagArchive Customer

hashtagList Customer Users

hashtagAdd User to Customer

hashtag🧾 Invoices

hashtagList Invoices

hashtagCreate Invoice

hashtagRetrieve Invoice

hashtagArchive Invoice

hashtagGet Invoice Payment Link

hashtagGet Invoice PDF

hashtag💵 Payment Request

hashtagCreate Payment Request

hashtagGet Payment Request by ID

hashtag💳 Transactions

hashtagList Transactions

hashtag💸 Payouts

hashtagList Payouts

hashtagGet Payout by ID

hashtagList Payout Transactions

hashtag⚠️Error Handling

🔐 Authentication

Get OAuth Token

👤 Customers

List Customers

Create Customer

Retrieve Customer

Archive Customer

List Customer Users

Add User to Customer

🧾 Invoices

List Invoices

Create Invoice

Retrieve Invoice

Archive Invoice

Get Invoice Payment Link

Get Invoice PDF

💵 Payment Request

Create Payment Request

Get Payment Request by ID

💳 Transactions

List Transactions

💸 Payouts

List Payouts

Get Payout by ID

List Payout Transactions

⚠️Error Handling