evenbooks
Sign inStart for free

Online payments

Card and bank payments through Stripe.

Paths are relative to https://evenbooks.org/api/v1. How keys, errors, paging and versions work is in the guide; the whole reference is also an OpenAPI 3.1 document.

Administrator key marks endpoints that need a key with the admin role, Write access those a read-only key can’t call, and Idempotent those that accept an idempotency key.

List online payments

get/processor/charges

Card and ACH payments taken through Stripe, newest first, at most limit (default 50). Filter by invoice or status.

Parameters

  • invoiceIdstring · Uuidquery
  • statusstring · ProcessorChargeStatusquery

    One of: pending processing succeeded failed canceled

  • limitintegerquery

    1–200 · default 50

Response 200

Errors 400 · 401 · 403 · 404 · 409 · 429

Get an online payment

get/processor/charges/{id}

With its refunds and disputes, oldest first.

Parameters

  • idstring (uuid)path · required

Response 200

ProcessorChargeDetailDto

  • idstring
  • providerstring · ProcessorProvider

    One of: stripe

  • providerPaymentIntentIdstring or null
  • providerChargeIdstring or null
  • invoiceIdstring or null
  • invoiceNumberstring or null
  • contactIdstring or null
  • contactNamestring or null
  • originstring

    One of: evenbooks external

  • methodstring

    One of: card ach unknown

  • statusstring · ProcessorChargeStatus

    One of: pending processing succeeded failed canceled

  • currencystring
  • amountstring · DecimalString
  • processorFeestring · DecimalString
  • platformFeestring · DecimalString
  • platformFeeRefundedstring · DecimalString
  • amountRefundedstring · DecimalString
  • amountDisputedstring · DecimalString
  • refundableAmountstring · DecimalString
  • paymentIdstring or null
  • feeJournalEntryIdstring or null
  • payerEmailstring or null
  • descriptionstring or null
  • failureMessagestring or null
  • succeededAtstring or null
  • createdAtstring
  • versioninteger
  • refundsarray of ProcessorRefundDto

    Refunds, disputes and dispute reversals against this payment, oldest first.

Errors 400 · 401 · 403 · 404 · 409 · 429

Refund an online payment

post/processor/charges/{id}/refund
Administrator keyWrite accessIdempotent

Administrators only. Asks Stripe to refund amount (an outbound call; real money leaves the connected account) and records the refund in the books; Evenbooks’ fee is refunded in proportion. Only a settled payment, up to refundableAmount (400 over_allocation). The returned refund has status: failed when Stripe declines it; 502 external_error when Stripe rejects the request. Needs version of the payment from the last read (409 version_conflict otherwise).

Parameters

  • idstring (uuid)path · required

Request body

RefundProcessorChargeInput

Response 200

ProcessorRefundDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Get the Stripe connection

get/processor/connection

The connected Stripe account, its online payment settings and the Stripe balance recorded in the books. Null when Stripe is not connected or was disconnected.

Response 200

GetProcessorConnectionResponse

  • idstring
  • providerstring · ProcessorProvider

    One of: stripe

  • providerAccountIdstring
  • statusstring · ProcessorConnectionStatus

    One of: pending active restricted disconnected

  • chargesEnabledboolean
  • payoutsEnabledboolean
  • detailsSubmittedboolean
  • displayNamestring or null
  • originstring

    One of: created linked

  • linkedBalancestring · DecimalString or null
  • linkedAtstring or null
  • clearingAccountIdstring
  • clearingAccountNamestring
  • feeAccountIdstring
  • feeAccountNamestring
  • payoutBankAccountIdstring or null
  • payoutBankAccountNamestring or null
  • allowCardboolean
  • allowAchboolean
  • allowPartialboolean
  • minimumPaymentstring · DecimalString
  • autoPostPayoutsboolean
  • lastEventAtstring or null
  • lastErrorstring or null
  • dashboardUrlstring
  • platformFeePlatformFeeDto
  • clearingBalancestring · DecimalString
  • versioninteger
  • createdAtstring

Errors 400 · 401 · 403 · 404 · 409 · 429

Change online payment settings

patch/processor/connection
Administrator keyWrite access

Administrators only. Which methods customers may use (card, ACH or both, at least one), partial payments and their minimum, the bank account payouts land in, and whether payouts post automatically. Omitted fields stay as they are. Needs version from the last read (409 version_conflict otherwise).

Request body

UpdateProcessorConnectionInput

  • versionintegerrequired
  • payoutBankAccountIdstring · Uuid or null
  • allowCardboolean
  • allowAchboolean
  • allowPartialboolean
  • minimumPaymentstring · NonNegativeDecimalString
  • autoPostPayoutsboolean

Response 200

ProcessorConnectionDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Disconnect Stripe

post/processor/connection/disconnect
Administrator keyWrite access

