This guide provides detailed information about integrating with the Payment Authorization API. The API enables processing of payment transactions including authorization, capture, void, charge and refund operations.
\n![](\"https://lh7-rt.googleusercontent.com/docsz/AD_4nXfB0MQQ4WwIIL7kFDzSzpSBSdyZgUzWEeNjt-g8piCWPvegFG4_0z0FoQXrQxXLC5dqtQDyx1H_2agENeJC9DBifV5ZuoqhSa01gYm03w32CbDTlqqPaGT10lOuI-JK_pDNIIJi4g?key=qelmDFYy1iA40AB_-hYa6chE\")
\n\n![](\"https://lh7-rt.googleusercontent.com/docsz/AD_4nXf9tPOtBv5iQlgkQHdfkSeO3oT60FramzF9EE78DZ-tliCcAKWsujj0KuIf7VJRqwq8VQCOAg4qAUg0VLGdS08hh6Cz5-lMWjFceg4VGfVEjDKkZjP_Cp75rnpZH6SQnQPi-uULng?key=qelmDFYy1iA40AB_-hYa6chE\")
\n\nAll API requests require two headers:
\nx-api-key: Your API key for authentication
x-partner-id: Your partner identifier
Sandbox: https://sandbox-api.bettercharge.ai
Production: https://api.bettercharge.ai
Always check HTTP status code
\nParse error response for details
\nImplement appropriate retry logic
\nLog all error responses
\nAlways use TLS 1.2 or higher
\nImplement proper error handling
\nStore payment IDs for reference
\nImplement idempotency
\nMonitor API response times
\nSet appropriate timeouts
\n100 requests per minute per API key
\n429 status code indicates rate limit exceeded
\nImplement exponential backoff
\nThe state field in the payment object represents the current status of a payment’s lifecycle. This state reflects the high-level status that clients should rely on.
\nFor testing purposes we support test card numbers/tokens, test email addresses (used for different response types)
\nTest all response scenarios. This can be achieved by the different test email addresses provided by Better
\nVerify error handling
\nTest timeout scenarios
\nThe following card numbers can be used for testing in our Sandbox environment.
\nUsing a test card in production will result with an error response, and the transaction will not be processed.
\nUsing a card not from this list, in our Sandbox environment will result with an error response.
\nThe following email addresses can be used for testing in our Sandbox environment. Using these email addresses, you can illustrate different response codes.
\nThis document provides a comprehensive list of all error responses that can be returned by the BetterCharge API. All error responses follow a consistent structure with a code, error, and message field.
{\n \"code\": \"ERROR_CODE\",\n \"error\": \"Error Type\",\n \"message\": \"Detailed error message\"\n}\n\nThe service may return specific system wide decline reasons:
\nAPI endpoints are subject to rate limiting. When rate limits are exceeded, the API will return a 429 status code with appropriate headers:
\nHTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1640275200\n\nAlways check the HTTP status code first to determine the general category of error
\nParse the error response body to get specific error details
\nHandle 4xx errors by correcting the request and retrying
\nHandle 5xx errors by implementing exponential backoff and retry logic
\nLog error details for debugging and monitoring purposes
\nImplement proper error handling for network timeouts and connection issues
\nUse the error codes to provide meaningful feedback to end users
\nIn a case where Better calls the API for retries it is up to the partner to block another fallback to Better, which can happen in the following scenario:
\nMerchant calls Partner → Partner calls PSP → PSP returns NSF → Partner calls Better → Better approves → Better retries using Partner API → Partner calls PSP → PSP returns NSF → Partner calls Better again ❌ → Better starts a new process
\nIt is up to the partner to block the fallback to Better
\nContact support@bettercharge.ai for assistanceAPI documentation for BetterCharge payment and merchant management services.API documentation for Better payment and connector services.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"BetterCharge API Error Responses","slug":"bettercharge-api-error-responses"}],"owner":"42148697","collectionId":"bc4d9034-c117-4938-b353-e20f5a190539","publishedId":"2sB3HjLLsT","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"58b3b3"},"publishDate":"2025-11-10T16:12:19.000Z"},"item":[{"name":"Payment","item":[{"name":"Authorize payment","id":"c4ca93bf-991d-42de-b4f6-9384f8a096b3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"(Required)
\n"},{"key":"x-partner-id","value":"(Required)
\n"},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"merchantId\": \"Authorize a payment and return a decision based on the passed parameters.
\nThe following table defines the supported parameters.
\n\n\n","urlObject":{"path":["v1","payment","authorize"],"host":["https://sandbox-api.bettercharge.ai"],"query":[],"variable":[]}},"response":[{"id":"b0d5ae2b-71aa-4d8e-8c5a-6b368f81a6cc","name":"Successful response","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"Note: Parameters marked as Recommended are not mandatory, but they are highly valuable. Supplying them improves the likelihood of payment approval and routing quality.
\n
(Required)
\n"},{"key":"x-partner-id","value":"(Required)
\n"},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"merchantId\": \"