Skip to main content
Use your business API key and secret to authenticate requests. Your server calculates an HMAC-SHA256 signature for each request, so Ledig can verify that it came from you and has not changed. Some endpoints also accept a bearer token, as shown in the API reference. Use one authentication method per request. Sending both a bearer token and an API key returns 401.

Credentials and permissions

Your business administrator creates API keys in the dashboard. A business can have up to ten active keys, each expiring within six months. Save the secret when creating or rotating a key; it is shown only once. Rotation replaces the old secret immediately, and revocation stops the key from working. Keep credentials in a server-side secret manager. Do not put them in browser or mobile code, repositories, URLs or logs. Each endpoint lists its required scope, which is the permission your key needs. Payments still need to meet your business’s service access, recipient approval, balance and limit requirements.

HMAC v1

Use v1 for requests on behalf of your own business. Send these three headers: Build this exact UTF-8 string:
Use the uppercase method. Include the exact path and query string, beginning with /; do not include the scheme or hostname. For a request without a body, use the empty string. For JSON, serialize once, then sign and send that same string. Whitespace, query ordering and JSON key ordering affect the signature. Calculate the digest with your secret and standard base64 encoding. Timestamps must be within 300 seconds of server time. Keep your server clock in sync and use a fresh timestamp and signature for every attempt.

Examples

Set LEDIG_API_BASE_URL to https://api-sandbox.ledig.io to start in Sandbox. Load LEDIG_API_KEY and LEDIG_API_SECRET from your server’s secret configuration. These examples read your USD balance. The signature and timestamp are calculated for the request; they are not API keys.
For a JSON request, serialize the body once and sign that exact text. Send the same text with Content-Type: application/json. If the response is lost, follow the retry rules.

Act for a managed business

Use HMAC v2 when your institution makes payments or reads balances for a business it manages. V2 includes the business-selection headers in the signature. Build the v2 payload using compact JSON, in this exact order. This Node.js helper uses the createHmac import from the example above:
The last three values must match the headers you send, with surrounding whitespace trimmed. Use "" for an omitted header. IDs are case-sensitive. Send the resulting signature in x-ledig-signature, along with the key and timestamp headers. V1 cannot select a managed business. Your institution must have access to that business, and your key must have the permissions required for the request.
When onboarding a managed business, keep your institution selected and put the managed business ID in the endpoint path. You can use v1 or v2 for these requests. See Managed businesses.

Troubleshooting

If authentication fails, check your server clock, uppercase method, query string, body text and selected business. The values you sign must match the request you send. Save the request ID and HTTP status when troubleshooting. Do not log secrets, signatures or the full signing text, which can contain customer information. See Errors and troubleshooting for response codes and safe retries.