Spend events

Your users' card transactions. Each is stored once, then processed right after the answer.

Send a spend event

POST/v1/spend-events

Sends one of your user's card transactions: an authorization, an incremental authorization, a clearing, a reversal or a refund. Only clearings earn rewards; authorizations give estimates. The event is stored before the answer, and processed right after it: the reward reaches the user's balance within seconds, and your webhook endpoint usually within seconds, at times a minute or more.

An event's ID is your integrator, the user, the kind and your transaction ID. Sending the same event again is answered as a duplicate and changes nothing, so retry freely; different content under the same ID is a 409. The user must be enrolled first, and occurredAt can't be more than a minute ahead of Gave's clock.

Request Body

application/json

Send a spend event

Request Body

Responses

202The event is stored. `duplicate` is true when this exact event was sent before: nothing changed.

400`InvalidRequest`: the request doesn't match the API. `part` says where: Payload, Query, Params or Headers.

401`Unauthorized`: the `x-api-key` header is missing, or isn't an active key.

403`IntegratorMismatch`: the request names another integrator than the API key's. | `IntegratorSuspended`: your integrator is suspended. Contact Gave.

409`SpendEventConflict`: this event's ID (integrator, user, kind and transaction ID) was already used by an event with different content. Never a duplicate: fix the event or its ID.

422`EventInFuture`: `occurredAt` is more than a minute ahead of Gave's clock. Check the sender's clock and time zone. | `UserNotEnrolled`: enroll the user with `PUT /v1/users/{userId}` first.

429`RateLimited`: too many requests for this key, or too many failed authentications. Retry after `retryAfterSeconds`.

503`Unavailable`: Gave couldn't complete the request right now. Retry the same request, with backoff.