Overview
Build Acquiring API provides a simple and flexible way to initiate and authorise online payments. You can use the same integration for payments made with cards (including 3D Secure). Before writing any code, please familiarize yourself with the basics of our API interaction.
Environments & Base URLs
| Environment | URL Endpoint | Purpose |
|---|---|---|
| Sandbox | https://api.sandbox.build.app | Used for development and debugging. No actual charges are made. |
| Production | https://api.build.app | Used for processing real transactions. |
Conventions
- Protocol: HTTP/1.1 over TLS 1.2+.
- Data Format: Both Request and Response bodies are JSON (Content-Type: application/json).
- Character Encoding: UTF-8.
- Date Format: We recommend using the ISO 8601 standard (e.g.,
2023-11-26T10:00:00Z).
Key Concepts
To build a robust payment system, please ensure you understand the following concepts:
1. Idempotency
Due to network instability, a request might time out even though the server has successfully processed it. To prevent duplicate charges, you must pass a unique identifier in the header or body.
- Field:
order_reference(UUID v4 is recommended). - Logic: If you retry a request with the same
requestId, we will return the result of the initial processing attempt without performing a new charge.
2. Async Payments & 3DS
Not all transactions succeed instantly.
- 3D Secure: If the issuing bank requires user verification (e.g., SMS code), the API will return redirect_url in next_action. You must redirect the user to this URL to complete verification.
- Final Status: We recommend using Webhooks to receive the final payment result.