Common errors and best practices

Common Errors

Missing required fields

{
   "errors": [
       {
           "code": "invalid_object",
           "description": "The 'items' field must be provided."
       }
   ]
}

How to avoid: Always fill in the required fields:

billingTypes
chargeTypes
callback with cancelUrl, expiredUrl, successUrl
items with name, description, value, quantity

Best Practices

Organization and clarity — Structure your requests with clear indentation and use meaningful names for your items (name, description). This improves both conversion rates and visual presentation.

Security — Keep your access_token secure and never expose it in public repositories.

Testing and sandbox environment — Use the sandbox environment to validate integrations before going live in production.

Adjusted expiration flow — Use minutesToExpire strategically.

Customer experience — Send base64 images in the checkout items for a more visual and professional look. Whenever possible, pre-fill customerData to speed up the checkout process for your customers.

Reusability — Registered a customer via API? Use the customer field for future sales with the same buyer.

Business rule validation — Make sure your chargeTypes and billingTypes combinations follow the valid configurations.