Direct store API

01Architecture

The flow has two mandatory calls from the store to Cashbanx, always in this order: the order notification and, after it, the status update to completed or canceled.

1. A Cashbanx page specific to the partner offers a link to the store's site. That link carries the click identifier — a value in the format hub_<number>, delivered in a URL parameter whose name is agreed with each store at onboarding.
2. On click, a new tab opens the store's site. E.g.: https://www.paginadolojaxpto.com.br/?token=hub_1234567
3. At the store's site the customer picks the products and places the order. The store must keep the click identifier received in the URL and associate it with the order.
4. Once the order is confirmed, the store notifies Cashbanx (purchase-made), returning the click identifier in the click_id field. At that moment Cashbanx tells Esfera, which e-mails the customer about the purchase. The order starts out pending: no points are released yet.
5. After the statutory cancellation window and the agreement with the Cashbanx commercial team, the store updates the order status (confirm-purchase) — completed or canceled.

Who calculates the points

The store reports the order amount; Cashbanx is what calculates the points, from the commission recorded in the store's registration and from the programme rule. The points field of the notification is informational: it is stored alongside the order, but it does not determine what the customer receives.

02Environments

Every endpoint in this document is published under the /api prefix. Replace {cashbanx_url} with the host of the environment:

03Credentials and identification

Cashbanx hands the store, per environment:

• client_id and client_secret — used only to obtain the access token. The client_secret is shown once, at creation; if lost, it is replaced by a new one, never recovered.
• partner_id — the store's identifier in the Cashbanx registration, sent in the body of both calls.

The credential is what determines the store and the programme the order will be booked into. The partner_id sent in the body must be exactly the one of the credential in use; any other value is refused with partner not found. No field in the body changes where the order is booked.

04Authentication

OAuth 2.0, client_credentials flow. The token is valid for 30 minutes (expires_in: 1800) and must be reused while it lasts — request a new one only when the previous has expired.

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

200 · success

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800,
  "token_type": "bearer"
}

The client_credentials flow issues neither refresh_token nor refresh_expires_in (RFC 6749, §4.4.3): the store already holds the credentials and requests a new token when it needs one. The encrypted parameter is not accepted.

4xx · error — the error body always has the same shape:

{ "errorCode": "invalid_client", "errorMessage": "client_id or client_secret is incorrect" }

05API · Order notification

Reports that an order was placed. The order is recorded as pending and awaits the status update described in section 06.

Authorization: Bearer {access_token}
Content-Type: application/json

Example request

{
  "customer_id": "01245678901",
  "customer_id_type": "CPF",
  "customer_name": "João da Silva",
  "customer_mail": "joaodasilva@hotmail.com",
  "customer_phone": "11999999999",
  "click_id": "hub_1234567",
  "partner_id": "ABC",
  "campaign_id": "DEFG1234",
  "order_id": "1234567891",
  "order_date": "2026-01-01",
  "points": 100,
  "order_total": 100.50,
  "order_item_quantity": 1,
  "order_item_sku": "0987654321",
  "address_street": "Rua XPTO",
  "address_number": "200",
  "address_complement": "AP 100",
  "address_city": "São Paulo",
  "address_uf": "SP",
  "address_country": "Brasil"
}

200 · success

{ "message": "Purchase received." }

06API · Order update

Completes or cancels an order notified earlier. This is the call that releases or cancels the customer's points.

Authorization: Bearer {access_token}
Content-Type: application/json

Order completed · releases the points

{
  "partner_id": "ABC",
  "order_id": "1234567891",
  "order_status": "COMPLETED",
  "order_date": "2026-01-01",
  "order_update_date": "2026-02-15",
  "status_description": "Order delivered"
}

{ "message": "Confirmed order." }

Order canceled · does not release the points

{
  "partner_id": "ABC",
  "order_id": "1234567891",
  "order_status": "CANCELED",
  "order_update_date": "2026-02-15",
  "status_description": "Canceled for a specific reason"
}

{ "message": "Order canceled." }

07Transactional e-mails

When the store notifies that the order was placed, Cashbanx tells Esfera so that it can communicate with the customer by e-mail. Esfera is what sends the e-mail, not Cashbanx.

Subject: "Você vai ganhar pontos na Esfera!" — You are going to earn Esfera points!

08Integration notes

• Resending after a timeout is safe. The order_id is the idempotency key: a resent notification answers order_id duplicated and a second update answers Order already processed. Neither case credits twice.
• There is no negative amount. Refunds and returns are not represented by a negative order_total — the published path is CANCELED, and only while the order has not been updated yet.
• Keep the click_id per order. Reusing an old click identifier on a new order makes the points be calculated at the wrong rate, with nothing flagging the problem.
• Reuse the token through its 30 minutes of validity. Token requests are limited to 20 per minute per client_id.
• A field not published in this document is refused with Bad Request. Send only the published fields.