Payaca API (1.0.0)

The external API uses HTTP Basic Authentication with client credentials (Client ID and Client Secret).

Creating API Credentials

API credentials can be created through the Payaca provider web application:

1. Navigate to My Company → Integrations
2. Click "Create API key"
3. Provide a name for the credentials
4. Record the generated Client ID and Client Secret immediately - the secret cannot be retrieved again

Making Authenticated Requests

Include your credentials in the Authorization header using HTTP Basic Authentication:

curl -X GET https://api.payaca.com/v1/customers \
  -u "your-client-id:your-client-secret"

Or encode the credentials manually:

# Base64 encode "client-id:client-secret"
AUTH_HEADER=$(echo -n "your-client-id:your-client-secret" | base64)

curl -X GET https://api.payaca.com/v1/customers \
  -H "Authorization: Basic $AUTH_HEADER"

Webhooks allow you to receive real-time notifications when events occur in your Payaca account.

Registering a Webhook subscriber

Webhooks can be created through the Payaca provider web application:

1. Navigate to My Company → Integrations
2. Click "Create webhook"
3. Provide the following details:
   1. name for the webhook
   2. URL for Webhook Delivery (must be publicly accessible)
   3. select the events you want to subscribe to (e.g. invoice.fullyPaid, scheduledEvent.created)
   4. provide a secret for Signature Verification - record this secret securely as it will not be retrievable later

Webhook Delivery

When a subscribed event occurs a POST request is made to the webhook URL with a JSON payload and signature from your provided secret.

Webhook Signature Verification

All webhook payloads include an X-Payaca-Signature header for verification, containing an HMAC-SHA256 signature of the payload

X-Payaca-Signature: a2114d57b48eac7b4cde7f32c991906e42c79dc606e60c5093f02c3afc567f78

Verification Process

1. Compute Signature: Create HMAC-SHA256 hex digest of the entire request body, using your webhook secret
2. Compare: Use timing-safe comparison to verify your signature matches the X-Payaca-Signature header.

Retry Logic

If you respond with HTTP 2XX or 4XX, we will not attempt to redeliver a webhook.

We will retry with exponential backoff in the following circumstances:

• HTTP 5xx response,
• Network errors
• Response timeouts (up to 3 seconds)