Quick Start Guide

Step 1. Getting API Credentials

• Before using the Carusell API, you must obtain API credentials (login and password) from our Support Team. These credentials are required to generate an access token and authenticate your requests.
• To receive your API credentials, please contact our Support Team: [email protected].
• You will be issued separate credentials for each:
  • Sandbox credentials are used for testing your integration in a safe environment.
  • Production credentials are used for live payment processing and must be handled securely.

Step 2. Authentication & Authorization

Getting Access and Refresh Tokens

Authentication in the Carusell API is based on a token system. It follows the OAuth 2.0 framework, specifically the Resource Owner Password Credentials grant type, where tokens are issued in exchange for company credentials. When you log in using your company credentials, the API returns two tokens:

How It Works

1. Send a POST request to /configuration-management/api/v1/admin-accounts/oauth/authorize with your login and password.
2. Receive both access and refresh tokens in the response body.
3. Use the access token in the Authorization: Bearer YOUR_TOKEN header for all authenticated API requests.

Updating Access Token with Refresh Token

When your access token expires (after 30 minutes), you can obtain a new one without re-authenticating by using the refresh token.

How It Works

1. Send a POST request to /configuration-management/client/api/v1/auth/refresh-token with your refresh token in the request body.
2. Receive a new access token in the response.
3. Replace the expired access token in your API requests with the new one.

Token Endpoints

Step 3: Setting Up Webhooks

Webhooks allow our system to automatically notify your application when specific events occur (e.g., when a transaction status changes).

Provide Your Webhook URL

• You must supply a publicly accessible HTTPS endpoint that can receive POST requests from our servers.
• The webhook URL can be specified in the dedicated fields in the requests.

Webhook Trigger

A webhook will be sent for each status change of a payment transaction. This ensures your system always stays in sync with the latest transaction state.

Step 4. Creating New Transactions

Entity	Description
Intent	A container that groups one or more payments representing a user's intention to pay
Payment	An individual transaction representing a transfer of funds as part of an intent
Payment Authorization	A step that confirms the payment method has sufficient funds and reserves the amount for capture
Payment Capturing	The process of collecting the authorized funds and completing the transaction
Auto-Capturing	A feature that automatically captures authorized payments without requiring a separate manual step

Endpoint	Description
POST /processing/api/v1/intents	Initiate the creation of a new intent with payments
PATCH /processing/api/v1/payments/{id}	Initiates a payment status change. Possible values include: CAPTURED, CANCELLED
GET /processing/api/v1/payments/{id}	Retrieve the payment details and its current status

Download high-resolution Payment Status Model