Transferring credit
Learn how to implement credit transfer flow between marketplaces and sellers in VTEX Ads.
Credit transfer is the flow that allows marketplaces to transfer advertising credits to their sellers. This guide details the endpoints that marketplaces must implement and the webhook they must consume to integrate with VTEX Ads.
The Authentication model follows Basic Auth.
Endpoints to be implemented by the marketplace
Authentication: Basic Auth
1. Balance inquiry (GET /checking_account)
-
Purpose: Check the seller's available balance.
-
Query parameters:
seller_id,publisher_id(optional, used only when an entity manages multiple publishers). -
Success response (200 OK):
_10{ "total": "1111.00" }
2. Transfer request (POST /checking_account/transfer)
-
Purpose: Request the transfer of an amount.
-
Request body:
_10{_10"amount": "10.00",_10"seller_id": "SELLER_ID",_10"publisher_id": "PUBLISHER_ID",_10"transfer_identity_id": "uuid"_10} -
Responses:
-
Synchronous (Success):
201 Created_10{_10"transaction_id": "TRANSACTION_ID",_10"status": "success"_10} -
Synchronous (Failure):
400 Bad Request_10{_10"transaction_id": "TRANSACTION_ID",_10"status": "failure",_10"message": "Reason for rejection"_10} -
Asynchronous:
202 Accepted_10{_10"transaction_id": "TRANSACTION_ID",_10"status": "processing"_10}
-
Webhook to be consumed by the marketplace
The marketplace must call the VTEX Ads webhook to notify the final status of each transfer. For the endpoint path, authentication headers, and the full request and response specification, see Notify credit transfer status in the VTEX Ads API reference.
-
Payload:
_10{_10"transaction_id": "TRANSACTION_ID",_10"status": "success"_10}or
_10{_10"transaction_id": "TRANSACTION_ID",_10"status": "failure",_10"message": "Problem description"_10} -
Retry logic: In case of webhook call failure, the marketplace must retry.
-
Expected response:
204 No Content