Overview

The Outpost Merchant of Record API lets you issue proforma invoices for B2B customers paying by bank transfer, receive a webhook the moment those transfers settle, and retrieve tax invoices for payments and refunds processed through Outpost. Proforma invoices are generated on demand and returned with a link to the PDF; tax invoices are generated automatically and fetched by Outpost ID or PSP reference.

Key Concepts

Environment Setup

Authentication

Outpost uses OAuth2 client_credentials flow for server-to-server authentication. Your backend requests an access token using your client ID and secret, then includes it as a Bearer token in all API calls.

Flow

• Request access token using client credentials
• Parse response and extract access_token with expires_in
• Cache token server-side with TTL (recommend expires_in - 300s buffer)
• Refresh token on expiry or 401 responses
• Include Bearer token in all subsequent API requests

Cache access_token with expires_in - 300s buffer; retry once after refresh on 401.

Token Response

{
  "access_token": "<JWT>",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Create Proforma Invoice

Generates a proforma invoice for a B2B customer who is paying by bank transfer. A proforma invoice is a non-fiscal request for payment: it states what is owed, to whom, and how to pay, before the money has been received. Outpost renders the PDF, stores it, and returns a link to it directly in the response so you can surface it on your checkout.

How it works

• Your checkout collects the B2B customer details, line items, and jurisdiction.
• Your backend calls POST /api/proforma-invoices with that payload.
• Outpost generates the PDF, stores it, and returns invoice.url in the response.
• You display or email the proforma invoice to the customer with bank-transfer instructions.
• When the transfer settles, Outpost sends a proforma_invoice.settled webhook so you can fulfill the order.

Request Headers

Request Body Parameters

Response 201 Created

{
  "proformaInvoiceId": "019d4d40-15cf-7764-ad6e-b2ec47736bb9",
  "status": "ISSUED",
  "invoice": {
    "fileName": "proforma-invoice-2026-000123.pdf",
    "url": "https://storage.outpostanywhere.com/proforma-invoices/019d4d40-...pdf",
    "expiresAt": "2026-06-01T12:15:00Z"
  },
  "total": { "amount": "1200.00", "currency": "GBP" },
  "issueDate": "2026-06-01",
  "dueDate": "2026-06-15",
  "createdAt": "2026-06-01T12:00:00Z"
}

Response Fields

Error Responses

{
  "invoice": {
    "fileName": "invoice-7110000000023059375.pdf",
    "url": "https://storage.outpostanywhere.com/invoices/...",
    "expiresAt": "2026-01-05T12:15:00Z"
  }
}

Response 202 Accepted — Invoice is still being generated. Retry after a short delay.

# Get payment invoice by Outpost payment ID
curl -X GET \
  "https://api.outpostanywhere.com/api/payments/${PAYMENT_ID}/invoice" \
  -H "Authorization: Bearer $OUTPOST_ACCESS_TOKEN" | jq

# Response: 200 OK with invoice download URL
# Response: 202 Accepted if invoice is still being generated

{
  "invoice": {
    "fileName": "invoice-7110000000023059375.pdf",
    "url": "https://storage.outpostanywhere.com/invoices/...",
    "expiresAt": "2026-01-05T12:15:00Z"
  }
}

Response 202 Accepted — Invoice is still being generated. Retry after a short delay.

# Get payment invoice by PSP reference
curl -X GET \
  "https://api.outpostanywhere.com/api/payments/invoice?psp_reference=7110000000023059375" \
  -H "Authorization: Bearer $OUTPOST_ACCESS_TOKEN" | jq

{
  "invoice": {
    "fileName": "invoice-7110000000023059375.pdf",
    "url": "https://storage.outpostanywhere.com/invoices/...",
    "expiresAt": "2026-01-05T12:15:00Z"
  }
}

Response 202 Accepted — Invoice is still being generated. Retry after a short delay.

# Get refund invoice by Outpost refund ID
curl -X GET \
  "https://api.outpostanywhere.com/api/refunds/${REFUND_ID}/invoice" \
  -H "Authorization: Bearer $OUTPOST_ACCESS_TOKEN" | jq

{
  "invoice": {
    "fileName": "invoice-7110000000023059375.pdf",
    "url": "https://storage.outpostanywhere.com/invoices/...",
    "expiresAt": "2026-01-05T12:15:00Z"
  }
}

Response 202 Accepted — Invoice is still being generated. Retry after a short delay.

# Get refund invoice by PSP reference
curl -X GET \
  "https://api.outpostanywhere.com/api/refunds/invoice?psp_reference=7110000000023060251" \
  -H "Authorization: Bearer $OUTPOST_ACCESS_TOKEN" | jq

Webhooks

Bank transfers settle asynchronously — sometimes minutes, sometimes days after you issue a proforma invoice. Rather than polling, register a webhook endpoint and Outpost will notify your backend the moment the money settles, so you can release the order or activate the subscription.

Response 204 No Content — The webhook was deleted.

# Delete a webhook endpoint so it stops receiving events
curl -X DELETE \
  "https://api.outpostanywhere.com/api/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $OUTPOST_ACCESS_TOKEN"

# Response: 204 No Content

Use cases

End-to-end integration guides for common patterns built on top of the Merchant of Record API.