Administrators only. Customers can no longer pay invoices online. The Stripe account stays the company’s, and Stripe events for it keep posting so the books stay complete. Needs version from the last read (409 version_conflict otherwise). Returns the connection as it was disconnected; GET /processor/connection returns null afterwards.

Request body

PostProcessorConnectionDisconnectBody

  • versionintegerrequired

Response 200

ProcessorConnectionDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Refresh the Stripe connection

post/processor/connection/refresh
Administrator keyWrite access

Administrators only. Reads the account’s status and whether it can take charges and receive payouts from Stripe (an outbound call), for example after onboarding.

Response 200

ProcessorConnectionDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

List Stripe payouts

get/processor/payouts

The 50 most recent payouts from Stripe to the bank, latest arrival date first, with the journal entry each posted.

Response 200

Errors 400 · 401 · 403 · 404 · 409 · 429

Schemas

The types these endpoints take or return, by name. Type names above link here.

DecimalString

decimal string

string

up to 32 characters · pattern ^-?\d+(\.\d+)?$

IdempotencyKey

string

8–128 characters

NonNegativeDecimalString

string

up to 32 characters · pattern ^\d+(\.\d+)?$

PlainDateString

string

pattern ^\d{4}-\d{2}-\d{2}$

PlatformFeeDto

  • planstring

    One of: free paid

  • cardTotalPercentstring
  • achTotalPercentstring

PositiveDecimalString

string

ProcessorChargeDto

  • idstring
  • providerstring · ProcessorProvider

    One of: stripe

  • providerPaymentIntentIdstring or null
  • providerChargeIdstring or null
  • invoiceIdstring or null
  • invoiceNumberstring or null
  • contactIdstring or null
  • contactNamestring or null
  • originstring

    One of: evenbooks external

  • methodstring

    One of: card ach unknown

  • statusstring · ProcessorChargeStatus

    One of: pending processing succeeded failed canceled

  • currencystring
  • amountstring · DecimalString
  • processorFeestring · DecimalString
  • platformFeestring · DecimalString
  • platformFeeRefundedstring · DecimalString
  • amountRefundedstring · DecimalString
  • amountDisputedstring · DecimalString
  • refundableAmountstring · DecimalString
  • paymentIdstring or null
  • feeJournalEntryIdstring or null
  • payerEmailstring or null
  • descriptionstring or null
  • failureMessagestring or null
  • succeededAtstring or null
  • createdAtstring
  • versioninteger

ProcessorChargeStatus

string

One of: pending processing succeeded failed canceled

ProcessorConnectionDto

  • idstring
  • providerstring · ProcessorProvider

    One of: stripe

  • providerAccountIdstring
  • statusstring · ProcessorConnectionStatus

    One of: pending active restricted disconnected

  • chargesEnabledboolean
  • payoutsEnabledboolean
  • detailsSubmittedboolean
  • displayNamestring or null
  • originstring

    One of: created linked

  • linkedBalancestring · DecimalString or null
  • linkedAtstring or null
  • clearingAccountIdstring
  • clearingAccountNamestring
  • feeAccountIdstring
  • feeAccountNamestring
  • payoutBankAccountIdstring or null
  • payoutBankAccountNamestring or null
  • allowCardboolean
  • allowAchboolean
  • allowPartialboolean
  • minimumPaymentstring · DecimalString
  • autoPostPayoutsboolean
  • lastEventAtstring or null
  • lastErrorstring or null
  • dashboardUrlstring
  • platformFeePlatformFeeDto
  • clearingBalancestring · DecimalString
  • versioninteger
  • createdAtstring

ProcessorConnectionStatus

string

One of: pending active restricted disconnected

ProcessorPayoutDto

  • idstring
  • providerPayoutIdstring
  • statusstring

    One of: pending in_transit paid failed canceled

  • currencystring
  • amountstring · DecimalString
  • arrivalDatestring · PlainDateString
  • descriptionstring or null
  • bankAccountIdstring or null
  • bankAccountNamestring or null
  • journalEntryIdstring or null
  • reversalEntryIdstring or null
  • failureMessagestring or null
  • createdAtstring

ProcessorProvider

string

One of: stripe

ProcessorRefundDto

  • idstring
  • chargeIdstring
  • providerRefundIdstring or null
  • providerDisputeIdstring or null
  • kindstring

    One of: refund dispute dispute_reversal

  • originstring

    One of: evenbooks external

  • statusstring

    One of: pending succeeded failed canceled

  • amountstring · DecimalString
  • feeAmountstring · DecimalString
  • platformFeeRefundedstring · DecimalString
  • reasonstring or null
  • disputeStatusstring or null
  • refundIdstring or null
  • paymentIdstring or null
  • failureMessagestring or null
  • createdAtstring

Uuid

string (uuid)